PassThruStartMsgFilter v4.04 v5.0

Setting up a message filter

Last updated: January 11, 2026

Description

Before you can start receiving or transmitting messages, you must set up message filters. If no filter is set, all messages are blocked. For the ISO 15765 protocol, only one filter type is available, FLOW_CONTROL_FILTER. It must not be set for other protocols. For each ChannelID you can create up to 16 FLOW_CONTROL_FILTER filters and up to 10 PASS_FILTER or BLOCK_FILTER filters. For each selected filter type you must specify the filter parameters. For FLOW_CONTROL_FILTER, you specify three parameters: pMaskMsg, pPatternMsg, pFlowControlMsg. For PASS_FILTER or BLOCK_FILTER, you specify two parameters: pMaskMsg and pPatternMsg. The parameter length can be from 1 to 12 bytes.

long PassThruStartMsgFilter(unsigned long ChannelID, unsigned long FilterType, PASSTHRU_MSG *pMaskMsg, PASSTHRU_MSG *pPatternMsg, PASSTHRU_MSG *pFlowControlMsg, unsigned long *FilterID)

Parameters

unsigned long ChannelID - The channel identifier saved when the connection was established with the PassThruConnect command.

unsigned long FilterType - The filter type.

Constant name	Description
PASS_FILTER	If the filter conditions defined by the filter parameters are met, the message is passed through. This filter is not valid for ISO 15765 protocols.
BLOCK_FILTER	If the filter conditions defined by the filter parameters are met, the message is blocked. This filter is not valid for ISO 15765 protocols.
FLOW_CONTROL_FILTER	If the filter conditions defined by the filter parameters are met, the message is passed through. This filter is valid only for ISO 15765 protocols.

PASSTHRU_MSG* pMaskMsg - Pointer to the filter mask. The mask is applied with AND to the message, starting from the first byte of the header.
PASSTHRU_MSG* pPatternMsg - Pointer to the pattern. It is compared against the message to which the mask has been applied. If the header does not match, the filter condition is considered not met, and depending on the filter type the message is blocked or passed through.
PASSTHRU_MSG* pFlowControlMsg - Pointer to the Flow control parameter. Used only for the ISO15765 protocol. This parameter specifies the header used to transmit the FlowControl frame within a segmented message. It is usually set equal to the CANID of the diagnostic tester.
unsigned long* FilterID, - Returned pointer to the filter that was set. Required later to remove the filter.

In the ISO 15765 protocol there are standard and extended messages. A standard message uses 4 bytes for the header, an extended message uses 5 bytes. The extended header is used, for example, in the Toyota BCM or in BMW ECUs.

Return error codes

Code	Description	Possible causes and solutions
STATUS_NOERROR	Function completed successfully	—
ERR_DEVICE_NOT_CONNECTED	No connection to the adapter	The adapter is turned off or out of range Solution: check the adapter power and the network connection
ERR_INVALID_DEVICE_ID	Invalid device identifier	DeviceID was not obtained through PassThruOpen or the device is already closed Solution: make sure PassThruOpen completed successfully
ERR_INVALID_CHANNEL_ID	Invalid channel identifier	ChannelID was not obtained through PassThruConnect or the channel is already closed Solution: make sure PassThruConnect completed successfully
ERR_INVALID_MSG	Invalid message structure	Invalid structure in pMaskMsg, pPatternMsg or pFlowControlMsg The messages have different TxFlags or DataSize Solution: verify that the ProtocolID, DataSize and TxFlags fields are correct in all messages
ERR_NULL_PARAMETER	NULL was passed instead of a required pointer	pMaskMsg, pPatternMsg or FilterID is NULL Solution: pass valid pointers to the structures
ERR_NOT_UNIQUE	The CAN ID is already used in another FLOW_CONTROL_FILTER	The CAN ID in pPatternMsg or pFlowControlMsg matches the ID in an existing filter Solution: remove the existing filter or use a different CAN ID
ERR_EXCEEDED_LIMIT	Filter limit exceeded	The maximum has been reached: 16 FLOW_CONTROL_FILTER or 10 PASS/BLOCK_FILTER per channel Solution: remove unused filters with PassThruStopMsgFilter
ERR_MSG_PROTOCOL_ID	Protocol mismatch	The ProtocolID in the filter messages does not match the channel protocol Solution: use the same ProtocolID that was specified in PassThruConnect
ERR_FAILED	Undefined error	Internal error in the library or the adapter Solution: call `PassThruGetLastError()` to get a description

Examples

ISO15765 protocol (CAN)

C/C++ example

#include "j2534_lib.hpp"

// ... ChannelID obtained from PassThruConnect ...

PASSTHRU_MSG MaskMsg, PatternMsg, FlowControlMsg;
unsigned long FilterID;
long Ret;

// Mask: compare the first 4 bytes (CAN ID)
MaskMsg.ProtocolID = ISO15765;
MaskMsg.DataSize = 4;
memset(MaskMsg.Data, 0xFF, 4);

// Pattern: accept messages with CAN ID 0x7E8
PatternMsg.ProtocolID = ISO15765;
PatternMsg.DataSize = 4;
PatternMsg.Data[0] = 0x00;
PatternMsg.Data[1] = 0x00;
PatternMsg.Data[2] = 0x07;
PatternMsg.Data[3] = 0xE8;

