Network Listener: REST API and Sync Server

Data Structures
struct	C4TLSConfig
	TLS configuration for C4Listener. More...
struct	C4ListenerConfig
	Configuration for a C4Listener. More...
struct	C4ListenerDatabaseConfig
	Per-database configuration for a C4Listener. More...

Typedefs
typedef bool(*	C4ListenerCertAuthCallback) (C4Listener *listener, C4Slice clientCertData, void *context)
	Called when a client connects, during the TLS handshake, if a client certificate is received.
typedef bool(*	C4ListenerHTTPAuthCallback) (C4Listener *listener, C4Slice authHeader, void *context)
	Called when a client connects, after the TLS handshake (if any), when the initial HTTP request is received.

Enumerations
enum	C4PrivateKeyRepresentation : unsigned { kC4PrivateKeyFromCert , kC4PrivateKeyFromKey }

Functions
NODISCARD CBL_CORE_API C4Listener *	c4listener_start (const C4ListenerConfig *config, C4Error *error)
	Creates and starts a new listener.
NODISCARD CBL_CORE_API bool	c4listener_shareDB (C4Listener *listener, C4String name, C4Database *db, C4Error *outError)
	Makes a database available from the network, and its default collection.
NODISCARD CBL_CORE_API bool	c4listener_shareDBWithConfig (C4Listener *listener, C4String name, C4Database *db, const C4ListenerDatabaseConfig *config, C4Error *outError)
	Makes a database available from the network, and its default collection.
NODISCARD CBL_CORE_API bool	c4listener_unshareDB (C4Listener *listener, C4Database *db, C4Error *outError)
	Makes a previously-shared database unavailable.
NODISCARD CBL_CORE_API bool	c4listener_shareCollection (C4Listener *listener, C4String name, C4Collection *collection, C4Error *outError)
	Specifies a collection to be used in a P2P listener context.
NODISCARD CBL_CORE_API bool	c4listener_unshareCollection (C4Listener *listener, C4String name, C4Collection *collection, C4Error *outError)
	Makes a previously-shared collection unavailable.
NODISCARD CBL_CORE_API FLMutableArray	c4listener_getURLs (const C4Listener *listener, C4Database *db, C4Error *err)
	Returns the URL(s) of a database being shared, or of the root.
CBL_CORE_API uint16_t	c4listener_getPort (const C4Listener *listener)
	Returns the port number the listener is accepting connections on.
CBL_CORE_API void	c4listener_getConnectionStatus (const C4Listener *listener, unsigned *connectionCount, unsigned *activeConnectionCount)
	Returns the number of client connections, and how many of those are currently active.
CBL_CORE_API C4StringResult	c4db_URINameFromPath (C4String path)
	A convenience that, given a filesystem path to a database, returns the database name for use in an HTTP URI path.

Detailed Description

Typedef Documentation

C4ListenerCertAuthCallback

typedef bool(* C4ListenerCertAuthCallback) (C4Listener *listener, C4Slice clientCertData, void *context)

Called when a client connects, during the TLS handshake, if a client certificate is received.

Parameters

listener	The C4Listener handling the connection.
clientCertData	The client's X.509 certificate in DER encoding.
context	The tlsCallbackContext from the C4TLSConfig.

Returns

True to allow the connection, false to refuse it.

C4ListenerHTTPAuthCallback

typedef bool(* C4ListenerHTTPAuthCallback) (C4Listener *listener, C4Slice authHeader, void *context)

Called when a client connects, after the TLS handshake (if any), when the initial HTTP request is received.

Parameters

listener	The C4Listener handling the connection.
authHeader	The "Authorization" header value from the client's HTTP request, or null.
context	The callbackContext from the listener config.

Returns

True to allow the connection, false to refuse it.

Enumeration Type Documentation

C4PrivateKeyRepresentation

enum C4PrivateKeyRepresentation : unsigned

Enumerator
kC4PrivateKeyFromCert	Key in secure storage, associated with certificate.
kC4PrivateKeyFromKey	Key from the provided key pair.

Function Documentation

c4db_URINameFromPath()

CBL_CORE_API C4StringResult c4db_URINameFromPath

(

C4String

path

)

A convenience that, given a filesystem path to a database, returns the database name for use in an HTTP URI path.

• The directory portion of the path and the ".cblite2" extension are removed.
• Any leading "_" is replaced with a "-".
• Any control characters or slashes are replaced with "-".

  Parameters

  path	The filesystem path of a database.

  Returns

  A name that can be used as a URI path component, or NULL if the path is not a valid database path (does not end with ".cblite2".)

