App outbox service

Passes variable-length messages from an app buffer to a kernel service. More...

Data Structures
struct	AppOutboxMessage
	Message sent by an app, as seen by the consuming kernel service. More...

Typedefs
typedef void(*	AppOutboxMessageHandler) (AppOutboxMessage *message)
	Called on the consumer task when a message is added.

Enumerations
enum	AppOutboxServiceTag { AppOutboxServiceTagInvalid = -1 , AppOutboxServiceTagAppMessageSender , NumAppOutboxServiceTag }
	Identifies a kernel consumer and the sent handler permitted for it. More...

Functions
void	app_outbox_service_init (void)
	Initialize the service, once at boot.
void	app_outbox_service_cleanup_all_pending_messages (void)
	Drop all pending messages.
void	app_outbox_service_cleanup_event (PebbleEvent *event)
	Free the message of an unprocessed app outbox event.
bool	app_outbox_service_is_message_cancelled (AppOutboxMessage *message)
	Check whether a message was cancelled.
void	app_outbox_service_register (AppOutboxServiceTag service_tag, AppOutboxMessageHandler message_handler, PebbleTask consumer_task, size_t consumer_data_size)
	Register the consumer of a tag.
void	app_outbox_service_consume_message (AppOutboxMessage *message, AppOutboxStatus status)
	Finish processing a message and free it.
void	app_outbox_service_unregister (AppOutboxServiceTag service_tag)
	Unregister the consumer of a tag.

Detailed Description

Passes variable-length messages from an app buffer to a kernel service.

Apps send with app_outbox_send(). The data is read directly from the app's buffer and the transfer is asynchronous: once the receiving kernel service consumes the message, the sender's sent handler runs on the app task with a simple status. Only a hard-coded set of sent handlers is permitted, each mapping to one service tag, to prevent abuse by misbehaving apps. If no consumer is registered for the tag, the sent handler is called right away with a failure. Several messages may be pending at once. Cancelling a message already added is not supported.

---

Data Structure Documentation

AppOutboxMessage

struct AppOutboxMessage

Message sent by an app, as seen by the consuming kernel service.

Data Fields
void *	cb_ctx	Context passed to sent_handler.
uint8_t	consumer_data[]	Zero-initialized space of the size given to app_outbox_service_register(), for the consumer to keep the state it needs to process the message.
const uint8_t *	data	Message data. It resides in app memory, so its contents must be checked carefully.
size_t	length	Length of data in bytes.
ListNode	node	List node, for internal use.
AppOutboxSentHandler	sent_handler	Called on the app task when the message is consumed.

Typedef Documentation

AppOutboxMessageHandler

typedef void(* AppOutboxMessageHandler) (AppOutboxMessage *message)

Called on the consumer task when a message is added.

Only AppOutboxMessage::consumer_data may be modified by the handler.

Parameters

message

Added message.

Enumeration Type Documentation

AppOutboxServiceTag

enum AppOutboxServiceTag

Identifies a kernel consumer and the sent handler permitted for it.

Enumerator
AppOutboxServiceTagInvalid	Invalid tag.
AppOutboxServiceTagAppMessageSender	App message sender.
NumAppOutboxServiceTag	Number of tags.

Function Documentation

app_outbox_service_cleanup_all_pending_messages()

void app_outbox_service_cleanup_all_pending_messages

(

void

)

Drop all pending messages.

Called by the app manager when an app terminates. The sent handlers are not called; the messages are freed once their consumers call app_outbox_service_consume_message().

app_outbox_service_cleanup_event()

void app_outbox_service_cleanup_event

(

PebbleEvent *

event

)

Free the message of an unprocessed app outbox event.

Used when cleaning up events queued towards the kernel. Other event types are ignored.

Parameters

event

Event to clean up.

app_outbox_service_consume_message()

void app_outbox_service_consume_message	(	AppOutboxMessage *	message,
		AppOutboxStatus	status
	)

Finish processing a message and free it.

Schedules the sender's sent handler on the app task, unless the message was cancelled.

Parameters

message	Message to consume; invalid once this returns.
status	Status reported to the sent handler.

app_outbox_service_init()

void app_outbox_service_init

(

void

)

Initialize the service, once at boot.

app_outbox_service_is_message_cancelled()

bool app_outbox_service_is_message_cancelled

(

AppOutboxMessage *

message

)

Check whether a message was cancelled.

A message is cancelled when its consumer unregisters or the app terminates. app_outbox_service_consume_message() must still be called on a cancelled message to free it.

Parameters

message

Message to check.

Returns

true if the message was cancelled.

app_outbox_service_register()

void app_outbox_service_register	(	AppOutboxServiceTag	service_tag,
		AppOutboxMessageHandler	message_handler,
		PebbleTask	consumer_task,
		size_t	consumer_data_size
	)

Register the consumer of a tag.

Only one consumer per tag is allowed.

Parameters

service_tag	Tag to consume.
message_handler	Called when a message is added.
consumer_task	Task on which message_handler runs.
consumer_data_size	Bytes allocated in each message for AppOutboxMessage::consumer_data.

app_outbox_service_unregister()

void app_outbox_service_unregister

(

AppOutboxServiceTag

service_tag

)

Unregister the consumer of a tag.

The sent handlers of all pending messages are called with AppOutboxStatusConsumerDoesNotExist.

Parameters

service_tag

Tag to unregister.