rpc_app.h File Reference

Application RPC subsystem interface. More...

#include "rpc.h"
#include "rpc_app_error_codes.h"

Go to the source code of this file.

Data Structures
struct	RpcAppSystemEventData
	Event data structure, containing the type and associated data. More...
struct	RpcAppSystemEvent
	RPC application subsystem event structure. More...

Typedefs
typedef void(*	RpcAppSystemCallback) (const RpcAppSystemEvent *event, void *context)
	Callback function type.
typedef struct RpcAppSystem	RpcAppSystem
	RPC application subsystem opaque type declaration.

Enumerations
enum	RpcAppSystemEventDataType { RpcAppSystemEventDataTypeNone , RpcAppSystemEventDataTypeString , RpcAppSystemEventDataTypeInt32 , RpcAppSystemEventDataTypeBytes }
	Enumeration of possible event data types. More...
enum	RpcAppSystemEventType {   RpcAppEventTypeInvalid , RpcAppEventTypeSessionClose , RpcAppEventTypeAppExit , RpcAppEventTypeLoadFile ,   RpcAppEventTypeButtonPress , RpcAppEventTypeButtonRelease , RpcAppEventTypeButtonPressRelease , RpcAppEventTypeDataExchange }
	Enumeration of possible event types. More...

Functions
void	rpc_system_app_set_callback (RpcAppSystem *rpc_app, RpcAppSystemCallback callback, void *context)
	Set the callback function for use by an RpcAppSystem instance.
void	rpc_system_app_send_started (RpcAppSystem *rpc_app)
	Send a notification that an RpcAppSystem instance has been started and is ready.
void	rpc_system_app_send_exited (RpcAppSystem *rpc_app)
	Send a notification that the application using an RpcAppSystem instance is about to exit.
void	rpc_system_app_confirm (RpcAppSystem *rpc_app, bool result)
	Send a confirmation that the application using an RpcAppSystem instance has handled the event.
void	rpc_system_app_set_error_code (RpcAppSystem *rpc_app, uint32_t error_code)
	Set the error code stored in an RpcAppSystem instance.
void	rpc_system_app_set_error_text (RpcAppSystem *rpc_app, const char *error_text)
	Set the error text stored in an RpcAppSystem instance.
void	rpc_system_app_error_reset (RpcAppSystem *rpc_app)
	Reset the error code and text stored in an RpcAppSystem instance.
void	rpc_system_app_exchange_data (RpcAppSystem *rpc_app, const uint8_t *data, size_t data_size)
	Send a byte array of arbitrary data to the client using an RpcAppSystem instance.

Detailed Description

Application RPC subsystem interface.

The application RPC subsystem provides facilities for interacting with applications, such as starting/stopping, passing parameters, sending commands and exchanging arbitrary data.

All commands are handled asynchronously via a user-settable callback.

For a complete description of message types handled in this subsystem, see https://github.com/flipperdevices/flipperzero-protobuf/blob/dev/application.proto

Typedef Documentation

RpcAppSystemCallback

typedef void(* RpcAppSystemCallback) (const RpcAppSystemEvent *event, void *context)

Callback function type.

A function of this type must be passed to rpc_system_app_set_callback() by the user code.

Warning

The event pointer is valid ONLY inside the callback function.

Parameters

[in]	event	pointer to the event object. Valid only inside the callback function.
[in,out]	context	pointer to the user-defined context object.

Enumeration Type Documentation

RpcAppSystemEventDataType

enum RpcAppSystemEventDataType

Enumeration of possible event data types.

Enumerator
RpcAppSystemEventDataTypeNone	No data is provided by the event.
RpcAppSystemEventDataTypeString	Event data contains a zero-terminated string.
RpcAppSystemEventDataTypeInt32	Event data contains a signed 32-bit integer.
RpcAppSystemEventDataTypeBytes	Event data contains zero or more bytes.

RpcAppSystemEventType

enum RpcAppSystemEventType

Enumeration of possible event types.

