Sync client is used to provide ObjectBox Sync client capabilities to your application. More...

#include <objectbox-sync.hpp>

Inheritance diagram for obx::SyncClient:

Public Member Functions
	SyncClient (Store &store, const std::vector< std::string > &serverUrls, const SyncCredentials &creds)
	Creates a sync client associated with the given store and options. This does not initiate any connection attempts yet: call start() to do so. More...

	SyncClient (Store &store, const std::string &serverUrl, const SyncCredentials &creds)

	SyncClient (Store &store, OBX_sync *cSync)
	Creates a sync client associated with the given store and options. This does not initiate any connection attempts yet: call start() to do so. More...

	SyncClient (SyncClient &&source)=delete
	Can't be moved due to the atomic cSync_ - use shared_ptr instead of SyncClient instances directly. More...

	SyncClient (const SyncClient &)=delete
	Can't be copied, single owner of C resources is required (to avoid double-free during destruction) More...

	~SyncClient () override

void	close () override
	Closes and cleans up all resources used by this sync client. It can no longer be used afterwards, make a new sync client instead. Does nothing if this sync client has already been closed. More...

bool	isClosed () override
	Returns if this sync client is closed and can no longer be used. More...

OBXSyncState	state () const
	Gets the current sync client state. More...

uint32_t	serverProtocolVersion () const
	Returns the protocol version of the server after a connection was established (or attempted), zero otherwise. More...

void	setCredentials (const SyncCredentials &creds)
	Configure authentication credentials. The accepted OBXSyncCredentials type depends on your sync-server configuration. More...

bool	triggerReconnect ()
	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...

void	setHeartbeatInterval (std::chrono::milliseconds interval)
	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 (when there are many connected clients). More...

void	sendHeartbeat ()
	Triggers the heartbeat sending immediately. More...

void	send (SyncObjectsMessageBuilder &&message)
	Sends the given 'objects message' from the client to the currently connected server. More...

void	setRequestUpdatesMode (OBXRequestUpdatesMode mode)
	Configures how sync updates are received from the server. If automatic sync updates are turned off, they will need to be requested manually. More...

void	maxMessagesInFlight (int value)
	Configures the maximum number of outgoing TX messages that can be sent without an ACK from the server. More...

void	start ()
	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. If you haven't set the credentials in the options during construction, call setCredentials() before start(). More...

void	stop ()
	Stops this sync client. Does nothing if it is already stopped. More...

bool	requestUpdates (bool subscribeForFuturePushes)
	Request updates since we last synchronized our database. More...

bool	cancelUpdates ()
	Cancel updates from the server so that it will stop sending updates. More...

uint64_t	outgoingMessageCount (uint64_t limit=0)
	Count the number of messages in the outgoing queue, i.e. those waiting to be sent to the server. Note: This calls uses a (read) transaction internally: 1) it's not just a "cheap" return of a single number. While this will still be fast, avoid calling this function excessively. 2) the result follows transaction view semantics, thus it may not always match the actual value. More...

void	setConnectListener (OBX_sync_listener_connect listener, void listenerArg)

void	setDisconnectListener (OBX_sync_listener_disconnect listener, void listenerArg)

void	setLoginListener (OBX_sync_listener_login listener, void listenerArg)

void	setLoginFailureListener (OBX_sync_listener_login_failure listener, void listenerArg)

void	setCompleteListener (OBX_sync_listener_complete listener, void listenerArg)

void	setChangeListener (OBX_sync_listener_change listener, void listenerArg)

void	setLoginListener (std::shared_ptr< SyncClientLoginListener > listener)

void	setCompletionListener (std::shared_ptr< SyncClientCompletionListener > listener)

void	setConnectionListener (std::shared_ptr< SyncClientConnectionListener > listener)

void	setTimeListener (std::shared_ptr< SyncClientTimeListener > listener)

void	setChangeListener (std::shared_ptr< SyncChangeListener > listener)

void	setErrorListener (std::shared_ptr< SyncClientErrorListener > listener)

void	setListener (std::shared_ptr< SyncClientListener > listener)

