Message Fragmentation#

Fragmented message support for EZSP Hosts. Splits long messages into smaller blocks for transmission and reassembles received blocks. See fragment-host.c for source code.

::EZSP_CONFIG_FRAGMENT_WINDOW_SIZE controls how many blocks are sent at a time. ::EZSP_CONFIG_FRAGMENT_DELAY_MS controls the spacing between blocks.

Before calling any of the other functions listed here, the application must call ezspFragmentInit().

To send a long message, the application calls ezspFragmentSendUnicast(). The application must add a call to ezspFragmentMessageSent() at the start of its ezspMessageSentHandler(). If ezspFragmentMessageSent() returns true, the fragmentation code has handled the event and the application must not process it further. The fragmentation code calls the application-defined ezspFragmentMessageSentHandler() when it has finished sending the long message.

To receive a long message, the application must add a call to ezspFragmentIncomingMessage() at the start of its ezspIncomingMessageHandler(). If ezspFragmentIncomingMessage() returns true, the fragmentation code has handled the message and the application must not process it further. The application must also call ezspFragmentTick() regularly.

Initialization#

void
ezspFragmentInit(uint16_t receiveBufferLength, uint8_t *receiveBuffer)

Initialize variables and buffers used for sending and receiving long messages. This functions reads the values of ::EZSP_CONFIG_MAX_HOPS and ::EZSP_CONFIG_FRAGMENT_WINDOW_SIZE. The application must set these values before calling this function.

Transmitting#

ezspFragmentSendUnicast(EmberOutgoingMessageType type, uint16_t indexOrDestination, EmberApsFrame *apsFrame, uint8_t maxFragmentSize, uint16_t messageLength, uint8_t *messageContents)

Send a long message by splitting it into blocks. Only one long message can be sent at a time. Calling this function a second time aborts the first message.

DEPRECATED A callback invoked just before each block of the current long message is sent. Previously, if the message had to be source routed, the application needed this callback and call ezspSetSourceRoute() in it. Since Zigbee 6.7 has removed the host side source route table, this callback deems to be unnecessary, and will be deprecated later.

bool
ezspFragmentMessageSent(EmberApsFrame *apsFrame, EmberStatus status)

The application must call this function at the start of its ezspMessageSentHandler(). If it returns true, the fragmentation code has handled the event and the application must not process it further.

void
ezspFragmentMessageSentHandler(EmberStatus status)

The fragmentation code calls this application-defined handler when it finishes sending a long message.

Receiving#

bool
ezspFragmentIncomingMessage(EmberApsFrame *apsFrame, EmberNodeId sender, uint16_t *messageLength, uint8_t **messageContents)

The application must call this function at the start of its ezspIncomingMessageHandler(). If it returns true, the fragmentation code has handled the message and the application must not process it further. When the final block of a long message is received, this function replaces the message with the reassembled long message and returns false so that the application processes it.

void

Used by the fragmentation code to time incoming blocks. The application must call this function regularly.

Initialization Documentation#

ezspFragmentInit#

void ezspFragmentInit (uint16_t receiveBufferLength, uint8_t * receiveBuffer)

Initialize variables and buffers used for sending and receiving long messages. This functions reads the values of ::EZSP_CONFIG_MAX_HOPS and ::EZSP_CONFIG_FRAGMENT_WINDOW_SIZE. The application must set these values before calling this function.

Parameters
N/AreceiveBufferLength

The length of receiveBuffer. Incoming messages longer than this will be dropped.

N/AreceiveBuffer

The buffer used to reassemble incoming long messages. Once the message is complete, this buffer will be passed back to the application by ezspFragmentIncomingMessage().


Definition at line 69 of file app/util/zigbee-framework/fragment-host.h

Transmitting Documentation#

ezspFragmentSendUnicast#

EmberStatus ezspFragmentSendUnicast (EmberOutgoingMessageType type, uint16_t indexOrDestination, EmberApsFrame * apsFrame, uint8_t maxFragmentSize, uint16_t messageLength, uint8_t * messageContents)

Send a long message by splitting it into blocks. Only one long message can be sent at a time. Calling this function a second time aborts the first message.

