APIs for mailbox client. More...

Functions
EmberAfMailboxStatus	emberAfPluginMailboxClientMessageSubmit ( EmberNodeId mailboxServer, EmberNodeId messageDestination, uint8_t *message, EmberMessageLength messageLength, uint8_t tag, bool useSecurity)
	Submit a data message to a mailbox server. If this API returns an EmberAfMailboxStatus value of EMBER_MAILBOX_STATUS_SUCCESS , the corresponding asynchronous callback emberAfPluginMailboxClientMessageSubmitCallback() will be invoked to indicate whether the message was successfully submitted to the mailbox server or to inform the application of the reason of failure. More...

EmberAfMailboxStatus	emberAfPluginMailboxClientCheckInbox ( EmberNodeId mailboxServer, bool useSecurity)
	Query a mailbox server for pending messages. If this API returns an EmberAfMailboxStatus value of EMBER_MAILBOX_STATUS_SUCCESS , the corresponding asynchronous callback emberAfPluginMailboxClientCheckInboxCallback() will be invoked either to provide the retrieved message or to indicate the reason for failure. More...

Callbacks
void	emberAfPluginMailboxClientMessageSubmitCallback ( EmberAfMailboxStatus status, EmberNodeId mailboxServer, EmberNodeId messageDestination, uint8_t tag)
	Mailbox Client Message Submit Callback. More...

void	emberAfPluginMailboxClientMessageDeliveredCallback ( EmberAfMailboxStatus status, EmberNodeId mailboxServer, EmberNodeId messageDestination, uint8_t tag)
	Mailbox Client Message Delivered Callback. More...

void	emberAfPluginMailboxClientCheckInboxCallback ( EmberAfMailboxStatus status, EmberNodeId mailboxServer, EmberNodeId messageSource, uint8_t *message, EmberMessageLength messageLength, uint8_t tag, bool moreMessages)
	Mailbox Client Check Inbox Callback. More...

Detailed Description

APIs for mailbox client.

Mailbox protocol is designed for devices that can't be online on the network all the time. The most common example for this is a sleepy end device.

Mailbox clients and the server can submit messages into the mailbox, which is stored in RAM on the mailbox server. Clients can then query the mailbox server for available messages.

The mailbox server will notify clients who submit messages when a message was delivered or when it couldn't be delivered due to an error.

Mailbox uses a plugin configurable protocol endpoint, which is 15 by default.

The server can also configure the size of the mailbox (in number of packets, 25 by default) and the packet timeout, after which the server drops the message and notifies the source of the error.

The mailbox protocol uses standard data messages, so in case of sleepy end devices, it will use the indirect queue. This means that if a sleepy end device sends a request to a mailbox server, the end device should poll for the response.

Note: Mailbox is not available in MAC mode due to the lack of endpoints.

See mailbox-client.h and mailbox-client.c for source code.

Function Documentation

◆ emberAfPluginMailboxClientCheckInbox()

EmberAfMailboxStatus emberAfPluginMailboxClientCheckInbox	(	EmberNodeId	`mailboxServer,`
		bool	`useSecurity`
	)

Query a mailbox server for pending messages. If this API returns an EmberAfMailboxStatus value of EMBER_MAILBOX_STATUS_SUCCESS , the corresponding asynchronous callback emberAfPluginMailboxClientCheckInboxCallback() will be invoked either to provide the retrieved message or to indicate the reason for failure.

Parameters

[in]	`mailboxServer`	The node ID of the mailbox server.
[in]	`useSecurity`	Set it true if the request command and the responses to it should be sent secured. If a pending message was sent to a server securely, it will be always retrieved securely. This option only affects the request command and the pending messages that were sent without security to the server.

Returns

An EmberAfMailboxStatus value of:

EMBER_MAILBOX_STATUS_SUCCESS if the query command was successfully passed to the network layer to be transmitted to the mailbox server.
EMBER_MAILBOX_STATUS_INVALID_ADDRESS if the passed mailbox server short ID is an invalid address.
EMBER_MAILBOX_STATUS_BUSY if the client is still performing a submit message or a query for message action.
EMBER_MAILBOX_STATUS_STACK_ERROR if the network layer refused the command (the outgoing queue is currently full).