void	setObjectsMessageListener (std::shared_ptr< SyncObjectsMessageListener > listener)

uint64_t	statsValueU64 (OBXSyncStats counterType)
	Get u64 value for sync statistics. More...

Public Member Functions inherited from obx::Closable
virtual	~Closable ()=default

Static Public Member Functions
static uint32_t	protocolVersion ()
	Gets the protocol version this client uses. More...

Protected Member Functions
OBX_sync *	cPtr () const

void	closeNonVirtual ()
	Close, but non-virtual to allow calls from constructor/destructor. More...

void	removeLoginListener (bool evenIfEmpty=false)

void	removeCompletionListener (bool evenIfEmpty=false)

void	removeErrorListener (bool evenIfEmpty=false)

void	removeConnectionListener (bool evenIfEmpty=false)

void	removeTimeListener (bool evenIfEmpty=false)

void	removeChangeListener (bool evenIfEmpty=false)

Detailed Description

Sync client is used to provide ObjectBox Sync client capabilities to your application.

Constructor & Destructor Documentation

◆ SyncClient() [1/5]

obx::SyncClient::SyncClient	(	Store &	store,
		const std::vector< std::string > &	serverUrls,
		const SyncCredentials &	creds
	)

inlineexplicit

Creates a sync client associated with the given store and options. This does not initiate any connection attempts yet: call start() to do so.

◆ SyncClient() [2/5]

obx::SyncClient::SyncClient	(	Store &	store,
		const std::string &	serverUrl,
		const SyncCredentials &	creds
	)

inlineexplicit

◆ SyncClient() [3/5]

obx::SyncClient::SyncClient	(	Store &	store,
		OBX_sync *	cSync
	)

inlineexplicit

Creates a sync client associated with the given store and options. This does not initiate any connection attempts yet: call start() to do so.

Parameters

cSync an initialized sync client. You must NOT call obx_sync_close() yourself anymore.

◆ SyncClient() [4/5]

obx::SyncClient::SyncClient ( SyncClient && source )

delete

Can't be moved due to the atomic cSync_ - use shared_ptr instead of SyncClient instances directly.

◆ SyncClient() [5/5]

obx::SyncClient::SyncClient ( const SyncClient & )

delete

Can't be copied, single owner of C resources is required (to avoid double-free during destruction)

◆ ~SyncClient()

obx::SyncClient::~SyncClient ( )

inlineoverride

Member Function Documentation

◆ cancelUpdates()

bool obx::SyncClient::cancelUpdates ( )

inline

Cancel updates from the server so that it will stop sending updates.

See also: updatesRequest()

◆ close()

void obx::SyncClient::close ( )

inlineoverridevirtual

Closes and cleans up all resources used by this sync client. It can no longer be used afterwards, make a new sync client instead. Does nothing if this sync client has already been closed.

Implements obx::Closable.

◆ closeNonVirtual()

void obx::SyncClient::closeNonVirtual ( )

inlineprotected

Close, but non-virtual to allow calls from constructor/destructor.

◆ cPtr()

OBX_sync* obx::SyncClient::cPtr ( ) const

inlineprotected

◆ isClosed()

bool obx::SyncClient::isClosed ( )

inlineoverridevirtual

Returns if this sync client is closed and can no longer be used.

Implements obx::Closable.

◆ maxMessagesInFlight()

void obx::SyncClient::maxMessagesInFlight ( int value )

inline

Configures the maximum number of outgoing TX messages that can be sent without an ACK from the server.

Exceptions

if	value is not in the valid range 1-20

◆ outgoingMessageCount()

uint64_t obx::SyncClient::outgoingMessageCount ( uint64_t limit = 0 )

inline

Count the number of messages in the outgoing queue, i.e. those waiting to be sent to the server. Note: This calls uses a (read) transaction internally: 1) it's not just a "cheap" return of a single number. While this will still be fast, avoid calling this function excessively. 2) the result follows transaction view semantics, thus it may not always match the actual value.

Returns: the number of messages in the outgoing queue

◆ protocolVersion()

static uint32_t obx::SyncClient::protocolVersion ( )

inlinestatic

