Message transfer (badge-to-badge)

Register typed-payload handlers and push payloads to nearby badges. More...

Macros
#define	HOST_MSG_PAYLOAD_MAX   4096
	Maximum payload a plugin may send or receive in one transfer.
#define	HOST_MSG_MIME_MAX   64
	Maximum MIME type string length including the NUL.

Functions
int	host_msg_register_handler (const char *mime_type, uint32_t action_id)
	Register that this plugin handles an incoming MIME type.
int	host_msg_unregister_handler (const char *mime_type)
	Drop a previously registered handler.
int	host_msg_consume (uint8_t *buf, size_t buf_size, char *mime_out, size_t mime_size)
	Pull the payload delivered by the most recent inbound message action.
int	host_msg_send_interactive (const char *mime_type, const uint8_t *data, size_t len)
	Send a typed payload via the firmware-owned interactive peer picker.
int	host_msg_send (const uint8_t addr[6], uint8_t addr_type, const char *mime_type, const uint8_t *data, size_t len)
	Send a typed payload directly to a known peer address (no picker).

Detailed Description

Register typed-payload handlers and push payloads to nearby badges.

A plugin registers one or more MIME types it can receive. The firmware's MessageTransfer service auto-declines an incoming BLE OFFER whose MIME type has no registered handler. After the local user consents and the encrypted transfer completes, the firmware fires the plugin's action_id on the plugin tick task (deferred, like the BLE consume idiom); the handler then pulls the payload with host_msg_consume.

To send, a plugin hands a typed payload to host_msg_send_interactive, which opens the firmware-owned peer picker and consent/progress UI and returns immediately. Sending requires the manifest capability "ble" plus at least one declared message_types entry.

Payload bytes are opaque: the firmware does NOT convert them. For text MIME types the bytes are UTF-8; the plugin renders them through the normal UI functions, which convert UTF-8 to the display codepage. MIME type strings are ASCII.

Macro Definition Documentation

HOST_MSG_MIME_MAX

#define HOST_MSG_MIME_MAX   64

Maximum MIME type string length including the NUL.

Definition at line 1354 of file host_api.h.

Referenced by host_msg_register_handler().

HOST_MSG_PAYLOAD_MAX

#define HOST_MSG_PAYLOAD_MAX   4096

Maximum payload a plugin may send or receive in one transfer.

Definition at line 1352 of file host_api.h.

Referenced by host_msg_send(), and host_msg_send_interactive().

Function Documentation

host_msg_consume()

int host_msg_consume	(	uint8_t *	buf,
		size_t	buf_size,
		char *	mime_out,
		size_t	mime_size )

Pull the payload delivered by the most recent inbound message action.

Call from the handler fired by host_msg_register_handler. Copies the received bytes into buf and the delivering MIME type into mime_out.

Parameters

buf	Destination for payload bytes.
buf_size	Capacity of buf.
mime_out	Destination for the NUL-terminated MIME type (may be NULL).
mime_size	Capacity of mime_out.

Returns

Bytes copied into buf (>= 0), or a negative HOST_ERR_* code.

Definition at line 227 of file host_api_msg.cpp.

References HOST_ERR_INVALID_ARG.

Referenced by cdc::plugin_manager::w_host_msg_consume().

host_msg_register_handler()

int host_msg_register_handler	(	const char *	mime_type,
		uint32_t	action_id )

Register that this plugin handles an incoming MIME type.

Adds mime_type to the firmware MessageTransfer registry so an OFFER of that type is no longer auto-declined. On a completed inbound transfer of this type the firmware fires plugin_on_action(action_id, 0, len); the handler reads the bytes with host_msg_consume. Re-registering the same MIME type replaces the action id.

Parameters

mime_type	NUL-terminated ASCII MIME type, max HOST_MSG_MIME_MAX-1 bytes.
action_id	Plugin action fired on a completed inbound transfer.

Returns

HOST_OK, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NO_MEMORY.

Definition at line 169 of file host_api_msg.cpp.

References HOST_ERR_BUSY, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NO_MEMORY, HOST_MSG_MIME_MAX, HOST_OK, and plg_get_active_plugin().

Referenced by cdc::plugin_manager::w_host_msg_register_handler().

host_msg_send()

int host_msg_send	(	const uint8_t	addr[6],
		uint8_t	addr_type,
		const char *	mime_type,
		const uint8_t *	data,
		size_t	len )

Send a typed payload directly to a known peer address (no picker).

The peer's user still consents. Use when the plugin already has an address; most plugins prefer host_msg_send_interactive.

Parameters

addr	6-byte BLE address.
addr_type	0 = public, 1 = random.
mime_type	NUL-terminated ASCII MIME type.
data	Payload bytes, at most HOST_MSG_PAYLOAD_MAX.
len	Number of payload bytes.

Returns

HOST_OK, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_BUSY.

Definition at line 247 of file host_api_msg.cpp.

References HOST_ERR_BUSY, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_MSG_PAYLOAD_MAX, and HOST_OK.

Referenced by cdc::plugin_manager::w_host_msg_send().

host_msg_send_interactive()

int host_msg_send_interactive	(	const char *	mime_type,
		const uint8_t *	data,
		size_t	len )

Send a typed payload via the firmware-owned interactive peer picker.

Opens the scan/peer-select UI, then the consent + progress flow, then delivers data to the chosen peer's handler for mime_type. Returns immediately after the picker is shown; the transfer happens asynchronously.

Parameters

mime_type	NUL-terminated ASCII MIME type, max HOST_MSG_MIME_MAX-1 bytes.
data	Payload bytes, at most HOST_MSG_PAYLOAD_MAX.
len	Number of payload bytes.

Returns

HOST_OK once the picker is shown, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_BUSY.

Definition at line 239 of file host_api_msg.cpp.

References HOST_ERR_BUSY, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_MSG_PAYLOAD_MAX, and HOST_OK.

Referenced by cdc::plugin_manager::w_host_msg_send_interactive().

host_msg_unregister_handler()

int host_msg_unregister_handler

(

const char *

mime_type

)

Drop a previously registered handler.

Parameters

mime_type

The MIME type passed to host_msg_register_handler.

Returns

HOST_OK or HOST_ERR_NOT_FOUND.

Definition at line 217 of file host_api_msg.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND, HOST_OK, and plg_get_active_plugin().

Referenced by cdc::plugin_manager::w_host_msg_unregister_handler().