|
| 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.
|
| |
| 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 void | OBX_sync_listener_connect(void *arg) |
| | Called when connection is established.
|
| |
| typedef void | OBX_sync_listener_disconnect(void *arg) |
| | Called when connection is closed/lost.
|
| |
| typedef void | OBX_sync_listener_login(void *arg) |
| | Called on successful login.
|
| |
| typedef void | OBX_sync_listener_login_failure(void *arg, OBXSyncCode code) |
| | Called on a login failure.
|
| |
| typedef void | OBX_sync_listener_complete(void *arg) |
| | Called when synchronization is complete.
|
| |
| typedef void | OBX_sync_listener_error(void *arg, OBXSyncError error) |
| | Callend when sync-level errors occur.
|
| |
| 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)
|
| |
| typedef void | OBX_sync_listener_server_time(void *arg, int64_t timestamp_ns) |
| | Called when a server time information is received on the client.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
|
| 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.
|
| |
| 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()
|
| |
| OBX_C_API obx_err | obx_sync_close (OBX_sync *sync) |
| | 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. Any credentials that were set before are replaced; if you want to pass multiple credentials, use obx_sync_credentials_add() instead. If the client was waiting for credentials, this can trigger a reconnection/login attempt.
|
| |
| 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.
|
| |
| OBX_C_API obx_err | obx_sync_credentials_add (OBX_sync *sync, OBXSyncCredentialsType type, const void *data, size_t size, bool complete) |
| | For authentication with multiple credentials, collect credentials by calling this function multiple times. When adding the last credentials element, the "complete" flag must be set to true. When completed, it will "activate" the collected credentials and replace any previously set credentials and potentially trigger a reconnection/login attempt.
|
| |
| OBX_C_API obx_err | obx_sync_credentials_add_user_password (OBX_sync *sync, OBXSyncCredentialsType type, const char *username, const char *password, bool complete) |
| | For authentication with multiple credentials, collect credentials by calling this function multiple times. When adding the last credentials element, the "complete" flag must be set to true. When completed, it will "activate" the collected credentials and replace any previously set credentials and potentially trigger a reconnection/login attempt.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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).
|
| |
| 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.
|
| |
| 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)
|
| |
| 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.
|
| |
| 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.
|
| |
| 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_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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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).
|
| |
| OBX_C_API uint32_t | obx_sync_protocol_version () |
| | Gets the protocol version this client uses.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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_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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| OBX_C_API void | obx_sync_listener_error (OBX_sync *sync, OBX_sync_listener_error *listener, void *listener_arg) |
| | Set or overwrite a previously set 'error' listener - provides information about occurred sync-level errors.
|
| |
| 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.
|
| |
| 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:
|
| |
| 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.
|
| |
| 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_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 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_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().
|
| |
| 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).
|
| |
| 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().
|
| |
| 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.
|
| |
| 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).
|
| |
| 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).
|
| |
| 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.
|
| |
| 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.
|
| |
| 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_stop (OBX_sync_server *server) |
| | Stops this sync server. Does nothing if it is already stopped.
|
| |
| OBX_C_API bool | obx_sync_server_running (OBX_sync_server *server) |
| | Whether the server is up and running.
|
| |
| 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 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 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_stats_u64 (OBX_sync_server *server, OBXSyncServerStats counter_type, uint64_t *out_value) |
| | Get u64 value for sync server statistics.
|
| |
| 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.
|
| |
| 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_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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
| 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.
|
| |
1.9.8