Gets the protocol version this client uses.

◆ removeChangeListener()

void obx::SyncClient::removeChangeListener ( bool evenIfEmpty = false )

inlineprotected

◆ removeCompletionListener()

void obx::SyncClient::removeCompletionListener ( bool evenIfEmpty = false )

inlineprotected

◆ removeConnectionListener()

void obx::SyncClient::removeConnectionListener ( bool evenIfEmpty = false )

inlineprotected

◆ removeErrorListener()

void obx::SyncClient::removeErrorListener ( bool evenIfEmpty = false )

inlineprotected

◆ removeLoginListener()

void obx::SyncClient::removeLoginListener ( bool evenIfEmpty = false )

inlineprotected

◆ removeTimeListener()

void obx::SyncClient::removeTimeListener ( bool evenIfEmpty = false )

inlineprotected

◆ requestUpdates()

bool obx::SyncClient::requestUpdates ( bool subscribeForFuturePushes )

inline

Request updates since we last synchronized our database.

Parameters

subscribeForFuturePushes to keep sending us future updates as they come in.

See also: updatesCancel() to stop the updates

◆ send()

void obx::SyncClient::send ( SyncObjectsMessageBuilder && message )

inline

Sends the given 'objects message' from the client to the currently connected server.

◆ sendHeartbeat()

void obx::SyncClient::sendHeartbeat ( )

inline

Triggers the heartbeat sending immediately.

◆ serverProtocolVersion()

uint32_t obx::SyncClient::serverProtocolVersion ( ) const

inline

Returns the protocol version of the server after a connection was established (or attempted), zero otherwise.

◆ setChangeListener() [1/2]

void obx::SyncClient::setChangeListener	(	OBX_sync_listener_change *	listener,
		void *	listenerArg
	)

inline

Parameters

listener	set NULL to reset
listenerArg	is a pass-through argument passed to the listener

◆ setChangeListener() [2/2]

void obx::SyncClient::setChangeListener ( std::shared_ptr< SyncChangeListener > listener )

inline

◆ setCompleteListener()

void obx::SyncClient::setCompleteListener	(	OBX_sync_listener_complete *	listener,
		void *	listenerArg
	)

inline

Parameters

listener	set NULL to reset
listenerArg	is a pass-through argument passed to the listener

◆ setCompletionListener()

void obx::SyncClient::setCompletionListener ( std::shared_ptr< SyncClientCompletionListener > listener )

inline

◆ setConnectionListener()

void obx::SyncClient::setConnectionListener ( std::shared_ptr< SyncClientConnectionListener > listener )

inline

◆ setConnectListener()

void obx::SyncClient::setConnectListener	(	OBX_sync_listener_connect *	listener,
		void *	listenerArg
	)

inline

Parameters

listener	set NULL to reset
listenerArg	is a pass-through argument passed to the listener

◆ setCredentials()

void obx::SyncClient::setCredentials ( const SyncCredentials & creds )

inline

Configure authentication credentials. The accepted OBXSyncCredentials type depends on your sync-server configuration.

◆ setDisconnectListener()

void obx::SyncClient::setDisconnectListener	(	OBX_sync_listener_disconnect *	listener,
		void *	listenerArg
	)

inline

Parameters

listener	set NULL to reset
listenerArg	is a pass-through argument passed to the listener

◆ setErrorListener()

void obx::SyncClient::setErrorListener ( std::shared_ptr< SyncClientErrorListener > listener )

inline

◆ setHeartbeatInterval()

void obx::SyncClient::setHeartbeatInterval ( std::chrono::milliseconds interval )

inline

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 (when there are many connected clients).

Parameters

interval default value is 25 minutes (1 500 000 milliseconds), which is also the allowed maximum.

Exceptions

if	value is not in the allowed range, e.g. larger than the maximum (1 500 000).

◆ setListener()

void obx::SyncClient::setListener ( std::shared_ptr< SyncClientListener > listener )

inline

◆ setLoginFailureListener()

void obx::SyncClient::setLoginFailureListener	(	OBX_sync_listener_login_failure *	listener,
		void *	listenerArg
	)

