All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
AppMessage

Detailed Description

Function Documentation

void app_message_deregister_callbacks ( void  )

Deregisters all callbacks and their context.

void* app_message_get_context ( void  )

Gets the context that will be passed to all AppMessage callbacks.

Returns
The current context on record.
uint32_t app_message_inbox_size_maximum ( void  )

Programatically determine the inbox size maximum in the current configuration.

Returns
The inbox size maximum on this firmware.
See Also
APP_MESSAGE_INBOX_SIZE_MINIMUM
app_message_outbox_size_maximum()
AppMessageResult app_message_open ( const uint32_t  size_inbound,
const uint32_t  size_outbound 
)

Open AppMessage to transfers.

Use dict_calc_buffer_size_from_tuplets() or dict_calc_buffer_size() to estimate the size you need.

Parameters
[in]size_inboundThe required size for the Inbox buffer
[in]size_outboundThe required size for the Outbox buffer
Returns
A result code such as APP_MSG_OK or APP_MSG_OUT_OF_MEMORY.
Note
It is recommended that if the Inbox will be used, that at least the Inbox callbacks should be registered before this call. Otherwise it is possible for an Inbox message to be NACK'ed without being seen by the application.
AppMessageResult app_message_outbox_begin ( DictionaryIterator **  iterator)

Begin writing to the Outbox's Dictionary buffer.

Parameters
[out]iteratorLocation to write the DictionaryIterator pointer. This will be NULL on failure.
Returns
A result code, including but not limited to APP_MSG_OK, APP_MSG_INVALID_ARGS or APP_MSG_BUSY.
Note
After a successful call, one can add values to the dictionary using functions like dict_write_data() and friends.
See Also
Dictionary
AppMessageResult app_message_outbox_send ( void  )

Sends the outbound dictionary.

Returns
A result code, including but not limited to APP_MSG_OK or APP_MSG_BUSY. The APP_MSG_OK code does not mean that the message was sent successfully, but only that the start of processing was successful. Since this call is asynchronous, callbacks provide the final result instead.
See Also
AppMessageOutboxSent
AppMessageOutboxFailed
uint32_t app_message_outbox_size_maximum ( void  )

Programatically determine the outbox size maximum in the current configuration.

Returns
The outbox size maximum on this firmware.
See Also
APP_MESSAGE_OUTBOX_SIZE_MINIMUM
app_message_inbox_size_maximum()
AppMessageInboxDropped app_message_register_inbox_dropped ( AppMessageInboxDropped  dropped_callback)

Registers a function that will be called after any Inbox message is received but dropped by the system.

Only one callback may be registered at a time. Each subsequent call to this function will replace the previous callback. The callback is optional; setting it to NULL will deregister the current callback and no function will be called anymore.

Parameters
[in]dropped_callbackThe callback that will be called going forward; NULL to not have a callback.
Returns
The previous callback (or NULL) that was on record.
AppMessageInboxReceived app_message_register_inbox_received ( AppMessageInboxReceived  received_callback)

Registers a function that will be called after any Inbox message is received successfully.

Only one callback may be registered at a time. Each subsequent call to this function will replace the previous callback. The callback is optional; setting it to NULL will deregister the current callback and no function will be called anymore.

Parameters
[in]received_callbackThe callback that will be called going forward; NULL to not have a callback.
Returns
The previous callback (or NULL) that was on record.
AppMessageOutboxFailed app_message_register_outbox_failed ( AppMessageOutboxFailed  failed_callback)

Registers a function that will be called after any Outbox message is not sent with a timely ACK reply. The call to app_message_outbox_send() must have succeeded.

Only one callback may be registered at a time. Each subsequent call to this function will replace the previous callback. The callback is optional; setting it to NULL will deregister the current callback and no function will be called anymore.

Parameters
[in]failed_callbackThe callback that will be called going forward; NULL to not have a callback.
Returns
The previous callback (or NULL) that was on record.
AppMessageOutboxSent app_message_register_outbox_sent ( AppMessageOutboxSent  sent_callback)

Registers a function that will be called after any Outbox message is sent and an ACK reply occurs in a timely fashion.

Only one callback may be registered at a time. Each subsequent call to this function will replace the previous callback. The callback is optional; setting it to NULL will deregister the current callback and no function will be called anymore.

