External features (inter-plugin)

Invoke a named feature provided by another installed plugin. More...

Macros
#define	HOST_EXT_FEATURE_NAME_MAX   33
	Maximum external-feature name length including the NUL.
#define	HOST_EXT_FEATURE_PAYLOAD_MAX   32768
	Maximum payload a caller may hand to a provider in one job.
#define	HOST_EXT_FEATURE_STATUS_DONE   0
	Provider status: job completed successfully.
#define	HOST_EXT_FEATURE_STATUS_ERROR   1
	Provider status: generic failure. Provider-defined codes are >= 1.

Functions
int	host_ext_feature_available (const char *feature)
	Check whether an installed plugin provides feature.
int	host_ext_feature_use (const char *feature, const uint8_t *data, size_t len, uint32_t status_action_id)
	Invoke feature with a payload; the provider runs in the foreground.
int	host_ext_feature_register_handler (const char *feature, uint32_t action_id)
	Register this plugin as the live handler for a feature it provides.
int	host_ext_feature_consume (uint8_t *buf, size_t buf_size, char *feature_out, size_t feature_size)
	Pull the payload of the job that fired the current handler action.
int	host_ext_feature_result (int32_t status_code)
	Report the outcome of the job this provider is currently handling.

Detailed Description

Invoke a named feature provided by another installed plugin.

A provider plugin declares provides: ["thermo_print"] under manifest capabilities and registers a handler for each declared feature in plugin_init via host_ext_feature_register_handler. A caller invokes the feature with host_ext_feature_use: the firmware stashes the payload, switches the provider plugin to the FOREGROUND (like "Open with"), fires the provider's handler action, and the provider pulls the bytes with host_ext_feature_consume. When done, the provider reports the outcome once via host_ext_feature_result, which fires the caller's status_action_id with the status code in user_data.

Lifecycle: HOST_OK from host_ext_feature_use means job accepted, not done. The foreground switch unloads a caller without background: true (plugin_on_exit + teardown) - its status action is then silently dropped. Callers that need the result must declare background: true. Calling a feature requires no capability; providing one requires the manifest provides entry. If no installed plugin provides the feature, the firmware shows a "no plugin provides this feature" modal and returns HOST_ERR_NOT_FOUND.

Macro Definition Documentation

HOST_EXT_FEATURE_NAME_MAX

#define HOST_EXT_FEATURE_NAME_MAX   33

Maximum external-feature name length including the NUL.

Definition at line 1919 of file host_api.h.

Referenced by plg_ext_feature_pump().

HOST_EXT_FEATURE_PAYLOAD_MAX

#define HOST_EXT_FEATURE_PAYLOAD_MAX   32768

Maximum payload a caller may hand to a provider in one job.

Definition at line 1921 of file host_api.h.

Referenced by host_ext_feature_use().

HOST_EXT_FEATURE_STATUS_DONE

#define HOST_EXT_FEATURE_STATUS_DONE   0

Provider status: job completed successfully.

Definition at line 1923 of file host_api.h.

HOST_EXT_FEATURE_STATUS_ERROR

#define HOST_EXT_FEATURE_STATUS_ERROR   1

Provider status: generic failure. Provider-defined codes are >= 1.

Definition at line 1925 of file host_api.h.

Referenced by plg_ext_feature_on_unload(), and plg_ext_feature_pump().

Function Documentation

host_ext_feature_available()

int host_ext_feature_available

(

const char *

feature

)

Check whether an installed plugin provides feature.

Parameters

feature

NUL-terminated feature name, [a-z][a-z0-9_]*.

Returns

HOST_OK if a provider is installed (and enabled), HOST_ERR_NOT_FOUND otherwise, HOST_ERR_INVALID_ARG on a bad name.

Definition at line 129 of file host_api_ext_feature.cpp.

References cdc::plugin_manager::PluginManager::featureInstalled(), HOST_ERR_INVALID_ARG, HOST_ERR_NOT_FOUND, HOST_OK, cdc::plugin_manager::PluginManager::instance(), and cdc::plugin_manager::isValidExtFeatureName().

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

