Listeners

Every API function that registers a listener callback returns an opaque token representing the registered callback. More...

Typedefs
typedef struct CBLListenerToken	CBLListenerToken
	An opaque 'cookie' representing a registered listener callback. More...

Functions
void	CBLListener_Remove (CBLListenerToken *_cbl_nullable)
	Removes a listener callback, given the token that was returned when it was added. More...

Scheduling notifications
Applications may want control over when Couchbase Lite notifications (listener callbacks) happen. They may want them called on a specific thread, or at certain times during an event loop. This behavior may vary by database, if for instance each database is associated with a separate thread. The API calls here enable this. When notifications are "buffered" for a database, calls to listeners will be deferred until the application explicitly allows them. Instead, a single callback will be issued when the first notification becomes available; this gives the app a chance to schedule a time when the notifications should be sent and callbacks called.
typedef void(*	CBLNotificationsReadyCallback) (void *_cbl_nullable context, CBLDatabase *db)
	Callback indicating that the database (or an object belonging to it) is ready to call one or more listeners. More...
void	CBLDatabase_BufferNotifications (CBLDatabase *db, CBLNotificationsReadyCallback callback, void *_cbl_nullable context)
	Switches the database to buffered-notification mode. More...
void	CBLDatabase_SendNotifications (CBLDatabase *db)
	Immediately issues all pending notifications for this database, by calling their listener callbacks. More...

Detailed Description

Every API function that registers a listener callback returns an opaque token representing the registered callback.

To unregister any type of listener, call CBLListener_Remove.

The steps to creating a listener are:

1. Define the type of contextual information the callback needs. This is usually one of your objects, or a custom struct.
2. Implement the listener function:
   • The parameters and return value must match the callback defined in the API.
   • The first parameter is always a void* that points to your contextual information, so cast that to the actual pointer type.
   • The function may be called on a background thread! And since the CBL API is not itself thread-safe, you'll need to take special precautions if you want to call the API from your listener, such as protecting all of your calls (inside and outside the listener) with a mutex. It's safer to use CBLDatabase_BufferNotifications to schedule listener callbacks to a time of your own choosing, such as your thread's event loop; see that function's docs for details.
3. To register the listener, call the relevant AddListener function.
   • The parameters will include the CBL object to observe, the address of your listener function, and a pointer to the contextual information. (That pointer needs to remain valid for as long as the listener is registered, so it can't be a pointer to a local variable.)
   • The return value is a CBLListenerToken pointer; save that.
4. To unregister the listener, pass the CBLListenerToken to CBLListener_Remove.
   • You must unregister the listener before the contextual information pointer is invalidated, e.g. before freeing the object it points to.

Typedef Documentation

CBLListenerToken

typedef struct CBLListenerToken CBLListenerToken

An opaque 'cookie' representing a registered listener callback.

It's returned from functions that register listeners, and used to remove a listener by calling CBLListener_Remove.

CBLNotificationsReadyCallback

typedef void(* CBLNotificationsReadyCallback) (void *_cbl_nullable context, CBLDatabase *db)

Callback indicating that the database (or an object belonging to it) is ready to call one or more listeners.

You should call CBLDatabase_SendNotifications at your earliest convenience, in the context (thread, dispatch queue, etc.) you want them to run.

Note

This callback is called only once until the next time CBLDatabase_SendNotifications is called. If you don't respond by (sooner or later) calling that function, you will not be informed that any listeners are ready.

Warning

This can be called from arbitrary threads. It should do as little work as possible, just scheduling a future call to CBLDatabase_SendNotifications.

Function Documentation

CBLDatabase_BufferNotifications()

void CBLDatabase_BufferNotifications	(	CBLDatabase *	db,
		CBLNotificationsReadyCallback	callback,
		void *_cbl_nullable	context
	)

Switches the database to buffered-notification mode.

Notifications for objects belonging to this database (documents, queries, replicators, and of course the database) will not be called immediately; your CBLNotificationsReadyCallback will be called instead.

Parameters

db	The database whose notifications are to be buffered.
callback	The function to be called when a notification is available.
context	An arbitrary value that will be passed to the callback.

CBLDatabase_SendNotifications()

void CBLDatabase_SendNotifications

(

CBLDatabase *

db

)

Immediately issues all pending notifications for this database, by calling their listener callbacks.

CBLListener_Remove()

void CBLListener_Remove

(

CBLListenerToken *

_cbl_nullable

)

Removes a listener callback, given the token that was returned when it was added.