OPUS - PassThruStartMsgFilter

Syntax

#include "j2534_v0404.h"

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

Description
The PassThruStartMsgFilter function is used to setup a network protocol filter that will selectively restrict or limit network protocol messages received by the PassThru device. The filter messages will flow from the User Application to the PassThru device. There is a limit of ten filter messages per network layer protocol.
The PassThru device will block all vehicle network receive frames by default, when no filters are defined.
The CLEAR_RX_BUFFER (PassThruIoctl function) command must be used after establishing filters to ensure that the receive queue only contains receive frames that adhere to the filter criteria. The PassThruStartMsgFilter function does not cause existing receive messages to be removed from the PassThru device receive queue.

Parameters
ChannelID - The logical communication channel identifier assigned by the J2534 API/DLL when the communication channel was opened via the PassThruConnect function.
FilterType
PASS_FILTER: PassThru device adds receive messages matching the Mask and Pattern criteria to its receive message queue.
BLOCK_FILTER: PassThru device ignores receive messages matching the Mask and Pattern criteria.
FLOW_CONTROL_FILTER: PassThru device adds receive messages matching the Mask and Pattern criteria to its receive message queue. The PassThru device transmits a flow control message (only for ISO 15765-4) when receiving multi-segmented frames.
pMaskMsg - Pointer to the message structure containing the User Application's mask data. The mask message is applied by the PassThru device to every receive message. The mask is used to isolate the receive message header sections(s) that are of interest to the User Application. A "1" bit value means that the corresponding message bit will be examined; a "0" bit value means that the corresponding message bit will be ignored.
pPatternMsg - Pointer to the message structure containing the User Application’s pattern data. The PassThru device compares the Pattern message to the receive message after it is ANDed with the Mask message.
For a PASS_FILTER if the Pattern message matches the result of received message ANDed with the Mask message, then the PassThru device adds that message to its receive message queue. Otherwise that receive message will be ignored.
For a BLOCK_FILTER if the Pattern message matches the result of received message ANDed with the Mask message, then the PassThru device ignores that message. Otherwise that receive message will be added to the PassThru device receive message queue.
For a FLOW_CONTROL_FILTER if the Pattern message matches the result of received message ANDed with the Mask message, then the PassThru device adds that message to its receive message queue. Otherwise that receive message will be ignored.
Receive message data bytes outside the range of the pattern are not used in the comparison with the Pattern message.
pFlowControlMsg - The FlowControl message is only valid for the FLOW_CONTROL_FILTER and the pFlowControlMsg pointer must be set to NULL for the PASS_FILTER or BLOCK_FILTER.
Pointer to the message structure containing the User Application’s flow control message. The User Application specifies either an 11-bit or 29-bit CAN Identifier and an optional one byte extended CAN Address(used for identifying subnetworks connected to CAN gateways). The 11-bit CAN Identifier must be represented as a 4-byte object with the unused 2 bytes and 5 bits set to zero. The 29-bit CAN Identifier is also represented as a 4-byte object with the 3 unused bits set to zero.
This FlowControl mechanism is ISO15765 specific. The ISO15765-2 protocol is a network layer protocol devised for exchanging datagrams between CAN nodes or between a CAN node and an external PassThru device. The ISO15765-2 protocol defines a segmentation method that allows for large transfers(up to 4095 data bytes) to be segmented or broken into a series of CAN frames(up to 7 data bytes).
The FlowControl mechanism is used in a peer to peer data transfer where the transmitting peer is sending more data than can fit into one CAN frame. The transmitting peer splits the data between multiple CAN frames making the data transfer multi-framed or multi-segmented. The purpose of FlowControl is to allow the receiving peer to regulate the rate at which frames are sent by the transmitting peer. The receiving peer’s FlowControl message contains a BlockSize and SeparationTime parameters, which are used by the transmitting peer to shape its data transfer into consecutive frame bursts. The BlockSize is the number of consecutive frames that can be sent in a burst before waiting for the next FlowControl message. The SeparationTime is the minimum time to pause between transmitting consecutive frames.
The FlowControl message is transmitted by the PassThru device when the receive message ANDed with the Mask message matches the Pattern message and the receive message type is FirstFrame or the receive message type is ConsecutiveFrame and the receive frame is the last frame of the consecutive frame burst. FlowControl message filtering occurs only on the CAN Identifier portion of the CAN frame.
The User Application specifies the CAN Identifier (either 11-bit or 29-bit) and the extended address byte (if configured) for the FlowControl message. Extended addressing is configured by PassThruConnect(Flags, option ISO15765_ADDR_TYPE) or configured by PassThruWriteMsgs (TxFlags, option ISO15765_ADDR_TYPE in PASSTHRU_MSG structure).
The PassThru device will supply the Protocol Control Information (PCI) bytes for the FlowControl message. The PCI data includes message type (FlowControl, FirstFrame and ConsecutiveFrame) and associated message specific parameters FlowStatus(ContinueToSend, Wait or Overflow), BlockSize and SeparationTime minimum. The PassThru device will use the default BlockSize (0, FlowControl frames not used) and SeparationTimeMin (0, no time pause between consecutive frames) values or use BS and STmin set by the User Application through the PassThruIoctl function(SET_CONFIG).
Refer to Appendix A (page 64) of SAE J2534-1 for a detailed description of the flow control filter.
MsgID - Pointer to the variable that receives the handle to the message filter. The returned handle is used as an argument to PassThruStopMsgFilter to identify a specific message filter.