Message Fragmentation
Application Utilities API Reference

Transmitting

EmberStatus emberFragmentSendUnicast ( EmberOutgoingMessageType type, uint16_t indexOrDestination, EmberApsFrame *apsFrame, EmberMessageBuffer payload, uint8_t maxFragmentSize)
bool emberFragmentMessageSent ( EmberApsFrame *apsFrame, EmberMessageBuffer buffer, EmberStatus status)
void emberFragmentMessageSentHandler ( EmberStatus status)

Receiving

bool emberFragmentIncomingMessage ( EmberApsFrame *apsFrame, EmberMessageBuffer *payload)
void emberFragmentTick (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)
Sends 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 unneccessary, 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.

Detailed Description

Splits long messages into smaller blocks for transmission and reassembles received blocks. See fragment.h for source code.

EMBER_FRAGMENT_WINDOW_SIZE controls how many blocks are sent at a time. EMBER_FRAGMENT_DELAY_MS controls the spacing between blocks.

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

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

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.

Function Documentation

◆ emberFragmentIncomingMessage()

bool emberFragmentIncomingMessage ( EmberApsFrame * apsFrame,
EmberMessageBuffer * payload
)

The application must call this function at the start of its emberIncomingMessageHandler() . 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
apsFrame The APS frame passed to emberIncomingMessageHandler() .
payload The payload passed to emberIncomingMessageHandler() .
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 emberIncomingMessageHandler() . 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.

◆ emberFragmentMessageSent()

bool emberFragmentMessageSent ( EmberApsFrame * apsFrame,
EmberMessageBuffer buffer,
EmberStatus status
)

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

Parameters
apsFrame The APS frame passed to emberMessageSentHandler() .
buffer The buffer passed to emberMessageSentHandler() .
status The status passed to emberMessageSentHandler() .
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 emberMessageSentHandler() . Returns false otherwise. The fragmentation code has not handled the event so the application must continue to process it.

◆ emberFragmentMessageSentHandler()

void emberFragmentMessageSentHandler ( EmberStatus status )

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

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

◆ emberFragmentSendUnicast()

EmberStatus emberFragmentSendUnicast ( EmberOutgoingMessageType type,
uint16_t indexOrDestination,
EmberApsFrame * apsFrame,
EmberMessageBuffer payload,
uint8_t maxFragmentSize
)

Sends 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
type Specifies the outgoing message type. Must be one of EMBER_OUTGOING_DIRECT , EMBER_OUTGOING_VIA_ADDRESS_TABLE , or EMBER_OUTGOING_VIA_BINDING .
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.
apsFrame The APS frame for the message.
payload The long message to be sent.
maxFragmentSize The message will be broken into blocks no larger than this.
Returns
An EmberStatus value.

◆ emberFragmentTick()

void emberFragmentTick ( void )

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

◆ 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
apsFrame The APS frame passed to ezspIncomingMessageHandler().
sender The sender passed to ezspIncomingMessageHandler().
messageLength A pointer to the message length passed to ezspIncomingMessageHandler().
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.

◆ 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
receiveBufferLength The length of receiveBuffer. Incoming messages longer than this will be dropped.
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() .

◆ 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
apsFrame The APS frame passed to ezspMessageSentHandler().
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.

◆ ezspFragmentMessageSentHandler()

void ezspFragmentMessageSentHandler ( EmberStatus status )

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

Parameters
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 .

◆ ezspFragmentSendUnicast()

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

Sends 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
type Specifies the outgoing message type. Must be one of EMBER_OUTGOING_DIRECT , EMBER_OUTGOING_VIA_ADDRESS_TABLE , or EMBER_OUTGOING_VIA_BINDING .
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.
apsFrame The APS frame for the message.
maxFragmentSize The message will be broken into blocks no larger than this.
messageLength The length of the messageContents parameter in bytes.
messageContents The long message to be sent.
Returns
An EmberStatus value.

◆ 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 unneccessary, and will be deprecated later.

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.

◆ ezspFragmentTick()

void ezspFragmentTick ( void )

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