Fragmented message support for EZSP Hosts. Splits long messages into smaller blocks for transmission and reassembles received blocks. See Message Fragmentation for documentation.

DeprecatedThe fragment library is deprecated and will be removed in a future release. Similar functionality is available in the Fragmentation plugin in Application Framework.

License#

Copyright 2018 Silicon Laboratories Inc. www.silabs.com

The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code. 

/***************************************************************************/
void ezspFragmentInit(uint16_t receiveBufferLength, uint8_t *receiveBuffer);

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

EmberStatus ezspFragmentSourceRouteHandler(void);

bool ezspFragmentMessageSent(EmberApsFrame *apsFrame, EmberStatus status);

void ezspFragmentMessageSentHandler(EmberStatus status);

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

void ezspFragmentTick(void);

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#

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.

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.

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
ezspFragmentTick(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