host_ext_feature_consume()

int host_ext_feature_consume	(	uint8_t *	buf,
		size_t	buf_size,
		char *	feature_out,
		size_t	feature_size )

Pull the payload of the job that fired the current handler action.

Valid only during that action dispatch, mirroring host_msg_consume.

Parameters

buf	Destination for payload bytes.
buf_size	Capacity of buf.
feature_out	Destination for the NUL-terminated feature name (may be NULL).
feature_size	Capacity of feature_out.

Returns

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

Definition at line 205 of file host_api_ext_feature.cpp.

References HOST_ERR_INVALID_ARG.

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

host_ext_feature_register_handler()

int host_ext_feature_register_handler	(	const char *	feature,
		uint32_t	action_id )

Register this plugin as the live handler for a feature it provides.

Call from plugin_init for every manifest provides entry. On an incoming job the firmware fires plugin_on_action(action_id, 0, len); the handler pulls the payload with host_ext_feature_consume. The handler firing right after plugin_on_enter is what distinguishes "opened for a job" from "opened by the user".

Parameters

feature	NUL-terminated feature name; must be declared in provides.
action_id	Plugin action fired when a job arrives.

Returns

HOST_OK, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY (feature not in this plugin's provides), HOST_ERR_NO_MEMORY.

Definition at line 177 of file host_api_ext_feature.cpp.

References HOST_ERR_GENERIC, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NO_MEMORY, HOST_OK, cdc::plugin_manager::isValidExtFeatureName(), name, and plg_get_active_plugin().

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

host_ext_feature_result()

int host_ext_feature_result

(

int32_t

status_code

)

Report the outcome of the job this provider is currently handling.

Fires the caller's status_action_id (if the caller is still loaded) and frees the job slot. Call exactly once per received job.

Parameters

status_code

HOST_EXT_FEATURE_STATUS_DONE or a provider-defined error code >= 1.

Returns

HOST_OK, HOST_ERR_NOT_FOUND (no job owned by this plugin).

Definition at line 218 of file host_api_ext_feature.cpp.

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

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

host_ext_feature_use()

int host_ext_feature_use	(	const char *	feature,
		const uint8_t *	data,
		size_t	len,
		uint32_t	status_action_id )

Invoke feature with a payload; the provider runs in the foreground.

Returns immediately after stashing the job. The provider plugin is switched to the foreground on the next tick, receives its registered handler action and consumes the payload. The final outcome arrives later as plugin_on_action(status_action_id, 0, status) - only if this caller is still loaded at that time (see group docs for the background requirement).

Parameters

feature	NUL-terminated feature name.
data	Payload bytes (may be NULL when len == 0).
len	Payload length, at most HOST_EXT_FEATURE_PAYLOAD_MAX.
status_action_id	Caller action fired with the provider's status code in user_data (HOST_EXT_FEATURE_STATUS_*). Pass 0 for fire-and-forget.

Returns

HOST_OK (job accepted), HOST_ERR_INVALID_ARG (bad name/args or self-call), HOST_ERR_NOT_FOUND (no provider installed - a modal was shown), HOST_ERR_BUSY (another job is still pending), HOST_ERR_NO_MEMORY.

Definition at line 135 of file host_api_ext_feature.cpp.

References cdc::ui::ERROR, cdc::plugin_manager::PluginManager::featureProviderId(), HOST_ERR_BUSY, HOST_ERR_GENERIC, HOST_ERR_INVALID_ARG, HOST_ERR_NO_MEMORY, HOST_ERR_NOT_FOUND, HOST_EXT_FEATURE_PAYLOAD_MAX, HOST_OK, cdc::plugin_manager::PluginManager::instance(), cdc::plugin_manager::isValidExtFeatureName(), plg_get_active_plugin(), cdc::ui::showMessage(), and cdc::ui::tr().

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