Parameters
[in]sent_callbackThe callback that will be called going forward; NULL to not have a callback.
Returns
The previous callback (or NULL) that was on record.
void* app_message_set_context ( void *  context)

Sets the context that will be passed to all AppMessage callbacks.

Parameters
[in]contextThe context that will be passed to all AppMessage callbacks.
Returns
The previous context that was on record.

Typedef Documentation

typedef void(* AppMessageInboxDropped)(AppMessageResult reason, void *context)

Called after an incoming message is dropped.

Parameters
[in]resultThe reason why the message was dropped. Some possibilities include APP_MSG_BUSY and APP_MSG_BUFFER_OVERFLOW.
[in]contextPointer to application data as specified when registering the callback.
typedef void(* AppMessageInboxReceived)(DictionaryIterator *iterator, void *context)

Called after an incoming message is received.

Parameters
[in]iteratorThe dictionary iterator to the received message. Never NULL. Note that the iterator cannot be modified or saved off. The library may need to re-use the buffered space where this message is supplied. Returning from the callback indicates to the library that the received message contents are no longer needed or have already been externalized outside its buffering space and iterator.
[in]contextPointer to application data as specified when registering the callback.
typedef void(* AppMessageOutboxFailed)(DictionaryIterator *iterator, AppMessageResult reason, void *context)

Called after an outbound message has not been sent successfully.

Parameters
[in]iteratorThe dictionary iterator to the sent message. The iterator will be in the final state that was sent. Note that the iterator cannot be modified or saved off as the library will re-open the dictionary with dict_begin() after this callback returns.
[in]resultThe result of the operation. Some possibilities for the value include APP_MSG_SEND_TIMEOUT, APP_MSG_SEND_REJECTED, APP_MSG_NOT_CONNECTED, APP_MSG_APP_NOT_RUNNING, and the combination (APP_MSG_NOT_CONNECTED | APP_MSG_APP_NOT_RUNNING).
contextPointer to application data as specified when registering the callback.
typedef void(* AppMessageOutboxSent)(DictionaryIterator *iterator, void *context)

Called after an outbound message has been sent and the reply has been received.

Parameters
[in]iteratorThe dictionary iterator to the sent message. The iterator will be in the final state that was sent. Note that the iterator cannot be modified or saved off as the library will re-open the dictionary with dict_begin() after this callback returns.
[in]contextPointer to application data as specified when registering the callback.

Enumeration Type Documentation

AppMessage result codes.

Enumerator
APP_MSG_OK 

All good, operation was successful.

APP_MSG_SEND_TIMEOUT 

The other end did not confirm receiving the sent data with an (n)ack in time.

APP_MSG_SEND_REJECTED 

The other end rejected the sent data, with a "nack" reply.

APP_MSG_NOT_CONNECTED 

The other end was not connected.

APP_MSG_APP_NOT_RUNNING 

The local application was not running.

APP_MSG_INVALID_ARGS 

The function was called with invalid arguments.

APP_MSG_BUSY 

There are pending (in or outbound) messages that need to be processed first before new ones can be received or sent.

APP_MSG_BUFFER_OVERFLOW 

The buffer was too small to contain the incoming message.

APP_MSG_ALREADY_RELEASED 

The resource had already been released.

APP_MSG_CALLBACK_ALREADY_REGISTERED 

The callback node was already registered, or its ListNode has not been initialized.

APP_MSG_CALLBACK_NOT_REGISTERED 

The callback could not be deregistered, because it had not been registered before.

APP_MSG_OUT_OF_MEMORY 

The support library did not have sufficient application memory to perform the requested operation.

Macro Definition Documentation

#define APP_MESSAGE_INBOX_SIZE_MINIMUM   124

As long as the firmware maintains its current major version, inboxes of this size or smaller will be allowed.

See Also
app_message_inbox_size_maximum()
APP_MESSAGE_OUTBOX_SIZE_MINIMUM
#define APP_MESSAGE_OUTBOX_SIZE_MINIMUM   636

As long as the firmware maintains its current major version, outboxes of this size or smaller will be allowed.

See Also
app_message_outbox_size_maximum()
APP_MESSAGE_INBOX_SIZE_MINIMUM