// FlowControl response: send to CAN ID 0x7E0
FlowControlMsg.ProtocolID = ISO15765;
FlowControlMsg.DataSize = 4;
FlowControlMsg.Data[0] = 0x00;
FlowControlMsg.Data[1] = 0x00;
FlowControlMsg.Data[2] = 0x07;
FlowControlMsg.Data[3] = 0xE0;

Ret = PassThruStartMsgFilter(ChannelID, FLOW_CONTROL_FILTER,
                             &MaskMsg, &PatternMsg, &FlowControlMsg, &FilterID);
if (Ret != STATUS_NOERROR)
{
    // Error handling
}

Kotlin example (Android)

// channelID obtained earlier from ptConnect
val mask = PassThruMsg(
    protocolID = ISO15765,
    dataSize = 4,
    txFlags = ISO15765_FRAME_PAD,
    // Mask for the CAN ID (compare all 4 bytes)
    data = byteArrayOf(0xFF.toByte(), 0xFF.toByte(), 0xFF.toByte(), 0xFF.toByte())
)
val pattern = PassThruMsg(
    protocolID = ISO15765,
    dataSize = 4,
    txFlags = ISO15765_FRAME_PAD,
    // Accept responses from the ECU with CAN ID 0x7E8
    data = byteArrayOf(0x00, 0x00, 0x07, 0xE8.toByte())
)
val flowControl = PassThruMsg(
    protocolID = ISO15765,
    dataSize = 4,
    txFlags = ISO15765_FRAME_PAD,
    // Send FlowControl to CAN ID 0x7E0
    data = byteArrayOf(0x00, 0x00, 0x07, 0xE0.toByte())
)

val resFilter = j2534.ptStartMsgFilter(channelID, FLOW_CONTROL_FILTER, mask, pattern, flowControl)
if (resFilter.status == STATUS_NOERROR) {
    val filterID = resFilter.filterId
    // Filter set successfully
    Log.i("J2534", "FLOW_CONTROL_FILTER filter set, ID: $filterID")
} else {
    // Error handling
    Log.e("J2534", "Filter setup error: ${resFilter.status}")
}

Python example

from ctypes import *

# channelID obtained earlier from PassThruConnect

# Create the message structures
mask = PASSTHRU_MSG()
mask.ProtocolID = ISO15765
mask.DataSize = 4
mask.Data[0:4] = [0xFF, 0xFF, 0xFF, 0xFF]

pattern = PASSTHRU_MSG()
pattern.ProtocolID = ISO15765
pattern.DataSize = 4
pattern.Data[0:4] = [0x00, 0x00, 0x07, 0xE8]

flow_control = PASSTHRU_MSG()
flow_control.ProtocolID = ISO15765
flow_control.DataSize = 4
flow_control.Data[0:4] = [0x00, 0x00, 0x07, 0xE0]

filter_id = c_ulong()
ret = j2534.PassThruStartMsgFilter(
    channel_id, FLOW_CONTROL_FILTER,
    byref(mask), byref(pattern), byref(flow_control), byref(filter_id)
)
if ret == 0:  # STATUS_NOERROR
    print(f"Filter set, ID: {filter_id.value}")
else:
    print(f"Error: {ret}")

C# example

// channelID obtained earlier from PassThruConnect

var mask = new PASSTHRU_MSG {
    ProtocolID = ISO15765,
    DataSize = 4,
    Data = new byte[] { 0xFF, 0xFF, 0xFF, 0xFF }
};

var pattern = new PASSTHRU_MSG {
    ProtocolID = ISO15765,
    DataSize = 4,
    Data = new byte[] { 0x00, 0x00, 0x07, 0xE8 }
};

var flowControl = new PASSTHRU_MSG {
    ProtocolID = ISO15765,
    DataSize = 4,
    Data = new byte[] { 0x00, 0x00, 0x07, 0xE0 }
};

uint filterId;
int ret = J2534.PassThruStartMsgFilter(
    channelId, FLOW_CONTROL_FILTER,
    ref mask, ref pattern, ref flowControl, out filterId
);
if (ret == 0) // STATUS_NOERROR
{
    Console.WriteLine($"Filter set, ID: {filterId}");
}

ISO14230 protocol (K-Line)

C/C++ example

#include "j2534_lib.hpp"

// ... ChannelID obtained from PassThruConnect ...

PASSTHRU_MSG MaskMsg, PatternMsg;
unsigned long FilterID;
long Ret;

// Mask: compare the first byte (format)
MaskMsg.ProtocolID = ISO14230;
MaskMsg.DataSize = 1;
MaskMsg.Data[0] = 0x80;

// Pattern: pass all messages with the format bit = 1
PatternMsg.ProtocolID = ISO14230;
PatternMsg.DataSize = 1;
PatternMsg.Data[0] = 0x80;

Ret = PassThruStartMsgFilter(ChannelID, PASS_FILTER, &MaskMsg, &PatternMsg, NULL, &FilterID);
if (Ret != STATUS_NOERROR)
{
    // Error handling
}