Note: Receiving the emberAfPluginMailboxClientCheckInboxCallback() requires the reception of a mailbox command message, which is only possible by polling if the message was submitted on a EMBER_STAR_SLEEPY_END_DEVICE .

◆ emberAfPluginMailboxClientCheckInboxCallback()

void emberAfPluginMailboxClientCheckInboxCallback	(	EmberAfMailboxStatus	`status,`
		EmberNodeId	`mailboxServer,`
		EmberNodeId	`messageSource,`
		uint8_t *	`message,`
		EmberMessageLength	`messageLength,`
		uint8_t	`tag,`
		bool	`moreMessages`
	)

Mailbox Client Check Inbox Callback.

This callback is invoked after a successful call to the emberAfPluginMailboxClientCheckInbox() API. If a message was retrieved from the mailbox server, this callback passes it to the application. Otherwise, it indicates the reason for failure to the application.

Parameters

[in]	`status`	An EmberAfMailboxStatus value of: EMBER_MAILBOX_STATUS_SUCCESS if a message was retrieved from the mailbox server. EMBER_MAILBOX_STATUS_MESSAGE_NO_DATA if the server has currently no message for this mailbox client. EMBER_MAILBOX_STATUS_MESSAGE_NO_RESPONSE if the client timed-out waiting for a query response from the mailbox server. EMBER_MAILBOX_STATUS_STACK_ERROR if the stack failed to deliver the query message to the mailbox server.
[in]	`mailboxServer`	The node id of the mailbox server responding.
[in]	`messageSource`	The source node ID of the retrieved message. Note that this parameter is meaningful only if the status parameter has an EmberAfMailboxStatus value of EMBER_MAILBOX_STATUS_SUCCESS .
[in]	`message`	A pointer to the retrieved message payload. Note that this parameter is meaningful only if the status parameter has an EmberAfMailboxStatus value of EMBER_MAILBOX_STATUS_SUCCESS .
[in]	`messageLength`	The length in bytes of the retrieved message payload. Note that this parameter is meaningful only if the status parameter has an EmberAfMailboxStatus value of EMBER_MAILBOX_STATUS_SUCCESS .
[in]	`tag`	The tag value passed in the emberAfPluginMailboxClientMessageSubmit() API. Note that this parameter is meaningful only if the status parameter has an EmberAfMailboxStatus value of EMBER_MAILBOX_STATUS_SUCCESS .
[in]	`moreMessages`	This flag is true if the mailbox server has more pending messages for this mailbox client. Note that this parameter is meaningful only if the status parameter has an EmberAfMailboxStatus value of EMBER_MAILBOX_STATUS_SUCCESS .

Note: Receiving this callback requires the reception of a mailbox command message, which is only possible by polling if the message was submitted on a EMBER_STAR_SLEEPY_END_DEVICE .

◆ emberAfPluginMailboxClientMessageDeliveredCallback()

void emberAfPluginMailboxClientMessageDeliveredCallback	(	EmberAfMailboxStatus	`status,`
		EmberNodeId	`mailboxServer,`
		EmberNodeId	`messageDestination,`
		uint8_t	`tag`
	)

Mailbox Client Message Delivered Callback.

A callback that may be invoked on the submitter of the message either if the message that was submitted to a mailbox server reached its final destination or it timed-out. Note that the callback is not always called. If the status message from the server is lost, the callback won't be called.

Parameters

[in]	`status`	An EmberAfMailboxStatus value of: EMBER_MAILBOX_STATUS_SUCCESS indicates that the message was successfully delivered to the final destination. EMBER_MAILBOX_STATUS_MESSAGE_TIMED_OUT indicates that the message timed-out and was removed from the server queue.
[in]	`mailboxServer`	The node ID of the mailbox server where the message was submitted to.
[in]	`messageDestination`	The node ID of the destination.
[in]	`tag`	The tag value passed in the emberAfPluginMailboxClientMessageSubmit() API.

Note: Receiving this callback requires the reception of a mailbox command message, which is only possible by polling if the message was submitted on a EMBER_STAR_SLEEPY_END_DEVICE .

◆ emberAfPluginMailboxClientMessageSubmit()