c4listener_getConnectionStatus()

CBL_CORE_API void c4listener_getConnectionStatus	(	const C4Listener *	listener,
		unsigned *	connectionCount,
		unsigned *	activeConnectionCount )

Returns the number of client connections, and how many of those are currently active.

Either parameter can be NULL if you don't care about it.

Note

This function is thread-safe.

c4listener_getPort()

CBL_CORE_API uint16_t c4listener_getPort

(

const C4Listener *

listener

)

Returns the port number the listener is accepting connections on.

This is useful if you didn't specify a port in the config (port=0), so you can find out which port the kernel picked.

Note

This function is thread-safe.

c4listener_getURLs()

NODISCARD CBL_CORE_API FLMutableArray c4listener_getURLs	(	const C4Listener *	listener,
		C4Database *	db,
		C4Error *	err )

Returns the URL(s) of a database being shared, or of the root.

The URLs will differ only in their hostname – there will be one for each IP address or known hostname of the computer, or of the network interface.

WARNING: Link-local IPv6 addresses are included in this list. However, due to IPv6 specification rules, a scope ID is also required to connect to these addresses. So if the address starts with fe80:: you will need to take care on the other side to also incorporate the scope of of the client network interface into the URL when connecting (in short, it's probably best to avoid these but they are there if you would like to try)

Note

The caller must use a lock for the C4Database when this function is called.

The caller is responsible for releasing the returned Fleece array.

Parameters

listener	The active listener.
db	A database being shared, or NULL to get the listener's root URL(s).
err	The error information, if any

Returns

Fleece array of or more URL strings, or null if an error occurred. Caller is responsible for releasing the result.

c4listener_shareCollection()

NODISCARD CBL_CORE_API bool c4listener_shareCollection	(	C4Listener *	listener,
		C4String	name,
		C4Collection *	collection,
		C4Error *	outError )

Specifies a collection to be used in a P2P listener context.

NOTE: A database must have been previously shared under the same name, or this operation will fail.

Note

The caller must use a lock for the C4Collection when this function is called.

Parameters

listener	The listener that should share the collection.
name	The URI name to share it under, this must match the name of an already shared DB.
collection	The collection to share.
outError	On failure, the error info is stored here if non-NULL.

c4listener_shareDB()

NODISCARD CBL_CORE_API bool c4listener_shareDB	(	C4Listener *	listener,
		C4String	name,
		C4Database *	db,
		C4Error *	outError )

Makes a database available from the network, and its default collection.

This function is equivalent to c4listener_shareDBWithConfig, with config being NULL.

c4listener_shareDBWithConfig()

NODISCARD CBL_CORE_API bool c4listener_shareDBWithConfig	(	C4Listener *	listener,
		C4String	name,
		C4Database *	db,
		const C4ListenerDatabaseConfig *	config,
		C4Error *	outError )

Makes a database available from the network, and its default collection.

Note

The caller must use a lock for the C4Database when this function is called.

Parameters

listener	The listener that should share the database.
name	The URI name to share it under, i.e. the path component in the URL. If this is left null, a name will be chosen by calling c4db_URINameFromPath. The name may not include '/', '.', control characters, or non-ASCII characters.
db	The database to share.
config	Per-database configuration overriding the C4ListenerConfig, or NULL.
outError	On failure, the error info is stored here if non-NULL.

Returns

True on success, false if the name is already in use or invalid as a URI component.

c4listener_start()

NODISCARD CBL_CORE_API C4Listener * c4listener_start	(	const C4ListenerConfig *	config,
		C4Error *	error )

Creates and starts a new listener.

Caller must release it when done.

c4listener_unshareCollection()

NODISCARD CBL_CORE_API bool c4listener_unshareCollection	(	C4Listener *	listener,
		C4String	name,
		C4Collection *	collection,
		C4Error *	outError )

Makes a previously-shared collection unavailable.

Note

The caller must use a lock for the C4Collection when this function is called.

c4listener_unshareDB()

NODISCARD CBL_CORE_API bool c4listener_unshareDB	(	C4Listener *	listener,
		C4Database *	db,
		C4Error *	outError )

Makes a previously-shared database unavailable.

Note

db need not be the same instance that was registered, merely on the same file.

The caller must use a lock for the C4Database when this function is called.