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#
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#
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.
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.
The fragmentation code calls this application-defined handler when it finishes sending a long message.
Receiving#
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.
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.
| N/A | receiveBufferLength | The length of receiveBuffer. Incoming messages longer than this will be dropped. |
| N/A | receiveBuffer | The buffer used to reassemble incoming long messages. Once the message is complete, this buffer will be passed back to the application by ezspFragmentIncomingMessage(). |
69 of file app/util/zigbee-framework/fragment-host.hTransmitting 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.
| N/A | type | Specifies the outgoing message type. Must be one of EMBER_OUTGOING_DIRECT, EMBER_OUTGOING_VIA_ADDRESS_TABLE, or EMBER_OUTGOING_VIA_BINDING. |
| N/A | indexOrDestination | 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/A | apsFrame | The APS frame for the message. |
| N/A | maxFragmentSize | The message will be broken into blocks no larger than this. |
| N/A | messageLength | The length of the messageContents parameter in bytes. |
| N/A | messageContents | The long message to be sent. |
Returns
An EmberStatus value.
EMBER_INVALID_CALL is returned if messageLength is zero or if the window size (::EZSP_CONFIG_FRAGMENT_WINDOW_SIZE) is zero.
105 of file app/util/zigbee-framework/fragment-host.hezspFragmentSourceRouteHandler#
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.
| 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.
126 of file app/util/zigbee-framework/fragment-host.hezspFragmentMessageSent#
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.
| N/A | apsFrame | The APS frame passed to ezspMessageSentHandler(). |
| N/A | status | 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.
142 of file app/util/zigbee-framework/fragment-host.hezspFragmentMessageSentHandler#
void ezspFragmentMessageSentHandler (EmberStatus status)
The fragmentation code calls this application-defined handler when it finishes sending a long message.
| N/A | status | 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. |
152 of file app/util/zigbee-framework/fragment-host.hReceiving 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.
| N/A | apsFrame | The APS frame passed to ezspIncomingMessageHandler(). |
| N/A | sender | The sender passed to ezspIncomingMessageHandler(). |
| N/A | messageLength | A pointer to the message length passed to ezspIncomingMessageHandler(). |
| N/A | messageContents | 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.
185 of file app/util/zigbee-framework/fragment-host.hezspFragmentTick#
void ezspFragmentTick (void )
Used by the fragmentation code to time incoming blocks. The application must call this function regularly.
| N/A |
194 of file app/util/zigbee-framework/fragment-host.h