`CreateIdAreaReceiver` (FUN)

FUNCTION CreateIdAreaReceiver : CAA.HANDLE

This function creates a receiver to which several identifier areas may be added using the function RegisterIdArea. This receiver type is used if messages within a specific cobID area should be received. For receiving a message use the returned receiver handle for Read function call. 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.

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.

Note

Current implementation of this receiver type does not support 29 bit identifiers.

Example

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

//Create an IdAreaReceiver
hReceiver := CL2.CreateIdAreaReceiver(hDriver := hDriver, //driver handle
                                      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
);

IF hReceiver <> CAA.gc_hINVALID THEN
    //Add an area for CANopen Emergency messages (cobId 16#81-16#9F)
    CL2.RegisterIdArea(hReceiverId := hReceiver, //receiver
                       cobIdStart := 16#81, //start cobID
                       cobIdEnd := 16#9F, //end cobID
                       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
    );
END_IF

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	`CreateIdAreaReceiver`	`CAA.HANDLE`	new receiver handle or `CAA.gc_hINVALID` in case of failure
Input	`hDriver`	`CAA.HANDLE`	handle of CAN interface
	`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

CreateIdAreaReceiver (FUN)

`CreateIdAreaReceiver` (FUN)