CreateMaskReceiver (FUN)

FUNCTION CreateMaskReceiver : CAA.HANDLE

This function creates a receiver for a specific identifier area. For receiving a message use the returned receiver handle for Read function call. Mask receivers are very similar to Area Receivers (see also RegisterIdArea). The only difference is that CAN ID filtering is not done by range but by bit mask. Inputs cobIdValue and cobIdMask are interpreted as follows:

Value

x: this bit may be either TRUE or FALSE

0: this bit has to be FALSE

1: this bit hat to be TRUE

Mask

Result

In general: The values of the masks activate the evaluation of the value parameters. If the mask value is FALSE the value parameter is ignored.

There are two kind of receivers:

Always Newest Receivers (xAlwaysNewest := TRUE): Receiver holds only the last received message.
Receiver with Queue (xAlwaysNewest := FALSE): Receiver holds messages in chronological order.

Receivers can be also used for Tx loopback. If xTransmitMask is set to FALSE or xTransmitMask and xTransmitValue are set to TRUE CAN messages which are sent via Write will be received (applies to all transmit messages on the CAN interface). Use function IsTransmitMessage to distinguish between receive and transmit messages.

Note

To avoid losing receive messages an application has to read all messages of a receiver each cycle. All messages should be processed and released by FreeMessage afterwards.

Example

VAR
    hDriver : CAA.HANDLE;
    hReceiver : CAA.HANDLE;
    hMsg : CAA.HANDLE;
    ctMsgLeft : CAA.COUNT;
    eError : CL2.ERROR;
END_VAR

//Create a MaskReceiver which receives all messages with CAN ID 16#80.
hReceiver := CL2.CreateMaskReceiver(hDriver := hDriver,
                                    cobIdValue := 16#80, //cobID value
                                    cobIdMask := 16#FFFFFFFF, //cobID mask ==> all bits of value are relevant
                                    xRTRValue := FALSE, //no RTR messages
                                    xRTRMask := TRUE, //activate RTR filter ==> xRTRValue will be checked
                                    x29BitIdValue := FALSE, //no 29 bit CAN messages
                                    x29BitIdMask := TRUE, //activate 29 bit filter ==> x29BitIdValue will be checked
                                    xTransmitValue := FALSE, //only receive messages, no transmit message loopback
                                    xTransmitMask := TRUE, //activate transmit mask filter ==> xTransmitValue will be checked
                                    xAlwaysNewest := FALSE, //FALSE := receiver with queue; TRUE: only newest message
                                    eEvent := CB.EVENT.NO_EVENT, //no receive event
                                    xEnableSyncWindow := FALSE, //not implemented
                                    peError := ADR(eError) //optional pointer to error
);

REPEAT
    //receive a message from hReceiver
    hMsg := CL2.Read(hReceiverId := hReceiver, pctMsgLeft := ADR(ctMsgLeft), peError := ADR(eError));
    IF hMsg <> CAA.gc_hINVALID THEN
        //TODO: Process message (CL2.GetMessageDataPointer, CL2.GetMessageId, ...)
        CL2.FreeMessage(hMsg); //release message
        hMsg := CAA.gc_hINVALID; //to avoid using an already released message
    END_IF
UNTIL ctMsgLeft = 0
END_REPEAT

Optionally, an event can be registered which is triggered upon reception of a corresponding message. A callback function can be registerd via CB.RegisterCallback (CAA Callback library). Use event class CB.EVENT_CLASS.FIELDBUS, event source CB.EVENT_SOURCE.CB_DRIVER and any unassigned event number (see CB.EVENT). Use the same event number for eEvent input. Input variable dwParam of the registered callback function contains the CAN ID of the received message. See CreateSingleIdReceiver for example code.

Note

Event mechanism is not supported on all systems. Futhermore it is not possible to register an event for extended identifiers (29bit).

InOut:

Scope	Name	Type	Comment
Return	CreateMaskReceiver	CAA.HANDLE	new receiver handle or CAA.gc_hINVALID in case of failure
Input	hDriver	CAA.HANDLE	handle of CAN interface
	cobIdValue	CL2I.COBID	CobID value
	cobIdMask	CL2I.COBID	CobID mask
	xRTRValue	BOOL	Value RTR bit; only evaluated if xRTRMask is set to TRUE
	xRTRMask	BOOL	Mask RTR bit
	x29BitIdValue	BOOL	Value 29 Bit Id; only evaluated if x29BitIdMask is set to TRUE
	x29BitIdMask	BOOL	Mask 29 Bit Id
	xTransmitValue	BOOL	Value Transmit message; only evaluated if xTransmitMask is set to TRUE
	xTransmitMask	BOOL	Mask Transmit message
	xAlwaysNewest	BOOL	TRUE: returns only the newest message; FALSE: receiver with queue.
	eEvent	CB.EVENT	trigger event when message received
	xEnableSyncWindow	BOOL	use SYNC window: not implemented ==> do not care
	peError	POINTER TO ERROR	optional pointer to error enum