Loading...
Searching...
No Matches
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 , 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]eventpointer to the event object. Valid only inside the callback function.
[in,out]contextpointer to the user-defined context object.

Enumeration Type Documentation

◆ 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

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.

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
  • RpcAppEventTypeDataExchange

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

Parameters
[in,out]rpc_apppointer to the instance to be used.
[in]resultwhether 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_apppointer 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_apppointer to the instance to be used.
[in]datapointer to the data buffer to be sent.
[in]data_sizesize 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_apppointer 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_apppointer 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_apppointer to the instance to be configured.
[in]callbackpointer to the function to be called upon message reception.
[in,out]contextpointer 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_apppointer to the instance to be modified.
[in]error_codearbitrary 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_apppointer to the instance to be modified.
[in]error_textPointer to a zero-terminated string containing the error text.