Network Listener: REST API and Sync Server

Data Structures
struct	C4TLSConfig
	TLS configuration for C4Listener. More...
struct	C4ListenerConfig
	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	C4ListenerAPIs : unsigned { kC4RESTAPI = 0x01 , kC4SyncAPI = 0x02 }
enum	C4PrivateKeyRepresentation : unsigned { kC4PrivateKeyFromCert , kC4PrivateKeyFromKey }

Functions
CBL_CORE_API C4ListenerAPIs	c4listener_availableAPIs (void)
	Returns flags for the available APIs in this build (REST, sync, or both.)
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.
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, C4ListenerAPIs api, C4Error *err)
	Returns the URL(s) of a database being shared, or of the root, separated by "\n" bytes.
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

C4ListenerAPIs

enum C4ListenerAPIs : unsigned

Enumerator
kC4RESTAPI	CouchDB-like REST API.
kC4SyncAPI	Replication server.

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_availableAPIs()

CBL_CORE_API C4ListenerAPIs c4listener_availableAPIs

(

void

)

Returns flags for the available APIs in this build (REST, sync, or both.)

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.

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.

c4listener_getURLs()

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

Returns the URL(s) of a database being shared, or of the root, separated by "\n" bytes.

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)

Parameters

listener	The active listener.
db	A database being shared, or NULL to get the listener's root URL(s).
api	The API variant for which the URLs should be retrieved. If the listener is not running in the given mode, or more than one mode is given, an error is returned
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.

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.

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 based as though you had called c4db_URINameFromPath.
db	The database to share.
outError	On failure, the error info is stored here if non-NULL.

Returns

True on success, false if the name is 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.

c4listener_unshareDB()

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

Makes a previously-shared database unavailable.