Receiving SCOM packets

For maximum flexibility, the SCOM library API supports 3 independent tecniques for receiving packets:

• polling SCOM connection object
• installing single frame handler callback
• using filters

Polling SCOM connection object

By default, the received SCOM frames are stored in the reception queue. The SCOM_GetReceivedFrame function can be used to get the oldest received SCOM frame from this queue. Once the frame is not needed anymore, the user is responsible for unlocking it using SCOM_UnlockFrame, making space for another incoming frames. The following example illustrates this idea:

SCOMFrame* receivedFrame;
while (1) {
    // poll the connection for received frames
    receivedFrame = SCOM_GetReceivedFrame(&mySCOM);
    if (receivedFrame) {
        // Got frame! Do something with it...

        // Once the frame is not needed anymore, unlock it
        SCOM_UnlockFrame(receivedFrame).
    }
}

Frame handler callback

In order to improve the real-time response and provide a central point for brokering received SCOM frames it is possible to install a user callback that will handle all received frames. This callback is a function that will be called each time a new SCOM frame arrives. Please note, that the callback is called from within the SCOM_Proc processing function. Each delay introduced in this callback will delay sending of ACK and further frame reception and transmissions.

A callback function can look like this:

bool myFrameReceptionHandler(SCOMDataLink scom, SCOMFrame *frame)
{
    switch (SCOMFrame_GetType(frame)) {
        case MY_FRAMETYPE_1:
            // indicate that the frame was processed, and should be removed from the reception queue
               return true;
            break;
        case MY_FRAMETYPE_1:
            // indicate that the frame was processed, and should be removed from the reception queue
               return true;
            break;
        // etc...
    }

    // indicate that the frame was NOT processed and should be left in the reception queue
    return false;
}

The result of the handler indicated whether the received frame should be removed completely from the reception queue (result == true) or should be left for further processing (result == false)

To install the handler, simply call SCOM_SetFrameReceptionHandlerFunc :

SCOM_SetFrameReceptionHandlerFunc(&mySCOM, myFrameReceptionHandler);

Using filters

The third method for SCOM frame reception is by using filters. This method is described in detail in chapter Filtering SCOM packets.

Special consideration when receiving multi-frames

In a multi-frame transfer, the receiver receives several frames that it then needs to assemble into a single large payload.

Each SCOM multi-frame transfer is market with a 32-bit identifier called multiId. Each SCOM frame that is a part of the same transfer, carries the same multiId. The multiId from a given frame can be retrieved using SCOMFrame_GetMultiId. In case there are several simultaneous multi-frame transfers ongoing, the multiId can be used to identify each of them.

Each SCOM multi-frame carries a part of the payload. The data offset of each piece is carried within the multi-frame and can be retrieved using SCOMFrame_GetMultiOffset function.

Each SCOM multi-frame also carries information about the total payload size. This information can be retrieved using SCOMFrame_GetTotalPayloadSize.

For example, let's consider that a multi-frame transfer that is supposed to carry 350bytes of payload is split into 2 multi-frames. The first multi-frame received will have:

• some multiId,
• offset equal to 0 (start of payload)
• size equal to the size of the piece (let's say 200bytes)
• totalPayloadSize equal to 350bytes The second multi-frame received will have:
• the same multiId as the first frame (they are both parts of the same transfer)
• offset equal to 200 (start of the second payload piece)
• size equal to 350 - 200 = 150 bytes
• totalPayloadSize equal to 350bytes