`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

0

1

0

1

x: this bit may be either TRUE or FALSE

0: this bit has to be FALSE

1: this bit hat to be TRUE

Mask

0

1

Result

X

0

1

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

CreateMaskReceiver (FUN)

`CreateMaskReceiver` (FUN)