Enumerator
RpcAppEventTypeInvalid	Denotes an invalid state. An event of this type shall never be passed into the callback.
RpcAppEventTypeSessionClose	The client side has closed the session. After receiving this event, the RPC context is no more valid.
RpcAppEventTypeAppExit	The client has requested the application to exit. The application must exit after receiving this command.
RpcAppEventTypeLoadFile	The client has requested the application to load a file. This command's meaning is application-specific, i.e. the application might or might not require additional commands after loading a file to do anything useful.
RpcAppEventTypeButtonPress	The client has informed the application that a button has been pressed. This command's meaning is application-specific, e.g. to select a part of the previously loaded file or to invoke a particular function within the application.
RpcAppEventTypeButtonRelease	The client has informed the application that a button has been released. This command's meaning is application-specific, e.g. to cease all activities to be conducted while a button is being pressed.
RpcAppEventTypeButtonPressRelease	The client has informed the application that a button has been pressed and released. This command's meaning is application-specific, e.g. to perform an action once without repeating it.
RpcAppEventTypeDataExchange	The client has sent a byte array of arbitrary size. This command's purpose is bi-directional exchange of arbitrary raw data. Useful for implementing higher-level protocols while using the RPC as a transport layer.

Function Documentation

rpc_system_app_confirm()

void rpc_system_app_confirm	(	RpcAppSystem *	rpc_app,
		bool	result )

Send a confirmation that the application using an RpcAppSystem instance has handled the event.

An explicit confirmation is required for the following event types:

• RpcAppEventTypeAppExit
• RpcAppEventTypeLoadFile
• RpcAppEventTypeButtonPress
• RpcAppEventTypeButtonRelease
• RpcAppEventTypeButtonPressRelease
• RpcAppEventTypeDataExchange

Not confirming these events will result in a client-side timeout.

Parameters

[in,out]	rpc_app	pointer to the instance to be used.
[in]	result	whether the command was successfully handled or not (true for success).

rpc_system_app_error_reset()

void rpc_system_app_error_reset

(

RpcAppSystem *

rpc_app

)

Reset the error code and text stored in an RpcAppSystem instance.

Resets the error code to 0 and error text to "" (empty string).

Parameters

[in,out]

rpc_app

pointer to the instance to be reset.

rpc_system_app_exchange_data()

void rpc_system_app_exchange_data	(	RpcAppSystem *	rpc_app,
		const uint8_t *	data,
		size_t	data_size )

Send a byte array of arbitrary data to the client using an RpcAppSystem instance.

Parameters

[in,out]	rpc_app	pointer to the instance to be used.
[in]	data	pointer to the data buffer to be sent.
[in]	data_size	size of the data buffer, in bytes.

rpc_system_app_send_exited()

void rpc_system_app_send_exited

(

RpcAppSystem *

rpc_app

)

Send a notification that the application using an RpcAppSystem instance is about to exit.

Call this function when the application is about to exit (usually in the *_free() function).

Parameters

[in,out]

rpc_app

pointer to the instance to be used.

rpc_system_app_send_started()

void rpc_system_app_send_started

(

RpcAppSystem *

rpc_app

)

Send a notification that an RpcAppSystem instance has been started and is ready.

Call this function once right after acquiring an RPC context and setting the callback.

Parameters

[in,out]

rpc_app

pointer to the instance to be used.

rpc_system_app_set_callback()

void rpc_system_app_set_callback	(	RpcAppSystem *	rpc_app,
		RpcAppSystemCallback	callback,
		void *	context )

Set the callback function for use by an RpcAppSystem instance.

Parameters

[in,out]	rpc_app	pointer to the instance to be configured.
[in]	callback	pointer to the function to be called upon message reception.
[in,out]	context	pointer to the user-defined context object. Will be passed to the callback.

rpc_system_app_set_error_code()

void rpc_system_app_set_error_code	(	RpcAppSystem *	rpc_app,
		uint32_t	error_code )

Set the error code stored in an RpcAppSystem instance.

The error code can be retrieved by the client at any time by using the GetError request. The error code value has no meaning within the subsystem, i.e. it is only passed through to the client.

Parameters

[in,out]	rpc_app	pointer to the instance to be modified.
[in]	error_code	arbitrary error code to be set.

rpc_system_app_set_error_text()

void rpc_system_app_set_error_text	(	RpcAppSystem *	rpc_app,
		const char *	error_text )

Set the error text stored in an RpcAppSystem instance.

The error text can be retrieved by the client at any time by using the GetError request. The text has no meaning within the subsystem, i.e. it is only passed through to the client.

Parameters

[in,out]	rpc_app	pointer to the instance to be modified.
[in]	error_text	Pointer to a zero-terminated string containing the error text.