inline

Parameters

listener	set NULL to reset
listenerArg	is a pass-through argument passed to the listener

◆ setLoginListener() [1/2]

void obx::SyncClient::setLoginListener	(	OBX_sync_listener_login *	listener,
		void *	listenerArg
	)

inline

Parameters

listener	set NULL to reset
listenerArg	is a pass-through argument passed to the listener

◆ setLoginListener() [2/2]

void obx::SyncClient::setLoginListener ( std::shared_ptr< SyncClientLoginListener > listener )

inline

◆ setObjectsMessageListener()

void obx::SyncClient::setObjectsMessageListener ( std::shared_ptr< SyncObjectsMessageListener > listener )

inline

◆ setRequestUpdatesMode()

void obx::SyncClient::setRequestUpdatesMode ( OBXRequestUpdatesMode mode )

inline

Configures how sync updates are received from the server. If automatic sync updates are turned off, they will need to be requested manually.

◆ setTimeListener()

void obx::SyncClient::setTimeListener ( std::shared_ptr< SyncClientTimeListener > listener )

inline

◆ start()

void obx::SyncClient::start ( )

inline

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. If you haven't set the credentials in the options during construction, call setCredentials() before start().

◆ state()

OBXSyncState obx::SyncClient::state ( ) const

inline

Gets the current sync client state.

◆ statsValueU64()

uint64_t obx::SyncClient::statsValueU64 ( OBXSyncStats counterType )

inline

Get u64 value for sync statistics.

◆ stop()

void obx::SyncClient::stop ( )

inline

Stops this sync client. Does nothing if it is already stopped.

◆ triggerReconnect()

bool obx::SyncClient::triggerReconnect ( )

inline

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.

Member Data Documentation

◆ change

std::shared_ptr<SyncChangeListener> obx::SyncClient::change

◆ combined

std::shared_ptr<SyncClientListener> obx::SyncClient::combined

◆ complete

std::shared_ptr<SyncClientCompletionListener> obx::SyncClient::complete

◆ connect

std::shared_ptr<SyncClientConnectionListener> obx::SyncClient::connect

◆ error

std::shared_ptr<SyncClientErrorListener> obx::SyncClient::error

◆ login

std::shared_ptr<SyncClientLoginListener> obx::SyncClient::login

◆ mutex

std::mutex obx::SyncClient::mutex

◆ object

std::shared_ptr<SyncObjectsMessageListener> obx::SyncClient::object

◆ time

std::shared_ptr<SyncClientTimeListener> obx::SyncClient::time

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SyncClient() [1/5]

◆ SyncClient() [2/5]

◆ SyncClient() [3/5]

◆ SyncClient() [4/5]

◆ SyncClient() [5/5]

◆ ~SyncClient()

Member Function Documentation

◆ cancelUpdates()

◆ close()

◆ closeNonVirtual()

◆ cPtr()

◆ isClosed()

◆ maxMessagesInFlight()

◆ outgoingMessageCount()

◆ protocolVersion()

◆ removeChangeListener()

◆ removeCompletionListener()

◆ removeConnectionListener()

◆ removeErrorListener()

◆ removeLoginListener()

◆ removeTimeListener()

◆ requestUpdates()

◆ send()

◆ sendHeartbeat()

◆ serverProtocolVersion()

◆ setChangeListener() [1/2]

◆ setChangeListener() [2/2]

◆ setCompleteListener()

◆ setCompletionListener()

◆ setConnectionListener()

◆ setConnectListener()

◆ setCredentials()

◆ setDisconnectListener()

◆ setErrorListener()

◆ setHeartbeatInterval()

◆ setListener()

◆ setLoginFailureListener()

◆ setLoginListener() [1/2]

◆ setLoginListener() [2/2]

◆ setObjectsMessageListener()

◆ setRequestUpdatesMode()

◆ setTimeListener()

◆ start()

◆ state()

◆ statsValueU64()

◆ stop()

◆ triggerReconnect()

Member Data Documentation

◆ change

◆ combined

◆ complete

◆ connect

◆ error

◆ login

◆ mutex

◆ object

◆ time