Parameters
N/Atype

Specifies the outgoing message type. Must be one of EMBER_OUTGOING_DIRECT, EMBER_OUTGOING_VIA_ADDRESS_TABLE, or EMBER_OUTGOING_VIA_BINDING.

N/AindexOrDestination

Depending on the type of addressing used, this is either the EmberNodeId of the destination, an index into the address table, or an index into the binding table.

N/AapsFrame

The APS frame for the message.

N/AmaxFragmentSize

The message will be broken into blocks no larger than this.

N/AmessageLength

The length of the messageContents parameter in bytes.

N/AmessageContents

The long message to be sent.

Returns


Definition at line 105 of file app/util/zigbee-framework/fragment-host.h

ezspFragmentSourceRouteHandler#

EmberStatus ezspFragmentSourceRouteHandler (void )

DEPRECATED A callback invoked just before each block of the current long message is sent. Previously, if the message had to be source routed, the application needed this callback and call ezspSetSourceRoute() in it. Since Zigbee 6.7 has removed the host side source route table, this callback deems to be unnecessary, and will be deprecated later.

Parameters
N/A

The application must define EZSP_APPLICATION_HAS_FRAGMENT_SOURCE_ROUTE_HANDLER in its configuration header if it defines this callback.

Returns

  • EMBER_SUCCESS if the source route has been set. Any other value will abort transmission of the current long message.


Definition at line 126 of file app/util/zigbee-framework/fragment-host.h

ezspFragmentMessageSent#

bool ezspFragmentMessageSent (EmberApsFrame * apsFrame, EmberStatus status)

The application must call this function at the start of its ezspMessageSentHandler(). If it returns true, the fragmentation code has handled the event and the application must not process it further.

Parameters
N/AapsFrame

The APS frame passed to ezspMessageSentHandler().

N/Astatus

The status passed to ezspMessageSentHandler().

Returns

  • true if the sent message was a block of a long message. The fragmentation code has handled the event so the application must return immediately from its ezspMessageSentHandler(). Returns false otherwise. The fragmentation code has not handled the event so the application must continue to process it.


Definition at line 142 of file app/util/zigbee-framework/fragment-host.h

ezspFragmentMessageSentHandler#

void ezspFragmentMessageSentHandler (EmberStatus status)

The fragmentation code calls this application-defined handler when it finishes sending a long message.

Parameters
N/Astatus

EMBER_SUCCESS if all the blocks of the long message were delivered to the destination, otherwise EMBER_DELIVERY_FAILED, EMBER_NETWORK_DOWN or EMBER_NETWORK_BUSY.


Definition at line 152 of file app/util/zigbee-framework/fragment-host.h

Receiving Documentation#

ezspFragmentIncomingMessage#

bool ezspFragmentIncomingMessage (EmberApsFrame * apsFrame, EmberNodeId sender, uint16_t * messageLength, uint8_t ** messageContents)

The application must call this function at the start of its ezspIncomingMessageHandler(). If it returns true, the fragmentation code has handled the message and the application must not process it further. When the final block of a long message is received, this function replaces the message with the reassembled long message and returns false so that the application processes it.

Parameters
N/AapsFrame

The APS frame passed to ezspIncomingMessageHandler().

N/Asender

The sender passed to ezspIncomingMessageHandler().

N/AmessageLength

A pointer to the message length passed to ezspIncomingMessageHandler().

N/AmessageContents

A pointer to the message contents passed to ezspIncomingMessageHandler().

Returns

  • true if the incoming message was a block of an incomplete long message. The fragmentation code has handled the message so the application must return immediately from its ezspIncomingMessageHandler(). Returns false if the incoming message was not part of a long message. The fragmentation code has not handled the message so the application must continue to process it. Returns false if the incoming message was a block that completed a long message. The fragmentation code replaces the message with the reassembled long message so the application must continue to process it.


Definition at line 185 of file app/util/zigbee-framework/fragment-host.h

ezspFragmentTick#

void ezspFragmentTick (void )

Used by the fragmentation code to time incoming blocks. The application must call this function regularly.

Parameters
N/A

Definition at line 194 of file app/util/zigbee-framework/fragment-host.h