EmberAfMailboxStatus emberAfPluginMailboxClientMessageSubmit	(	EmberNodeId	`mailboxServer,`
		EmberNodeId	`messageDestination,`
		uint8_t *	`message,`
		EmberMessageLength	`messageLength,`
		uint8_t	`tag,`
		bool	`useSecurity`
	)

Submit a data message to a mailbox server. If this API returns an EmberAfMailboxStatus value of EMBER_MAILBOX_STATUS_SUCCESS , the corresponding asynchronous callback emberAfPluginMailboxClientMessageSubmitCallback() will be invoked to indicate whether the message was successfully submitted to the mailbox server or to inform the application of the reason of failure.

Parameters

[in]	`mailboxServer`	The node ID of the mailbox server.
[in]	`messageDestination`	The node ID of the destination for this data message.
[in]	`message`	A pointer to the message to be sent.
[in]	`messageLength`	The length in bytes of the message to be sent.
[in]	`tag`	A tag value which will be returned in all of the corresponding callbacks: emberAfPluginMailboxClientMessageSubmitCallback() , emberAfPluginMailboxClientMessageDeliveredCallback() and emberAfPluginMailboxClientCheckInboxCallback() . The application can use it to match the callbacks with the call.
[in]	`useSecurity`	Set it true if the data message should be sent to the server using security.

Returns

An EmberAfMailboxStatus value of:

EMBER_MAILBOX_STATUS_SUCCESS if the message was successfully passed to the network layer to be transmitted to the mailbox server.
EMBER_MAILBOX_STATUS_INVALID_CALL if the passed data message is invalid.
EMBER_MAILBOX_STATUS_INVALID_ADDRESS if the server ID or the destination ID is an invalid address.
EMBER_MAILBOX_STATUS_MESSAGE_TOO_LONG if the passed message does not fit in a single mailbox data message.
EMBER_MAILBOX_STATUS_BUSY if the client is still performing a submit message or a query for message action.
EMBER_MAILBOX_STATUS_STACK_ERROR if the network layer refused the message (the outgoing queue is currently full).

Note: Receiving the emberAfPluginMailboxClientMessageSubmitCallback() requires the reception of a mailbox command message, which is only possible by polling if the message was submitted on a EMBER_STAR_SLEEPY_END_DEVICE .

See also: emberAfPluginMailboxServerAddMessage()

◆ emberAfPluginMailboxClientMessageSubmitCallback()

void emberAfPluginMailboxClientMessageSubmitCallback	(	EmberAfMailboxStatus	`status,`
		EmberNodeId	`mailboxServer,`
		EmberNodeId	`messageDestination,`
		uint8_t	`tag`
	)

Mailbox Client Message Submit Callback.

A callback invoked when a message arrived to the mailbox server after a call of emberAfPluginMailboxClientMessageSubmit() .

Parameters

[in]	`status`	An EmberAfMailboxStatus value of: EMBER_MAILBOX_STATUS_SUCCESS if the data message was accepted by the mailbox server. EMBER_MAILBOX_STATUS_STACK_ERROR if the message couldn't be delivered to the mailbox server. EMBER_MAILBOX_STATUS_MESSAGE_NO_RESPONSE if the client timed-out waiting for a response from the server. EMBER_MAILBOX_STATUS_MESSAGE_TABLE_FULL if the mailbox server table is currently full. EMBER_MAILBOX_STATUS_MESSAGE_NO_BUFFERS if the server can't allocate enough memory to store the message.
[in]	`mailboxServer`	The node ID of the mailbox server.
[in]	`messageDestination`	The node ID of the destination.
	`tag`	The tag value passed in the emberAfPluginMailboxClientMessageSubmit() API.

Note: Receiving this callback requires the reception of a mailbox command message, which is only possible by polling if the message was submitted on a EMBER_STAR_SLEEPY_END_DEVICE .

Mailbox Client Plugin Connect Application Framework API Reference

Functions

Callbacks

Detailed Description

Function Documentation

◆ emberAfPluginMailboxClientCheckInbox()

◆ emberAfPluginMailboxClientCheckInboxCallback()

◆ emberAfPluginMailboxClientMessageDeliveredCallback()

◆ emberAfPluginMailboxClientMessageSubmit()

◆ emberAfPluginMailboxClientMessageSubmitCallback()

Mailbox Client Plugin
Connect Application Framework API Reference