|
Soletta™ Framework
| 
|
|
Soletta™ Framework
|
|
Data Structures | |
| struct | sol_main_callbacks |
| Structure used to keep the application main callbacks. More... | |
| struct | sol_mainloop_implementation |
| Structure representing a mainloop implementation (hooks). More... | |
| struct | sol_mainloop_source_type |
| Structure representing the type of a source of mainloop events. More... | |
Macros | |
| #define | SOL_MAIN(CALLBACKS) |
Convenience macro to declare the main function and properly initialize and execute a Soletta Application. More... | |
| #define | SOL_MAIN_DEFAULT(STARTUP, SHUTDOWN) |
| Preferred entry point for Soletta applications. More... | |
| #define | SOL_MAINLOOP_FD_ENABLED |
| This macro is defined by Soletta at build time and will state if file descriptor (fd) functionality is available, this is common in Linux/UNIX environments. More... | |
| #define | SOL_MAINLOOP_FORK_WATCH_ENABLED |
| This macro is defined by Soletta at build time and will state if monitoring (watch) of child process functionality is available, this is common in Linux/UNIX environments. More... | |
| #define | SOL_NO_API_VERSION |
This macro is defined by Soletta at build time and will state if api_version structure members and related defines shouldn't be used. More... | |
| #define | SOL_SET_API_VERSION(expression) |
This macro will cope with SOL_NO_API_VERSION and allows easy declaration of api_version fields. More... | |
Typedefs | |
| typedef struct sol_idle | sol_idle |
| Handle for idlers. More... | |
| typedef struct sol_main_callbacks | sol_main_callbacks |
| Structure used to keep the application main callbacks. More... | |
| typedef struct sol_mainloop_implementation | sol_mainloop_implementation |
| Structure representing a mainloop implementation (hooks). More... | |
| typedef struct sol_mainloop_source | sol_mainloop_source |
| Structure of a Source of mainloop events. More... | |
| typedef struct sol_mainloop_source_type | sol_mainloop_source_type |
| Structure representing the type of a source of mainloop events. More... | |
| typedef struct sol_timeout | sol_timeout |
| Handle for timers tracking the timeouts. More... | |
Functions | |
| int | sol_argc (void) |
| Gets the argument count the application was launched with, if any. More... | |
| char ** | sol_argv (void) |
| Gets the list of arguments the application was launched with, if any. More... | |
| struct sol_idle * | sol_idle_add (bool(*cb)(void *data), const void *data) |
| Adds a function to be called when the application goes idle. More... | |
| bool | sol_idle_del (struct sol_idle *handle) |
| Deletes the given idler. More... | |
| int | sol_init (void) |
| Initializes the Soletta library. More... | |
| struct sol_mainloop_source * | sol_mainloop_add_source (const struct sol_mainloop_source_type *type, const void *data) |
| Create a new source of events to the main loop. More... | |
| int | sol_mainloop_default_main (const struct sol_main_callbacks *callbacks, int argc, char *argv[]) |
| Helper function called by SOL_MAIN. More... | |
| void | sol_mainloop_del_source (struct sol_mainloop_source *handle) |
| Destroy a source of main loop events. More... | |
| const struct sol_mainloop_implementation * | sol_mainloop_get_implementation (void) |
| Returns the current mainloop implementation in use. More... | |
| bool | sol_mainloop_set_implementation (const struct sol_mainloop_implementation *impl) |
| Changes the mainloop implementation. More... | |
| void * | sol_mainloop_source_get_data (const struct sol_mainloop_source *handle) |
| Retrieve the user data (context) given to the source at creation time. More... | |
| void | sol_quit (void) |
| Terminates the main loop. More... | |
| void | sol_quit_with_code (int return_code) |
| Terminates the main loop, setting a specific return code. More... | |
| int | sol_run (void) |
| Runs the main loop. More... | |
| void | sol_set_args (int argc, char *argv[]) |
| Sets a new list of arguments and its count. More... | |
| void | sol_shutdown (void) |
| Shutdown Soletta library. More... | |
| struct sol_timeout * | sol_timeout_add (uint32_t timeout_ms, bool(*cb)(void *data), const void *data) |
| Adds a function to be called periodically by the main loop. More... | |
| bool | sol_timeout_del (struct sol_timeout *handle) |
| Deletes the given timeout. More... | |
Variables | |
| const struct sol_mainloop_implementation * | SOL_MAINLOOP_IMPLEMENTATION_DEFAULT |
| Pointer to Soletta's internal mainloop implementation, that is the default to be used if no other is set. More... | |
| #define SOL_MAIN | ( | CALLBACKS | ) |
Convenience macro to declare the main function and properly initialize and execute a Soletta Application.
| #define SOL_MAIN_DEFAULT | ( | STARTUP, | |
| SHUTDOWN | |||
| ) |
Preferred entry point for Soletta applications.
Different platforms may have different ways in which an application is started, so in order to remain portable, Soletta applications should avoid using platform specific main functions.
SOL_MAIN_DEFAULT will be defined to something that makes sense for the target platform, ensuring that Soletta is properly initialized before calling the provided startup function, where all of the application specific initialization must take place. If they make sense, command line arguments will have been set and can be retrieved with sol_argc() and sol_argv().
After startup is called, the main loop will start, and once that finishes, the shutdown function, if provided, will be called to perform any necessary termination procedures by the application, before Soletta itself is shutdown and the program terminated.
| #define SOL_MAINLOOP_FD_ENABLED |
This macro is defined by Soletta at build time and will state if file descriptor (fd) functionality is available, this is common in Linux/UNIX environments.
| #define SOL_MAINLOOP_FORK_WATCH_ENABLED |
This macro is defined by Soletta at build time and will state if monitoring (watch) of child process functionality is available, this is common in Linux/UNIX environments.
| #define SOL_NO_API_VERSION |
This macro is defined by Soletta at build time and will state if api_version structure members and related defines shouldn't be used.
API Version is used when dynamic libraries are available so we can check in runtime if the structures match expectations. However in static builds such as those in Small OSes it's guaranteed at build time and the space and checks can be saved.
Users can rely on macros SOL_SET_API_VERSION() to set these members in a conditional way.
Referenced by mytype_func().
| #define SOL_SET_API_VERSION | ( | expression | ) |
This macro will cope with SOL_NO_API_VERSION and allows easy declaration of api_version fields.
Referenced by entry_new(), iio_gyroscope_reader_cb(), main(), read_access_control_obj(), register_light_resource_type(), request_cb(), request_events_cb(), request_input(), sol_http_params_init(), startup(), startup_client(), and startup_server().
Handle for idlers.
This structure is used to help setup and control Idlers.
| typedef struct sol_main_callbacks sol_main_callbacks |
Structure used to keep the application main callbacks.
It's intended to be used through SOL_MAIN_DEFAULT. Keeps the startup and shutdown callbacks of the application that will be called by SOL_MAIN_DEFAULT when appropriated.
| typedef struct sol_mainloop_implementation sol_mainloop_implementation |
Structure representing a mainloop implementation (hooks).
Structure of a Source of mainloop events.
| typedef struct sol_mainloop_source_type sol_mainloop_source_type |
Structure representing the type of a source of mainloop events.
Handle for timers tracking the timeouts.
| int sol_argc | ( | void | ) |
Gets the argument count the application was launched with, if any.
argc value as set by sol_set_args() or SOL_MAIN() Referenced by parse_cmdline_pin(), startup(), startup_client(), startup_network(), and startup_server().
| char** sol_argv | ( | void | ) |
Gets the list of arguments the application was launched with, if any.
argv value as set by sol_set_args() or SOL_MAIN() Referenced by parse_cmdline_pin(), show_help(), startup(), startup_client(), startup_network(), and startup_server().
| struct sol_idle* sol_idle_add | ( | bool(*)(void *data) | cb, |
| const void * | data | ||
| ) |
Adds a function to be called when the application goes idle.
Idlers are called when the main loop reaches the idle state. That is, after all pending events have been processed and no timeout has expired. This means that if there's always something to do, an idler function may never be called. Like timeouts, if an idler function returns false, it will be automatically removed, otherwise they will kept to be called until some other event becomes available.
| cb | The function to call when the idle state is reached |
| data | The user data pointer to pass to the function |
| bool sol_idle_del | ( | struct sol_idle * | handle | ) |
Deletes the given idler.
| handle | The idler to delete |
| int sol_init | ( | void | ) |
Initializes the Soletta library.
This function setup all needed infrastructure. It should be called prior the use of any Soletta API.
0 on success, error code (always negative) otherwiseReferenced by main(), and sol_glib_integration().
| struct sol_mainloop_source* sol_mainloop_add_source | ( | const struct sol_mainloop_source_type * | type, |
| const void * | data | ||
| ) |
Create a new source of events to the main loop.
Some libraries will have their own internal main loop, in the case we should integrate them with Soletta's we do so by adding a new source of events to Soletta's main loop.
The source is described by its type, a set of functions to be called back at various phases:
false the main loop can sleep forever. If not provided, then return false is assumed.true, then there are events to be dispatched in this source.check() returns true.dispose called when the source is deleted. This will happen at sol_shutdown() if the source is not manually deleted.If a source doesn't know the time for the next event (say an interruption service handler or an internal file descriptor), then further integration work needs to be done. The interruption service handler can use sol_timeout_add() from a thread to schedule a main loop wake, that in turn will run the source's prepare() automatically. Analogously, the internal file descriptors can be added to soletta's at prepare(). If the main loop uses epoll(), that fd can be added to chain the monitoring.
| type | the description of the source of main loop events. This pointer is not modified and is not copied, thus it must exist during the lifetime of the source |
| data | the user data (context) to give to callbacks in type |
NULL on failureReferenced by sol_glib_integration().
| int sol_mainloop_default_main | ( | const struct sol_main_callbacks * | callbacks, |
| int | argc, | ||
| char * | argv[] | ||
| ) |
Helper function called by SOL_MAIN.
Shouldn't be called directly.
| callbacks | Application callback structure |
| argc | The count of elements in argv |
| argv | Array of NUL terminated strings, each represents one argument |
0 on success, error code (always negative) otherwise | void sol_mainloop_del_source | ( | struct sol_mainloop_source * | handle | ) |
Destroy a source of main loop events.
| handle | a valid handle previously created with sol_mainloop_add_source(). |
| const struct sol_mainloop_implementation* sol_mainloop_get_implementation | ( | void | ) |
Returns the current mainloop implementation in use.
By default it is SOL_MAINLOOP_IMPLEMENTATION_DEFAULT, but can be changed by sol_mainloop_set_implementation().
Before accessing the members of the returned pointer check if your known SOL_MAINLOOP_IMPLEMENTATION_API_VERSION matches its api_version field (which is conditional to SOL_NO_API_VERSION).
| bool sol_mainloop_set_implementation | ( | const struct sol_mainloop_implementation * | impl | ) |
Changes the mainloop implementation.
By setting the mainloop implementation one can override the Soletta behavior, this is often useful if libsoletta is being used as a guest library in some system that already hosts one, such as a Node.JS application. In this case we want to forward requests to that mainloop and be as lean as possible.
This is an alternative to sol_mainloop_add_source(), in that case Soletta would be the host and other main loops can be the guest, see sol-glib-integration.h for one example.
| impl | a valid handle, this means api_version field must match SOL_MAINLOOP_IMPLEMENTATION_API_VERSION and all pointers are non-NULL. It is not copied, so the pointer must be valid until a new one is set to replace it. |
| void* sol_mainloop_source_get_data | ( | const struct sol_mainloop_source * | handle | ) |
Retrieve the user data (context) given to the source at creation time.
| handle | a valid handle previously created with sol_mainloop_add_source(). |
| void sol_quit | ( | void | ) |
Terminates the main loop.
Stops the main loop and sets the return value of sol_run() to EXIT_SUCCESS.
Referenced by check_delete_request(), check_post_request(), check_put_request(), consumer_read_available(), delete_cb(), found_resource_print(), on_data(), on_digest_ready(), on_stdin(), platform_info_cb(), print_response(), producer_data_written(), producer_make_data(), resource_notify(), server_info_cb(), startup(), and store_digest().
| void sol_quit_with_code | ( | int | return_code | ) |
Terminates the main loop, setting a specific return code.
Stops the main loop and sets the return value of sol_run() to return_code. Usually used to indicate that the application should end with an error.
| return_code | The exit code that sol_run() will return |
Referenced by check_delete_request(), check_post_request(), check_put_request(), create_minutes(), create_seconds(), found_resource(), found_resource_print(), on_can_read(), on_can_write(), on_stdin(), on_stdin_hash(), platform_info_cb(), print_response(), resource_notify(), response_cb(), response_func(), server_info_cb(), startup(), startup_client(), startup_network(), and startup_server().
| int sol_run | ( | void | ) |
Runs the main loop.
This function executes the main loop and it will return only after sol_quit() or sol_quit_with_code() is called.
Referenced by main().
| void sol_set_args | ( | int | argc, |
| char * | argv[] | ||
| ) |
Sets a new list of arguments and its count.
A reference to the argv pointer will be kept, so it must be valid at least until sol_set_args() is called again to set different arguments. This function is useful in cases where the main application may have arguments to handle and others that need to be passed forward to other sub-systems. For example, the flow systems has node types to retrieve the arguments the application was started with, and these may differ if the application is run as an FBP script, or as a compiled binary, so the FBP interpreter removes its own arguments and uses this function to set the list of arguments that the flow should see.
| argc | The count of elements in argv |
| argv | Array of nul terminated strings, each represents one argument |
| void sol_shutdown | ( | void | ) |
Shutdown Soletta library.
This function shuts down Soletta and once it's called, no other Soletta API should be used.
Referenced by main().
| struct sol_timeout* sol_timeout_add | ( | uint32_t | timeout_ms, |
| bool(*)(void *data) | cb, | ||
| const void * | data | ||
| ) |
Adds a function to be called periodically by the main loop.
Timeouts are called by the main loop every timeout_ms milliseconds for as long as the given function cb returns true.
| timeout_ms | The period in milliseconds in which the function will be called |
| cb | The function to call, it will be called every timeout_ms until it returns false |
| data | The user data pointer to pass to the function |
Referenced by _can_read(), create_location_obj(), enabled(), found_device(), main(), mytype_func(), on_connect(), on_disconnect(), reader_open(), and startup().
| bool sol_timeout_del | ( | struct sol_timeout * | handle | ) |
Deletes the given timeout.
If it's necessary to keep a created timeout from being called, this function can delete it.
| handle | The timeout to delete |
Referenced by create_location_obj(), del_location_obj(), main(), my_stream_api_close(), mytype_func(), reader_close(), and shutdown().
| const struct sol_mainloop_implementation* SOL_MAINLOOP_IMPLEMENTATION_DEFAULT |
Pointer to Soletta's internal mainloop implementation, that is the default to be used if no other is set.
1.8.6