11/*
2- * Copyright 2018-2024 ObjectBox Ltd. All rights reserved.
2+ * Copyright 2018-2025 ObjectBox Ltd. All rights reserved.
33 *
44 * Licensed under the Apache License, Version 2.0 (the "License");
55 * you may not use this file except in compliance with the License.
3434#include "objectbox.h"
3535
3636#if defined(static_assert ) || defined(__cplusplus )
37- static_assert (OBX_VERSION_MAJOR == 4 && OBX_VERSION_MINOR == 0 && OBX_VERSION_PATCH == 2 , // NOLINT
37+ static_assert (OBX_VERSION_MAJOR == 4 && OBX_VERSION_MINOR == 1 && OBX_VERSION_PATCH == 0 , // NOLINT
3838 "Versions of objectbox.h and objectbox-sync.h files do not match, please update" );
3939#endif
4040
@@ -56,11 +56,19 @@ typedef struct OBX_sync OBX_sync;
5656/// specifies a generic client-side credential type.
5757typedef enum {
5858 OBXSyncCredentialsType_NONE = 1 ,
59- OBXSyncCredentialsType_SHARED_SECRET = 2 ,
59+ OBXSyncCredentialsType_SHARED_SECRET = 2 , ///< Deprecated, replaced by SHARED_SECRET_SIPPED
6060 OBXSyncCredentialsType_GOOGLE_AUTH = 3 ,
61- OBXSyncCredentialsType_SHARED_SECRET_SIPPED = 4 ,
62- OBXSyncCredentialsType_OBX_ADMIN_USER = 5 ,
63- OBXSyncCredentialsType_USER_PASSWORD = 6 ,
61+ OBXSyncCredentialsType_SHARED_SECRET_SIPPED = 4 , ///< Uses shared secret to create a hashed credential.
62+ OBXSyncCredentialsType_OBX_ADMIN_USER = 5 , ///< ObjectBox admin users (username/password)
63+ OBXSyncCredentialsType_USER_PASSWORD = 6 , ///< Generic credential type suitable for ObjectBox admin
64+ ///< (and possibly others in the future)
65+ OBXSyncCredentialsType_JWT_ID = 7 , ///< JSON Web Token (JWT): an ID token that typically provides identity
66+ ///< information about the authenticated user.
67+ OBXSyncCredentialsType_JWT_ACCESS = 8 , ///< JSON Web Token (JWT): an access token that is used to access resources.
68+ OBXSyncCredentialsType_JWT_REFRESH = 9 , ///< JSON Web Token (JWT): a refresh token that is used to obtain a new
69+ ///< access token.
70+ OBXSyncCredentialsType_JWT_CUSTOM = 10 , ///< JSON Web Token (JWT): a token that is neither an ID, access,
71+ ///< nor refresh token.
6472} OBXSyncCredentialsType ;
6573
6674// TODO sync prefix
@@ -194,8 +202,11 @@ OBX_C_API OBX_sync* obx_sync_urls(OBX_store* store, const char* server_urls[], s
194202OBX_C_API obx_err obx_sync_close (OBX_sync * sync );
195203
196204/// Sets credentials to authenticate the client with the server.
197- /// See OBXSyncCredentialsType for available options.
198- /// The accepted OBXSyncCredentials type depends on your sync-server configuration.
205+ /// Any credentials that were set before are replaced;
206+ /// if you want to pass multiple credentials, use obx_sync_credentials_add() instead.
207+ /// If the client was waiting for credentials, this can trigger a reconnection/login attempt.
208+ /// @param type See OBXSyncCredentialsType for available options.
209+ /// The accepted OBXSyncCredentials type depends on your sync-server configuration.
199210/// @param data may be NULL in combination with OBXSyncCredentialsType_NONE
200211OBX_C_API obx_err obx_sync_credentials (OBX_sync * sync , OBXSyncCredentialsType type , const uint8_t * data , size_t size );
201212
@@ -207,6 +218,29 @@ OBX_C_API obx_err obx_sync_credentials(OBX_sync* sync, OBXSyncCredentialsType ty
207218OBX_C_API obx_err obx_sync_credentials_user_password (OBX_sync * sync , OBXSyncCredentialsType type , const char * username ,
208219 const char * password );
209220
221+ /// For authentication with multiple credentials, collect credentials by calling this function multiple times.
222+ /// When adding the last credentials element, the "complete" flag must be set to true.
223+ /// When completed, it will "activate" the collected credentials and replace any previously set credentials and
224+ /// potentially trigger a reconnection/login attempt.
225+ /// @param type See OBXSyncCredentialsType for available options.
226+ /// The accepted OBXSyncCredentials type depends on your sync-server configuration.
227+ /// @param data non-NULL (OBXSyncCredentialsType_NONE is not allowed)
228+ /// @param complete set to true when adding the last credentials element to activate the set of credentials
229+ OBX_C_API obx_err obx_sync_credentials_add (OBX_sync * sync , OBXSyncCredentialsType type , const uint8_t * data , size_t size ,
230+ bool complete );
231+
232+ /// For authentication with multiple credentials, collect credentials by calling this function multiple times.
233+ /// When adding the last credentials element, the "complete" flag must be set to true.
234+ /// When completed, it will "activate" the collected credentials and replace any previously set credentials and
235+ /// potentially trigger a reconnection/login attempt.
236+ /// @param type See OBXSyncCredentialsType for available options.
237+ /// The accepted OBXSyncCredentials type depends on your sync-server configuration.
238+ /// @param username non-NULL
239+ /// @param password non-NULL
240+ /// @param complete set to true when adding the last credentials element to activate the set of credentials
241+ OBX_C_API obx_err obx_sync_credentials_add_user_password (OBX_sync * sync , OBXSyncCredentialsType type ,
242+ const char * username , const char * password , bool complete );
243+
210244/// Configures the maximum number of outgoing TX messages that can be sent without an ACK from the server.
211245/// @returns OBX_ERROR_ILLEGAL_ARGUMENT if value is not in the range 1-20
212246OBX_C_API obx_err obx_sync_max_messages_in_flight (OBX_sync * sync , int value );
@@ -374,9 +408,9 @@ OBX_C_API void obx_sync_listener_msg_objects(OBX_sync* sync, OBX_sync_listener_m
374408 void * listener_arg );
375409
376410/// Set or overwrite a previously set 'error' listener - provides information about occurred sync-level errors.
377- /// @param listener set NULL to reset
411+ /// @param listener The callback to receive sync errors. Set to NULL to reset.
378412/// @param listener_arg is a pass-through argument passed to the listener
379- OBX_C_API void obx_sync_listener_error (OBX_sync * sync , OBX_sync_listener_error * error , void * listener_arg );
413+ OBX_C_API void obx_sync_listener_error (OBX_sync * sync , OBX_sync_listener_error * listener , void * listener_arg );
380414
381415//----------------------------------------------
382416// Sync Stats
@@ -702,7 +736,7 @@ typedef enum {
702736
703737/// Get u64 value for sync server statistics.
704738/// @param counter_type the counter value to be read (make sure to choose a uint64_t (u64) metric value type).
705- /// @param out_count receives the counter value.
739+ /// @param out_value receives the counter value.
706740/// @return OBX_SUCCESS if the counter has been successfully retrieved.
707741/// @return OBX_ERROR_ILLEGAL_ARGUMENT if counter_type is undefined (this also happens if the wrong type is requested)
708742/// @return OBX_ERROR_ILLEGAL_STATE if the server is not started.
@@ -711,7 +745,7 @@ OBX_C_API obx_err obx_sync_server_stats_u64(OBX_sync_server* server, OBXSyncServ
711745
712746/// Get double value for sync server statistics.
713747/// @param counter_type the counter value to be read (make sure to use a double (f64) metric value type).
714- /// @param out_count receives the counter value.
748+ /// @param out_value receives the counter value.
715749/// @return OBX_SUCCESS if the counter has been successfully retrieved.
716750/// @return OBX_ERROR_ILLEGAL_ARGUMENT if counter_type is undefined (this also happens if the wrong type is requested)
717751/// @return OBX_ERROR_ILLEGAL_STATE if the server is not started.
@@ -785,7 +819,7 @@ typedef void OBX_custom_msg_server_func_client_connection_close(void* server_use
785819/// Callback to shutdown and free all resources associated with the sync client connection to the custom server.
786820/// Note that the custom server may already have been shutdown at this point (e.g. no server user data is supplied).
787821/// Must be provided to implement a custom server. See notes on OBX_custom_msg_server_functions for more details.
788- /// @param server_user_data User supplied data returned by the function that created the server
822+ /// @param connection_user_data User supplied data returned by the function that created the server
789823typedef void OBX_custom_msg_server_func_client_connection_shutdown (void * connection_user_data );
790824
791825/// Struct of the custom server function callbacks. In order to implement the custom server, you must provide
0 commit comments