|
ObjectBox C and C++ API
4.0.3
|
|
|
ObjectBox C and C++ API
4.0.3
|
|
Classes | |
| struct | OBX_sync_change |
| struct | OBX_sync_change_array |
| struct | OBX_sync_object |
| A single data object contained in a OBX_sync_msg_objects message. More... | |
| struct | OBX_sync_msg_objects |
| Incubating message that carries multiple data "objects" (e.g. FlatBuffers, strings, raw bytes). Interpretation is up to the application. Does not involve any persistence or delivery guarantees at the moment. More... | |
| struct | OBX_custom_msg_server_functions |
| Struct of the custom server function callbacks. In order to implement the custom server, you must provide custom methods for each of the members of this struct. This is then passed to obx_custom_msg_server_register() to register the custom server. More... | |
| struct | OBX_custom_msg_client_functions |
| Struct of the custom client function callbacks. In order to implement the custom client, you must provide custom methods for each of the members of this struct. This is then passed to obx_custom_msg_client_register() to register the custom client. More... | |
Typedefs | |
| typedef struct OBX_sync | OBX_sync |
| typedef struct OBX_sync_change | OBX_sync_change |
| typedef struct OBX_sync_change_array | OBX_sync_change_array |
| typedef struct OBX_sync_object | OBX_sync_object |
| A single data object contained in a OBX_sync_msg_objects message. More... | |
| typedef struct OBX_sync_msg_objects | OBX_sync_msg_objects |
| Incubating message that carries multiple data "objects" (e.g. FlatBuffers, strings, raw bytes). Interpretation is up to the application. Does not involve any persistence or delivery guarantees at the moment. More... | |
| typedef struct OBX_sync_msg_objects_builder | OBX_sync_msg_objects_builder |
| typedef void | OBX_sync_listener_connect(void *arg) |
| Called when connection is established. More... | |
| typedef void | OBX_sync_listener_disconnect(void *arg) |
| Called when connection is closed/lost. More... | |
| typedef void | OBX_sync_listener_login(void *arg) |
| Called on successful login. More... | |
| typedef void | OBX_sync_listener_login_failure(void *arg, OBXSyncCode code) |
| Called on a login failure. More... | |
| typedef void | OBX_sync_listener_complete(void *arg) |
| Called when synchronization is complete. More... | |
| typedef void | OBX_sync_listener_error(void *arg, OBXSyncError error) |
| Callend when sync-level errors occur. More... | |
| typedef void | OBX_sync_listener_change(void *arg, const OBX_sync_change_array *changes) |
| Called with fine grained sync changes (IDs of put and removed entities) More... | |
| typedef void | OBX_sync_listener_server_time(void *arg, int64_t timestamp_ns) |
| Called when a server time information is received on the client. More... | |
| typedef void | OBX_sync_listener_msg_objects(void *arg, const OBX_sync_msg_objects *msg_objects) |
| typedef struct OBX_sync_server | OBX_sync_server |
| typedef void * | OBX_custom_msg_server_func_create(uint64_t server_id, const char *url, const char *cert_path, void *config_user_data) |
| Callback to create a custom messaging server. Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details. More... | |
| typedef obx_err | OBX_custom_msg_server_func_start(void *server_user_data, uint64_t *out_port) |
| Callback to start a custom server. Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details. More... | |
| typedef void | OBX_custom_msg_server_func_stop(void *server_user_data) |
| Callback to stop and close the custom server (e.g. further messages delivery will be rejected). Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details. This includes the store associated with the server; it gets closed and must not be used anymore after this call. More... | |
| typedef void | OBX_custom_msg_server_func_shutdown(void *server_user_data) |
| Callback to shut the custom server down, freeing its resources (the custom server is not used after this point). Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details. More... | |
| typedef bool | OBX_custom_msg_server_func_client_connection_send_async(OBX_bytes_lazy *bytes, void *server_user_data, void *connection_user_data) |
| Callback to enqueue a message for sending. Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details. More... | |
| typedef void | OBX_custom_msg_server_func_client_connection_close(void *server_user_data, void *connection_user_data) |
| Callback to close the sync client connection to the custom server. Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details. More... | |
| typedef void | OBX_custom_msg_server_func_client_connection_shutdown(void *connection_user_data) |
| Callback to shutdown and free all resources associated with the sync client connection to the custom server. Note that the custom server may already have been shutdown at this point (e.g. no server user data is supplied). Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details. More... | |
| typedef struct OBX_custom_msg_server_functions | OBX_custom_msg_server_functions |
| Struct of the custom server function callbacks. In order to implement the custom server, you must provide custom methods for each of the members of this struct. This is then passed to obx_custom_msg_server_register() to register the custom server. More... | |
| typedef void * | OBX_custom_msg_client_func_create(uint64_t client_id, const char *url, const char *cert_path, void *config_user_data) |
| Callback to create a custom messaging client. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details. More... | |
| typedef obx_err | OBX_custom_msg_client_func_start(void *client_user_data) |
| Callback to start the client. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details. More... | |
| typedef void | OBX_custom_msg_client_func_stop(void *client_user_data) |
| Callback to stop and close the client (e.g. further messages delivery will be rejected). Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details. More... | |
| typedef void | OBX_custom_msg_client_func_join(void *client_user_data) |
| Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details. More... | |
| typedef bool | OBX_custom_msg_client_func_connect(void *client_user_data) |
| Callback that tells the client it shall start trying to connect. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details. More... | |
| typedef void | OBX_custom_msg_client_func_disconnect(bool clear_outgoing_messages, void *client_user_data) |
| Callback that tells the client it shall disconnect. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details. More... | |
| typedef void | OBX_custom_msg_client_func_shutdown(void *client_user_data) |
| Callback to shut the custom client down, freeing its resources. The custom client is not used after this point. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details. More... | |
| typedef bool | OBX_custom_msg_client_func_send_async(OBX_bytes_lazy *bytes, void *client_user_data) |
| Callback to enqueue a message for sending. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details. More... | |
| typedef void | OBX_custom_msg_client_func_clear_outgoing_messages(void *client_user_data) |
| Callback to clear all outgoing messages. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details. More... | |
| typedef struct OBX_custom_msg_client_functions | OBX_custom_msg_client_functions |
| Struct of the custom client function callbacks. In order to implement the custom client, you must provide custom methods for each of the members of this struct. This is then passed to obx_custom_msg_client_register() to register the custom client. More... | |
Functions | |
| OBX_C_API OBX_sync * | obx_sync (OBX_store *store, const char *server_url) |
| Creates a sync client associated with the given store and sync server URL. This does not initiate any connection attempts yet: call obx_sync_start() to do so. Before obx_sync_start(), you must configure credentials via obx_sync_credentials. By default a sync client automatically receives updates from the server once login succeeded. To configure this differently, call obx_sync_request_updates_mode() with the wanted mode. More... | |
| OBX_C_API OBX_sync * | obx_sync_urls (OBX_store *store, const char *server_urls[], size_t server_urls_count) |
| Creates a sync client associated with the given store and a list of sync server URL. For details, see obx_sync() More... | |
| OBX_C_API obx_err | obx_sync_close (OBX_sync *sync) |
| Stops and closes (deletes) the sync client, freeing its resources. More... | |
| OBX_C_API obx_err | obx_sync_credentials (OBX_sync *sync, OBXSyncCredentialsType type, const void *data, size_t size) |
| Sets credentials to authenticate the client with the server. See OBXSyncCredentialsType for available options. The accepted OBXSyncCredentials type depends on your sync-server configuration. More... | |
| OBX_C_API obx_err | obx_sync_credentials_user_password (OBX_sync *sync, OBXSyncCredentialsType type, const char *username, const char *password) |
| Set username/password credentials to authenticate the client with the server. This is suitable for OBXSyncCredentialsType_OBX_ADMIN_USER and OBXSyncCredentialsType_USER_PASSWORD credential types. Use obx_sync_credentials() for other credential types. More... | |
| OBX_C_API obx_err | obx_sync_max_messages_in_flight (OBX_sync *sync, int value) |
| Configures the maximum number of outgoing TX messages that can be sent without an ACK from the server. More... | |
| OBX_C_API obx_err | obx_sync_trigger_reconnect (OBX_sync *sync) |
| Triggers a reconnection attempt immediately. By default, an increasing backoff interval is used for reconnection attempts. But sometimes the user of this API has additional knowledge and can initiate a reconnection attempt sooner. More... | |
| OBX_C_API obx_err | obx_sync_heartbeat_interval (OBX_sync *sync, uint64_t interval_ms) |
| Sets the interval in which the client sends "heartbeat" messages to the server, keeping the connection alive. To detect disconnects early on the client side, you can also use heartbeats with a smaller interval. Use with caution, setting a low value (i.e. sending heartbeat very often) may cause an excessive network usage as well as high server load (with many clients). More... | |
| OBX_C_API obx_err | obx_sync_send_heartbeat (OBX_sync *sync) |
| Triggers the heartbeat sending immediately. This lets you check the network connection at any time. More... | |
| OBX_C_API obx_err | obx_sync_request_updates_mode (OBX_sync *sync, OBXRequestUpdatesMode mode) |
| Switches operation mode that's initialized after successful login Must be called before obx_sync_start() (returns OBX_ERROR_ILLEGAL_STATE if it was already started) More... | |
| OBX_C_API obx_err | obx_sync_start (OBX_sync *sync) |
| Once the sync client is configured, you can "start" it to initiate synchronization. This method triggers communication in the background and will return immediately. If the synchronization destination is reachable, this background thread will connect to the server, log in (authenticate) and, depending on "update request mode", start syncing data. If the device, network or server is currently offline, connection attempts will be retried later using increasing backoff intervals. More... | |
| OBX_C_API obx_err | obx_sync_stop (OBX_sync *sync) |
| Stops this sync client and thus stopping the synchronization. Does nothing if it is already stopped. More... | |
| OBX_C_API OBXSyncState | obx_sync_state (OBX_sync *sync) |
| Gets the current state of the sync client (0 on error, e.g. given sync was NULL) More... | |
| OBX_C_API obx_err | obx_sync_wait_for_logged_in_state (OBX_sync *sync, uint64_t timeout_millis) |
| Waits for the sync client to get into the given state or until the given timeout is reached. For an asynchronous alternative, please check the listeners. More... | |
| OBX_C_API obx_err | obx_sync_updates_request (OBX_sync *sync, bool subscribe_for_pushes) |
| Request updates from the server since we last synced our database. More... | |
| OBX_C_API obx_err | obx_sync_updates_cancel (OBX_sync *sync) |
| Cancel updates from the server (once received, the server stops sending updates). The counterpart to obx_sync_updates_request(). This should only be called in "logged in" state and there are no delivery guarantees given. More... | |
| OBX_C_API obx_err | obx_sync_outgoing_message_count (OBX_sync *sync, uint64_t limit, uint64_t *out_count) |
| Count the number of messages in the outgoing queue, i.e. those waiting to be sent to the server. More... | |
| OBX_C_API obx_err | obx_sync_full (OBX_sync *sync) |
| Experimental. This API is likely to be replaced/removed in a future version. Quickly bring our database up-to-date in a single transaction, without transmitting all the history. Good for initial sync of new clients. More... | |
| OBX_C_API obx_err | obx_sync_time_server (OBX_sync *sync, int64_t *out_timestamp_ns) |
| Estimates the current server timestamp based on the last known server time and local steady clock. More... | |
| OBX_C_API obx_err | obx_sync_time_server_diff (OBX_sync *sync, int64_t *out_diff_ns) |
| Returns the estimated difference between the server time and the local timestamp. Equivalent to calculating obx_sync_time_server() - "current time" (nanos since epoch). More... | |
| OBX_C_API uint32_t | obx_sync_protocol_version () |
| Gets the protocol version this client uses. More... | |
| OBX_C_API uint32_t | obx_sync_protocol_version_server (OBX_sync *sync) |
| Gets the protocol version of the server after a connection is established (or attempted), zero otherwise. More... | |
| OBX_C_API OBX_sync_msg_objects_builder * | obx_sync_msg_objects_builder (const void *topic, size_t topic_size) |
| Start here to prepare an 'objects message'. Use obx_sync_msg_objects_builder_add() to set at least one object and then call obx_sync_send_msg_objects() or obx_sync_server_send_msg_objects() to initiate the sending process. More... | |
| OBX_C_API obx_err | obx_sync_msg_objects_builder_add (OBX_sync_msg_objects_builder *message, OBXSyncObjectType type, const void *data, size_t size, uint64_t id) |
| Adds an object to the given message (builder). There must be at least one message before sending. More... | |
| OBX_C_API obx_err | obx_sync_msg_objects_builder_discard (OBX_sync_msg_objects_builder *message) |
| Free the given message if you end up not sending it. Sending frees it already so never call this after obx_*_send(). More... | |
| OBX_C_API obx_err | obx_sync_send_msg_objects (OBX_sync *sync, OBX_sync_msg_objects_builder *message) |
| Sends the given 'objects message' from the client to the currently connected server. More... | |
| OBX_C_API void | obx_sync_listener_connect (OBX_sync *sync, OBX_sync_listener_connect *listener, void *listener_arg) |
| Set or overwrite a previously set 'connect' listener. More... | |
| OBX_C_API void | obx_sync_listener_disconnect (OBX_sync *sync, OBX_sync_listener_disconnect *listener, void *listener_arg) |
| Set or overwrite a previously set 'disconnect' listener. More... | |
| OBX_C_API void | obx_sync_listener_login (OBX_sync *sync, OBX_sync_listener_login *listener, void *listener_arg) |
| Set or overwrite a previously set 'login' listener. More... | |
| OBX_C_API void | obx_sync_listener_login_failure (OBX_sync *sync, OBX_sync_listener_login_failure *listener, void *listener_arg) |
| Set or overwrite a previously set 'login failure' listener. More... | |
| OBX_C_API void | obx_sync_listener_complete (OBX_sync *sync, OBX_sync_listener_complete *listener, void *listener_arg) |
| Set or overwrite a previously set 'complete' listener - notifies when the latest sync has finished. More... | |
| OBX_C_API void | obx_sync_listener_change (OBX_sync *sync, OBX_sync_listener_change *listener, void *listener_arg) |
| Set or overwrite a previously set 'change' listener - provides information about incoming changes. More... | |
| OBX_C_API void | obx_sync_listener_server_time (OBX_sync *sync, OBX_sync_listener_server_time *listener, void *listener_arg) |
| Set or overwrite a previously set 'serverTime' listener - provides current time updates from the sync-server. More... | |
| OBX_C_API void | obx_sync_listener_msg_objects (OBX_sync *sync, OBX_sync_listener_msg_objects *listener, void *listener_arg) |
| Set or overwrite a previously set 'objects message' listener to receive application specific data objects. More... | |
| OBX_C_API void | obx_sync_listener_error (OBX_sync *sync, OBX_sync_listener_error *error, void *listener_arg) |
| Set or overwrite a previously set 'error' listener - provides information about occurred sync-level errors. More... | |
| OBX_C_API obx_err | obx_sync_stats_u64 (OBX_sync *sync, OBXSyncStats counter_type, uint64_t *out_count) |
| Get u64 value for sync statistics. More... | |
| OBX_C_API OBX_sync_server * | obx_sync_server (OBX_store_options *store_options, const char *url) |
| Prepares an ObjectBox Sync Server to run within your application (embedded server) at the given URI. Note that you need a special sync edition, which includes the server components. Check https://objectbox.io/sync/. This call opens a store with the given options (also see obx_store_open()). The server's store is tied to the server itself and is closed when the server is closed. Before actually starting the server via obx_sync_server_start(), you can configure: More... | |
| OBX_C_API OBX_sync_server * | obx_sync_server_from_flat_options (OBX_store_options *store_options, const void *flat_options, size_t flat_options_size) |
| Like obx_sync_server(), but retrieves its options for the Sync Server from the given FlatBuffers options. More... | |
| OBX_C_API obx_err | obx_sync_server_close (OBX_sync_server *server) |
| Stops and closes (deletes) the sync server, freeing its resources. This includes the store associated with the server; it gets closed and must not be used anymore after this call. More... | |
| OBX_C_API OBX_store * | obx_sync_server_store (OBX_sync_server *server) |
| Gets the store this server uses. This is owned by the server and must NOT be closed manually with obx_store_close(). More... | |
| OBX_C_API obx_err | obx_sync_server_certificate_path (OBX_sync_server *server, const char *certificate_path) |
| Sets SSL certificate for the server to use. Use before obx_sync_server_start(). More... | |
| OBX_C_API obx_err | obx_sync_server_credentials (OBX_sync_server *server, OBXSyncCredentialsType type, const void *data, size_t size) |
| Sets credentials for the server to accept. Use before obx_sync_server_start(). More... | |
| OBX_C_API obx_err | obx_sync_server_enable_auth (OBX_sync_server *server, OBXSyncCredentialsType type) |
| Enables authenticator for server. Can be called multiple times. Use before obx_sync_server_start(). Use obx_sync_server_credentials() for authenticators which requires additional credentials data (i.e. Google Auth and shared secrets authenticators). More... | |
| OBX_C_API obx_err | obx_sync_server_worker_threads (OBX_sync_server *server, int thread_count) |
| Sets the number of worker threads. Use before obx_sync_server_start(). More... | |
| OBX_C_API obx_err | obx_sync_server_history_max_size_in_kb (OBX_sync_server *server, uint64_t max_in_kb, uint64_t target_in_kb) |
| Sets a maximum size for sync history entries to limit storage: old entries are removed to stay below this limit. Deleting older history entries may require clients to do a full sync if they have not contacted the server for a certain time. More... | |
| OBX_C_API obx_err | obx_sync_server_cluster_id (OBX_sync_server *server, const char *id) |
| Configures the cluster ID for the given embedded server (the cluster feature must be enabled). More... | |
| OBX_C_API obx_err | obx_sync_server_add_cluster_peer (OBX_sync_server *server, const char *url, OBXSyncCredentialsType credentials_type, const void *credentials, size_t credentials_size, uint32_t flags) |
| Adds a remote cluster peer that can be connected to using the given URL and credentials. Call this method multiple times to add multiple peers (at least 2 times for a cluster of 3). More... | |
| OBX_C_API obx_err | obx_sync_server_listener_change (OBX_sync_server *server, OBX_sync_listener_change *listener, void *listener_arg) |
| Set or overwrite a previously set 'change' listener - provides information about incoming changes. More... | |
| OBX_C_API obx_err | obx_sync_server_listener_msg_objects (OBX_sync_server *server, OBX_sync_listener_msg_objects *listener, void *listener_arg) |
| Set or overwrite a previously set 'objects message' listener to receive application specific data objects. More... | |
| OBX_C_API obx_err | obx_sync_server_start (OBX_sync_server *server) |
| After the sync server is fully configured (e.g. credentials), this will actually start the server. Once this call returns, the server is ready to accept client connections. Also, port and URL will be available. More... | |
| OBX_C_API obx_err | obx_sync_server_stop (OBX_sync_server *server) |
| Stops this sync server. Does nothing if it is already stopped. More... | |
| OBX_C_API bool | obx_sync_server_running (OBX_sync_server *server) |
| Whether the server is up and running. More... | |
| OBX_C_API const char * | obx_sync_server_url (OBX_sync_server *server) |
| Returns a URL this server is listening on, including the bound port (see obx_sync_server_port(). The returned char* is valid until another call to obx_sync_server_url() or the server is closed. More... | |
| OBX_C_API uint16_t | obx_sync_server_port (OBX_sync_server *server) |
| Returns a port this server listens on. This is especially useful if the port was assigned arbitrarily (a "0" port was used in the URL given to obx_sync_server()). More... | |
| OBX_C_API uint64_t | obx_sync_server_connections (OBX_sync_server *server) |
| Returns the number of clients connected to this server. More... | |
| OBX_C_API obx_err | obx_sync_server_stats_u64 (OBX_sync_server *server, OBXSyncServerStats counter_type, uint64_t *out_value) |
| Get u64 value for sync server statistics. More... | |
| OBX_C_API obx_err | obx_sync_server_stats_f64 (OBX_sync_server *server, OBXSyncServerStats counter_type, double *out_value) |
| Get double value for sync server statistics. More... | |
| OBX_C_API const char * | obx_sync_server_stats_string (OBX_sync_server *server, bool include_zero_values) |
| Get server runtime statistics. The returned char* is valid until another call to obx_sync_server_stats_string() or the server is closed. More... | |
| OBX_C_API obx_err | obx_sync_server_send_msg_objects (OBX_sync_server *server, OBX_sync_msg_objects_builder *message) |
| Broadcast the given 'objects message' from the server to all currently connected (and logged-in) clients. More... | |
| OBX_C_API OBX_admin * | obx_sync_server_admin (OBX_sync_server *server, OBX_admin_options *options) |
| Configure admin with a sync server, attaching the store and enabling custom sync-server functionality in the UI. This is a replacement for obx_admin_opt_store() and obx_admin_opt_store_path() - don't set them for the server. After configuring, this acts as obx_admin() - see for more details. You must use obx_admin_close() to stop & free resources after you're done; obx_sync_server_stop() doesn't do that. More... | |
| OBX_C_API obx_err | obx_custom_msg_server_register (const char *protocol, OBX_custom_msg_server_functions *functions, void *config_user_data) |
| Must be called to register a protocol for a custom messaging server. Call before starting a server. More... | |
| OBX_C_API uint64_t | obx_custom_msg_server_add_client_connection (uint64_t server_id, void *user_data) |
| Must be called from the custom server when a new client connection becomes available. More... | |
| OBX_C_API obx_err | obx_custom_msg_server_remove_client_connection (uint64_t server_id, uint64_t client_connection_id) |
| Must be called from the custom server when a client connection becomes inactive (e.g. closed) and can be removed. More... | |
| OBX_C_API obx_err | obx_custom_msg_server_receive_message_from_client (uint64_t server_id, uint64_t client_connection_id, const void *message_data, size_t message_size) |
| Must be called from the custom server when a message is received from a client connection. More... | |
| OBX_C_API obx_err | obx_custom_msg_client_register (const char *protocol, OBX_custom_msg_client_functions *functions, void *config_user_data) |
| Must be called to register a protocol for your custom messaging client. Call before starting a client. More... | |
| OBX_C_API obx_err | obx_custom_msg_client_receive_message_from_server (uint64_t client_id, const void *message_data, size_t message_size) |
| The custom msg client must call this whenever a message is received from the server. More... | |
| OBX_C_API obx_err | obx_custom_msg_client_set_state (uint64_t client_id, OBXCustomMsgClientState state) |
| The custom msg client must call this whenever the state (according to given enum values) changes. More... | |
| OBX_C_API obx_err | obx_custom_msg_client_trigger_reconnect (uint64_t client_id) |
| The custom msg client may call this if it has knowledge when a reconnection attempt makes sense, for example, when the network becomes available. More... | |
| typedef void OBX_custom_msg_client_func_clear_outgoing_messages(void *client_user_data) |
Callback to clear all outgoing messages. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details.
| client_user_data | user supplied data returned by the function that created the client |
| typedef bool OBX_custom_msg_client_func_connect(void *client_user_data) |
Callback that tells the client it shall start trying to connect. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details.
| client_user_data | user supplied data returned by the function that created the client |
| typedef void* OBX_custom_msg_client_func_create(uint64_t client_id, const char *url, const char *cert_path, void *config_user_data) |
Callback to create a custom messaging client. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details.
| client_id | the ID that was assigned to the client instance |
| config_user_data | user provided data set at registration of the client |
| typedef void OBX_custom_msg_client_func_disconnect(bool clear_outgoing_messages, void *client_user_data) |
Callback that tells the client it shall disconnect. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details.
| client_user_data | user supplied data returned by the function that created the client |
| typedef void OBX_custom_msg_client_func_join(void *client_user_data) |
Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details.
| client_user_data | user supplied data returned by the function that created the client |
| typedef bool OBX_custom_msg_client_func_send_async(OBX_bytes_lazy *bytes, void *client_user_data) |
Callback to enqueue a message for sending. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details.
| bytes | lazy bytes storing the message |
| client_user_data | user supplied data returned by the function that created the client |
| typedef void OBX_custom_msg_client_func_shutdown(void *client_user_data) |
Callback to shut the custom client down, freeing its resources. The custom client is not used after this point. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details.
| client_user_data | user supplied data returned by the function that created the client |
| typedef obx_err OBX_custom_msg_client_func_start(void *client_user_data) |
Callback to start the client. Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details.
| client_user_data | user supplied data returned by the function that created the client |
| typedef void OBX_custom_msg_client_func_stop(void *client_user_data) |
Callback to stop and close the client (e.g. further messages delivery will be rejected). Must be provided to implement a custom client. See notes on OBX_custom_msg_client_functions for more details.
| client_user_data | user supplied data returned by the function that created the client |
| typedef struct OBX_custom_msg_client_functions OBX_custom_msg_client_functions |
Struct of the custom client function callbacks. In order to implement the custom client, you must provide custom methods for each of the members of this struct. This is then passed to obx_custom_msg_client_register() to register the custom client.
| typedef void OBX_custom_msg_server_func_client_connection_close(void *server_user_data, void *connection_user_data) |
Callback to close the sync client connection to the custom server. Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details.
| server_user_data | User supplied data returned by the function that created the server |
| typedef bool OBX_custom_msg_server_func_client_connection_send_async(OBX_bytes_lazy *bytes, void *server_user_data, void *connection_user_data) |
Callback to enqueue a message for sending. Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details.
| bytes | lazy bytes storing the message |
| server_user_data | User supplied data returned by the function that created the server |
| typedef void OBX_custom_msg_server_func_client_connection_shutdown(void *connection_user_data) |
Callback to shutdown and free all resources associated with the sync client connection to the custom server. Note that the custom server may already have been shutdown at this point (e.g. no server user data is supplied). Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details.
| server_user_data | User supplied data returned by the function that created the server |
| typedef void* OBX_custom_msg_server_func_create(uint64_t server_id, const char *url, const char *cert_path, void *config_user_data) |
Callback to create a custom messaging server. Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details.
| server_id | the ID that was assigned to the custom server instance |
| config_user_data | user provided data set at registration of the server |
| typedef void OBX_custom_msg_server_func_shutdown(void *server_user_data) |
Callback to shut the custom server down, freeing its resources (the custom server is not used after this point). Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details.
| server_user_data | User supplied data returned by the function that created the server |
| typedef obx_err OBX_custom_msg_server_func_start(void *server_user_data, uint64_t *out_port) |
Callback to start a custom server. Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details.
| server_user_data | User supplied data returned by the function that created the server |
| out_port | When starting, the custom server can optionally supply a port by writing to the given pointer. The port value is arbitrary and, for now, is only used for debug logs. |
| typedef void OBX_custom_msg_server_func_stop(void *server_user_data) |
Callback to stop and close the custom server (e.g. further messages delivery will be rejected). Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details. This includes the store associated with the server; it gets closed and must not be used anymore after this call.
| server_user_data | User supplied data returned by the function that created the server |
| typedef struct OBX_custom_msg_server_functions OBX_custom_msg_server_functions |
Struct of the custom server function callbacks. In order to implement the custom server, you must provide custom methods for each of the members of this struct. This is then passed to obx_custom_msg_server_register() to register the custom server.
| typedef struct OBX_sync_change OBX_sync_change |
| typedef struct OBX_sync_change_array OBX_sync_change_array |
| typedef void OBX_sync_listener_change(void *arg, const OBX_sync_change_array *changes) |
Called with fine grained sync changes (IDs of put and removed entities)
| arg | is a pass-through argument passed to the called API |
| typedef void OBX_sync_listener_complete(void *arg) |
Called when synchronization is complete.
| arg | is a pass-through argument passed to the called API |
| typedef void OBX_sync_listener_connect(void *arg) |
Called when connection is established.
| arg | is a pass-through argument passed to the called API |
| typedef void OBX_sync_listener_disconnect(void *arg) |
Called when connection is closed/lost.
| arg | is a pass-through argument passed to the called API |
| typedef void OBX_sync_listener_error(void *arg, OBXSyncError error) |
Callend when sync-level errors occur.
| arg | is a pass-through argument passed to the called API |
| error | error code indicating sync-level error events |
| typedef void OBX_sync_listener_login(void *arg) |
Called on successful login.
| arg | is a pass-through argument passed to the called API |
| typedef void OBX_sync_listener_login_failure(void *arg, OBXSyncCode code) |
Called on a login failure.
| arg | is a pass-through argument passed to the called API |
| code | error code indicating why the login failed |
| typedef void OBX_sync_listener_msg_objects(void *arg, const OBX_sync_msg_objects *msg_objects) |
| typedef void OBX_sync_listener_server_time(void *arg, int64_t timestamp_ns) |
Called when a server time information is received on the client.
| arg | is a pass-through argument passed to the called API |
| timestamp_ns | is timestamp in nanoseconds since Unix epoch |
| typedef struct OBX_sync_msg_objects OBX_sync_msg_objects |
Incubating message that carries multiple data "objects" (e.g. FlatBuffers, strings, raw bytes). Interpretation is up to the application. Does not involve any persistence or delivery guarantees at the moment.
| typedef struct OBX_sync_msg_objects_builder OBX_sync_msg_objects_builder |
| typedef struct OBX_sync_object OBX_sync_object |
A single data object contained in a OBX_sync_msg_objects message.
| typedef struct OBX_sync_server OBX_sync_server |
States of custom msg client that must be forwarded to obx_custom_msg_client_set_state().
| Enumerator | |
|---|---|
| OBXCustomMsgClientState_Connecting | |
| OBXCustomMsgClientState_Connected | |
| OBXCustomMsgClientState_Disconnected | |
| Enumerator | |
|---|---|
| OBXRequestUpdatesMode_MANUAL | no updates by default, obx_sync_updates_request() must be called manually |
| OBXRequestUpdatesMode_AUTO | same as calling obx_sync_updates_request(sync, TRUE) default mode unless overridden by obx_sync_request_updates_mode |
| OBXRequestUpdatesMode_AUTO_NO_PUSHES | same as calling obx_sync_updates_request(sync, FALSE) |
| enum OBXSyncCode |
Specifies user-side credential types as well as server-side authenticator types. Some credential types do not make sense as authenticators such as OBXSyncCredentialsType_USER_PASSWORD which specifies a generic client-side credential type.
| enum OBXSyncError |
Sync-level error reporting codes, passed via obx_sync_listener_error().
| enum OBXSyncObjectType |
| enum OBXSyncServerStats |
Stats counter type IDs as passed to obx_sync_server_stats_u64() (for u64 values) and obx_sync_server_stats_f64() (for double (f64) values).
| enum OBXSyncState |
| enum OBXSyncStats |
Stats counter type IDs as passed to obx_sync_stats_u64().
| OBX_C_API obx_err obx_custom_msg_client_receive_message_from_server | ( | uint64_t | client_id, |
| const void * | message_data, | ||
| size_t | message_size | ||
| ) |
The custom msg client must call this whenever a message is received from the server.
| client_id | the ID that was assigned to the client instance |
| message_data | the message data in bytes |
| OBX_C_API obx_err obx_custom_msg_client_register | ( | const char * | protocol, |
| OBX_custom_msg_client_functions * | functions, | ||
| void * | config_user_data | ||
| ) |
Must be called to register a protocol for your custom messaging client. Call before starting a client.
| protocol | the communication protocol to use, e.g. "tcp" |
| OBX_C_API obx_err obx_custom_msg_client_set_state | ( | uint64_t | client_id, |
| OBXCustomMsgClientState | state | ||
| ) |
The custom msg client must call this whenever the state (according to given enum values) changes.
| client_id | the ID that was assigned to the client instance |
| state | the state to transition the custom client to |
The custom msg client may call this if it has knowledge when a reconnection attempt makes sense, for example, when the network becomes available.
| client_id | the ID that was assigned to the client instance |
| OBX_C_API uint64_t obx_custom_msg_server_add_client_connection | ( | uint64_t | server_id, |
| void * | user_data | ||
| ) |
Must be called from the custom server when a new client connection becomes available.
| server_id | the ID that was assigned to the custom server instance |
| user_data | user provided data set at registration of custom server |
| OBX_C_API obx_err obx_custom_msg_server_receive_message_from_client | ( | uint64_t | server_id, |
| uint64_t | client_connection_id, | ||
| const void * | message_data, | ||
| size_t | message_size | ||
| ) |
Must be called from the custom server when a message is received from a client connection.
| server_id | the ID that was assigned to the custom server instance |
| client_connection_id | the ID that was assigned to the custom client connection |
| message_data | the message data in bytes |
| OBX_C_API obx_err obx_custom_msg_server_register | ( | const char * | protocol, |
| OBX_custom_msg_server_functions * | functions, | ||
| void * | config_user_data | ||
| ) |
Must be called to register a protocol for a custom messaging server. Call before starting a server.
| protocol | the communication protocol to use, e.g. "tcp" |
| functions | the custom server function callbacks |
| config_user_data | user provided data set at registration of custom server |
| OBX_C_API obx_err obx_custom_msg_server_remove_client_connection | ( | uint64_t | server_id, |
| uint64_t | client_connection_id | ||
| ) |
Must be called from the custom server when a client connection becomes inactive (e.g. closed) and can be removed.
| server_id | the ID that was assigned to the custom server instance |
| client_connection_id | the ID that was assigned to the custom client connection |
Creates a sync client associated with the given store and sync server URL. This does not initiate any connection attempts yet: call obx_sync_start() to do so. Before obx_sync_start(), you must configure credentials via obx_sync_credentials. By default a sync client automatically receives updates from the server once login succeeded. To configure this differently, call obx_sync_request_updates_mode() with the wanted mode.
Stops and closes (deletes) the sync client, freeing its resources.
| OBX_C_API obx_err obx_sync_credentials | ( | OBX_sync * | sync, |
| OBXSyncCredentialsType | type, | ||
| const void * | data, | ||
| size_t | size | ||
| ) |
Sets credentials to authenticate the client with the server. See OBXSyncCredentialsType for available options. The accepted OBXSyncCredentials type depends on your sync-server configuration.
| data | may be NULL in combination with OBXSyncCredentialsType_NONE |
| OBX_C_API obx_err obx_sync_credentials_user_password | ( | OBX_sync * | sync, |
| OBXSyncCredentialsType | type, | ||
| const char * | username, | ||
| const char * | password | ||
| ) |
Set username/password credentials to authenticate the client with the server. This is suitable for OBXSyncCredentialsType_OBX_ADMIN_USER and OBXSyncCredentialsType_USER_PASSWORD credential types. Use obx_sync_credentials() for other credential types.
| type | should be OBXSyncCredentialsType_OBX_ADMIN_USER or OBXSyncCredentialsType_USER_PASSWORD |
Experimental. This API is likely to be replaced/removed in a future version. Quickly bring our database up-to-date in a single transaction, without transmitting all the history. Good for initial sync of new clients.
Sets the interval in which the client sends "heartbeat" messages to the server, keeping the connection alive. To detect disconnects early on the client side, you can also use heartbeats with a smaller interval. Use with caution, setting a low value (i.e. sending heartbeat very often) may cause an excessive network usage as well as high server load (with many clients).
| interval_ms | interval in milliseconds; the default is 25 minutes (1 500 000 milliseconds), which is also the allowed maximum. |
| OBX_C_API void obx_sync_listener_change | ( | OBX_sync * | sync, |
| OBX_sync_listener_change * | listener, | ||
| void * | listener_arg | ||
| ) |
Set or overwrite a previously set 'change' listener - provides information about incoming changes.
| listener | set NULL to reset |
| listener_arg | is a pass-through argument passed to the listener |
| OBX_C_API void obx_sync_listener_complete | ( | OBX_sync * | sync, |
| OBX_sync_listener_complete * | listener, | ||
| void * | listener_arg | ||
| ) |
Set or overwrite a previously set 'complete' listener - notifies when the latest sync has finished.
| listener | set NULL to reset |
| listener_arg | is a pass-through argument passed to the listener |
| OBX_C_API void obx_sync_listener_connect | ( | OBX_sync * | sync, |
| OBX_sync_listener_connect * | listener, | ||
| void * | listener_arg | ||
| ) |
Set or overwrite a previously set 'connect' listener.
| listener | set NULL to reset |
| listener_arg | is a pass-through argument passed to the listener |
| OBX_C_API void obx_sync_listener_disconnect | ( | OBX_sync * | sync, |
| OBX_sync_listener_disconnect * | listener, | ||
| void * | listener_arg | ||
| ) |
Set or overwrite a previously set 'disconnect' listener.
| listener | set NULL to reset |
| listener_arg | is a pass-through argument passed to the listener |
| OBX_C_API void obx_sync_listener_error | ( | OBX_sync * | sync, |
| OBX_sync_listener_error * | error, | ||
| void * | listener_arg | ||
| ) |
Set or overwrite a previously set 'error' listener - provides information about occurred sync-level errors.
| listener | set NULL to reset |
| listener_arg | is a pass-through argument passed to the listener |
| OBX_C_API void obx_sync_listener_login | ( | OBX_sync * | sync, |
| OBX_sync_listener_login * | listener, | ||
| void * | listener_arg | ||
| ) |
Set or overwrite a previously set 'login' listener.
| listener | set NULL to reset |
| listener_arg | is a pass-through argument passed to the listener |
| OBX_C_API void obx_sync_listener_login_failure | ( | OBX_sync * | sync, |
| OBX_sync_listener_login_failure * | listener, | ||
| void * | listener_arg | ||
| ) |
Set or overwrite a previously set 'login failure' listener.
| listener | set NULL to reset |
| listener_arg | is a pass-through argument passed to the listener |
| OBX_C_API void obx_sync_listener_msg_objects | ( | OBX_sync * | sync, |
| OBX_sync_listener_msg_objects * | listener, | ||
| void * | listener_arg | ||
| ) |
Set or overwrite a previously set 'objects message' listener to receive application specific data objects.
| listener | set NULL to reset |
| listener_arg | is a pass-through argument passed to the listener |
| OBX_C_API void obx_sync_listener_server_time | ( | OBX_sync * | sync, |
| OBX_sync_listener_server_time * | listener, | ||
| void * | listener_arg | ||
| ) |
Set or overwrite a previously set 'serverTime' listener - provides current time updates from the sync-server.
| listener | set NULL to reset |
| listener_arg | is a pass-through argument passed to the listener |
Configures the maximum number of outgoing TX messages that can be sent without an ACK from the server.
| OBX_C_API OBX_sync_msg_objects_builder* obx_sync_msg_objects_builder | ( | const void * | topic, |
| size_t | topic_size | ||
| ) |
Start here to prepare an 'objects message'. Use obx_sync_msg_objects_builder_add() to set at least one object and then call obx_sync_send_msg_objects() or obx_sync_server_send_msg_objects() to initiate the sending process.
| topic | optional, application-specific message qualifier (may be NULL), usually a string but can also be binary |
| OBX_C_API obx_err obx_sync_msg_objects_builder_add | ( | OBX_sync_msg_objects_builder * | message, |
| OBXSyncObjectType | type, | ||
| const void * | data, | ||
| size_t | size, | ||
| uint64_t | id | ||
| ) |
Adds an object to the given message (builder). There must be at least one message before sending.
| id | an optional (pass 0 if you don't need it) value that the application can use identify the object |
| OBX_C_API obx_err obx_sync_msg_objects_builder_discard | ( | OBX_sync_msg_objects_builder * | message | ) |
Free the given message if you end up not sending it. Sending frees it already so never call this after obx_*_send().
| OBX_C_API obx_err obx_sync_outgoing_message_count | ( | OBX_sync * | sync, |
| uint64_t | limit, | ||
| uint64_t * | out_count | ||
| ) |
Count the number of messages in the outgoing queue, i.e. those waiting to be sent to the server.
| limit | pass 0 to count all messages without any limitation or a lower number that's enough for your app logic. |
| OBX_C_API uint32_t obx_sync_protocol_version | ( | ) |
Gets the protocol version this client uses.
Gets the protocol version of the server after a connection is established (or attempted), zero otherwise.
| OBX_C_API obx_err obx_sync_request_updates_mode | ( | OBX_sync * | sync, |
| OBXRequestUpdatesMode | mode | ||
| ) |
Switches operation mode that's initialized after successful login Must be called before obx_sync_start() (returns OBX_ERROR_ILLEGAL_STATE if it was already started)
Triggers the heartbeat sending immediately. This lets you check the network connection at any time.
| OBX_C_API obx_err obx_sync_send_msg_objects | ( | OBX_sync * | sync, |
| OBX_sync_msg_objects_builder * | message | ||
| ) |
Sends the given 'objects message' from the client to the currently connected server.
| message | the prepared outgoing message; it will be freed along with any associated resources during this call (regardless of the call's success/failure outcome). |
| OBX_C_API OBX_sync_server* obx_sync_server | ( | OBX_store_options * | store_options, |
| const char * | url | ||
| ) |
Prepares an ObjectBox Sync Server to run within your application (embedded server) at the given URI. Note that you need a special sync edition, which includes the server components. Check https://objectbox.io/sync/. This call opens a store with the given options (also see obx_store_open()). The server's store is tied to the server itself and is closed when the server is closed. Before actually starting the server via obx_sync_server_start(), you can configure:
| store_options | Options for the server's store. It is freed automatically (same as with obx_store_open()) - don't use or free it afterwards. |
| url | The URL (following the pattern "protocol://IP:port") the server should listen on. Supported protocols are "ws" (WebSockets) and "wss" (secure WebSockets). To use the latter ("wss"), you must also call obx_sync_server_certificate_path(). To bind to all available interfaces, including those that are available from the "outside", use 0.0.0.0 as the IP. On the other hand, "127.0.0.1" is typically (may be OS dependent) only available on the same device. If you do not require a fixed port, use 0 (zero) as a port to tell the server to pick an arbitrary port that is available. The port can be queried via obx_sync_server_port() once the server was started. Examples: "ws://0.0.0.0:9999" could be used during development (WS no certificate config needed), while in a production system, you may want to use WSS and a specific IP for security reasons. |
| OBX_C_API obx_err obx_sync_server_add_cluster_peer | ( | OBX_sync_server * | server, |
| const char * | url, | ||
| OBXSyncCredentialsType | credentials_type, | ||
| const void * | credentials, | ||
| size_t | credentials_size, | ||
| uint32_t | flags | ||
| ) |
Adds a remote cluster peer that can be connected to using the given URL and credentials. Call this method multiple times to add multiple peers (at least 2 times for a cluster of 3).
| url | URL to the remote cluster peer used to connect it. |
| flags | For now, always pass 0. |
| credentials | the credentials provided to the remote peer to login (it must match the remote's configuration). May be NULL in combination with OBXSyncCredentialsType_NONE. |
| OBX_C_API OBX_admin* obx_sync_server_admin | ( | OBX_sync_server * | server, |
| OBX_admin_options * | options | ||
| ) |
Configure admin with a sync server, attaching the store and enabling custom sync-server functionality in the UI. This is a replacement for obx_admin_opt_store() and obx_admin_opt_store_path() - don't set them for the server. After configuring, this acts as obx_admin() - see for more details. You must use obx_admin_close() to stop & free resources after you're done; obx_sync_server_stop() doesn't do that.
| options | configuration set up with obx_admin_opt_*. You can pass NULL to use the default options. |
| OBX_C_API obx_err obx_sync_server_certificate_path | ( | OBX_sync_server * | server, |
| const char * | certificate_path | ||
| ) |
Sets SSL certificate for the server to use. Use before obx_sync_server_start().
| OBX_C_API obx_err obx_sync_server_close | ( | OBX_sync_server * | server | ) |
Stops and closes (deletes) the sync server, freeing its resources. This includes the store associated with the server; it gets closed and must not be used anymore after this call.
| OBX_C_API obx_err obx_sync_server_cluster_id | ( | OBX_sync_server * | server, |
| const char * | id | ||
| ) |
Configures the cluster ID for the given embedded server (the cluster feature must be enabled).
| id | A user defined string to identify the cluster (all cluster peer must share the same ID). |
| OBX_C_API uint64_t obx_sync_server_connections | ( | OBX_sync_server * | server | ) |
Returns the number of clients connected to this server.
| OBX_C_API obx_err obx_sync_server_credentials | ( | OBX_sync_server * | server, |
| OBXSyncCredentialsType | type, | ||
| const void * | data, | ||
| size_t | size | ||
| ) |
Sets credentials for the server to accept. Use before obx_sync_server_start().
| data | may be NULL in combination with OBXSyncCredentialsType_NONE |
| OBX_C_API obx_err obx_sync_server_enable_auth | ( | OBX_sync_server * | server, |
| OBXSyncCredentialsType | type | ||
| ) |
Enables authenticator for server. Can be called multiple times. Use before obx_sync_server_start(). Use obx_sync_server_credentials() for authenticators which requires additional credentials data (i.e. Google Auth and shared secrets authenticators).
| type | should be one of the available authentications, it should not be OBXSyncCredentialsType_USER_PASSWORD. |
| OBX_C_API OBX_sync_server* obx_sync_server_from_flat_options | ( | OBX_store_options * | store_options, |
| const void * | flat_options, | ||
| size_t | flat_options_size | ||
| ) |
Like obx_sync_server(), but retrieves its options for the Sync Server from the given FlatBuffers options.
| flat_options | FlatBuffers serialized options for the server (start of the bytes buffer, not the "table"). |
| flat_options_size | Size of the FlatBuffers serialized options. |
| OBX_C_API obx_err obx_sync_server_history_max_size_in_kb | ( | OBX_sync_server * | server, |
| uint64_t | max_in_kb, | ||
| uint64_t | target_in_kb | ||
| ) |
Sets a maximum size for sync history entries to limit storage: old entries are removed to stay below this limit. Deleting older history entries may require clients to do a full sync if they have not contacted the server for a certain time.
| max_in_kb | Once this maximum size is reached, old history entries are deleted (default 0: no limit). |
| target_in_kb | If this value is non-zero, the deletion of old history entries is extended until reaching this target (lower than the maximum) allowing deletion "batching", which may be more efficient. If zero, the deletion stops already stops when reaching the max size (or lower). |
| OBX_C_API obx_err obx_sync_server_listener_change | ( | OBX_sync_server * | server, |
| OBX_sync_listener_change * | listener, | ||
| void * | listener_arg | ||
| ) |
Set or overwrite a previously set 'change' listener - provides information about incoming changes.
| listener | set NULL to reset |
| listener_arg | is a pass-through argument passed to the listener |
| OBX_C_API obx_err obx_sync_server_listener_msg_objects | ( | OBX_sync_server * | server, |
| OBX_sync_listener_msg_objects * | listener, | ||
| void * | listener_arg | ||
| ) |
Set or overwrite a previously set 'objects message' listener to receive application specific data objects.
| listener | set NULL to reset |
| listener_arg | is a pass-through argument passed to the listener |
| OBX_C_API uint16_t obx_sync_server_port | ( | OBX_sync_server * | server | ) |
Returns a port this server listens on. This is especially useful if the port was assigned arbitrarily (a "0" port was used in the URL given to obx_sync_server()).
| OBX_C_API bool obx_sync_server_running | ( | OBX_sync_server * | server | ) |
Whether the server is up and running.
| OBX_C_API obx_err obx_sync_server_send_msg_objects | ( | OBX_sync_server * | server, |
| OBX_sync_msg_objects_builder * | message | ||
| ) |
Broadcast the given 'objects message' from the server to all currently connected (and logged-in) clients.
| message | the prepared outgoing message; it will be freed along with any associated resources during this call (regardless of the call's success/failure outcome). |
| OBX_C_API obx_err obx_sync_server_start | ( | OBX_sync_server * | server | ) |
After the sync server is fully configured (e.g. credentials), this will actually start the server. Once this call returns, the server is ready to accept client connections. Also, port and URL will be available.
| OBX_C_API obx_err obx_sync_server_stats_f64 | ( | OBX_sync_server * | server, |
| OBXSyncServerStats | counter_type, | ||
| double * | out_value | ||
| ) |
Get double value for sync server statistics.
| counter_type | the counter value to be read (make sure to use a double (f64) metric value type). |
| out_count | receives the counter value. |
| OBX_C_API const char* obx_sync_server_stats_string | ( | OBX_sync_server * | server, |
| bool | include_zero_values | ||
| ) |
Get server runtime statistics. The returned char* is valid until another call to obx_sync_server_stats_string() or the server is closed.
| OBX_C_API obx_err obx_sync_server_stats_u64 | ( | OBX_sync_server * | server, |
| OBXSyncServerStats | counter_type, | ||
| uint64_t * | out_value | ||
| ) |
Get u64 value for sync server statistics.
| counter_type | the counter value to be read (make sure to choose a uint64_t (u64) metric value type). |
| out_count | receives the counter value. |
| OBX_C_API obx_err obx_sync_server_stop | ( | OBX_sync_server * | server | ) |
Stops this sync server. Does nothing if it is already stopped.
| OBX_C_API OBX_store* obx_sync_server_store | ( | OBX_sync_server * | server | ) |
Gets the store this server uses. This is owned by the server and must NOT be closed manually with obx_store_close().
| OBX_C_API const char* obx_sync_server_url | ( | OBX_sync_server * | server | ) |
Returns a URL this server is listening on, including the bound port (see obx_sync_server_port(). The returned char* is valid until another call to obx_sync_server_url() or the server is closed.
| OBX_C_API obx_err obx_sync_server_worker_threads | ( | OBX_sync_server * | server, |
| int | thread_count | ||
| ) |
Sets the number of worker threads. Use before obx_sync_server_start().
| thread_count | The default is "0" which is hardware dependent, e.g. a multiple of CPU "cores". |
Once the sync client is configured, you can "start" it to initiate synchronization. This method triggers communication in the background and will return immediately. If the synchronization destination is reachable, this background thread will connect to the server, log in (authenticate) and, depending on "update request mode", start syncing data. If the device, network or server is currently offline, connection attempts will be retried later using increasing backoff intervals.
| OBX_C_API OBXSyncState obx_sync_state | ( | OBX_sync * | sync | ) |
Gets the current state of the sync client (0 on error, e.g. given sync was NULL)
| OBX_C_API obx_err obx_sync_stats_u64 | ( | OBX_sync * | sync, |
| OBXSyncStats | counter_type, | ||
| uint64_t * | out_count | ||
| ) |
Get u64 value for sync statistics.
| counter_type | the counter value to be read. |
| out_count | receives the counter value. |
Stops this sync client and thus stopping the synchronization. Does nothing if it is already stopped.
Estimates the current server timestamp based on the last known server time and local steady clock.
| out_timestamp_ns | - unix timestamp in nanoseconds - may be set to zero if the last server's time is unknown. |
Returns the estimated difference between the server time and the local timestamp. Equivalent to calculating obx_sync_time_server() - "current time" (nanos since epoch).
| out_diff_ns | time difference in nanoseconds; e.g. positive if server time is ahead of local time. Set to 0 if there has not been a server contact yet and thus the server's time is unknown. |
Triggers a reconnection attempt immediately. By default, an increasing backoff interval is used for reconnection attempts. But sometimes the user of this API has additional knowledge and can initiate a reconnection attempt sooner.
Cancel updates from the server (once received, the server stops sending updates). The counterpart to obx_sync_updates_request(). This should only be called in "logged in" state and there are no delivery guarantees given.
Request updates from the server since we last synced our database.
| subscribe_for_pushes | keep sending us future updates as they come in. This should only be called in "logged in" state and there are no delivery guarantees given. |
| OBX_C_API OBX_sync* obx_sync_urls | ( | OBX_store * | store, |
| const char * | server_urls[], | ||
| size_t | server_urls_count | ||
| ) |
Creates a sync client associated with the given store and a list of sync server URL. For details, see obx_sync()
Waits for the sync client to get into the given state or until the given timeout is reached. For an asynchronous alternative, please check the listeners.
| timeout_millis | Must be greater than 0 |
1.9.1