Replication Socket Provider API

Data Structures
struct	C4SocketFactory
	A group of callbacks that define the implementation of sockets; the client must fill this out and pass it to c4socket_registerFactory() before using any socket-based API. More...

Enumerations
enum	C4WebSocketCloseCode : int32_t {   kWebSocketCloseNormal = 1000 , kWebSocketCloseGoingAway = 1001 , kWebSocketCloseProtocolError = 1002 , kWebSocketCloseDataError = 1003 ,   kWebSocketCloseNoCode = 1005 , kWebSocketCloseAbnormal = 1006 , kWebSocketCloseBadMessageFormat = 1007 , kWebSocketClosePolicyError = 1008 ,   kWebSocketCloseMessageTooBig = 1009 , kWebSocketCloseMissingExtension = 1010 , kWebSocketCloseCantFulfill = 1011 , kWebSocketCloseTLSFailure = 1015 ,   kWebSocketCloseAppTransient = 4001 , kWebSocketCloseAppPermanent = 4002 , kWebSocketCloseFirstAvailable = 5000 }
enum	C4SocketFraming : uint8_t { kC4WebSocketClientFraming , kC4NoFraming , kC4WebSocketServerFraming }

Functions
CBL_CORE_API void	c4socket_registerFactory (C4SocketFactory factory)
	One-time registration of default socket callbacks.
CBL_CORE_API void	c4Socket_setNativeHandle (C4Socket *, void *)
	Associates an opaque "native handle" with this object.
CBL_CORE_API void *	c4Socket_getNativeHandle (C4Socket *)
	Returns the opaque "native handle" associated with this object.
CBL_CORE_API bool	c4socket_gotPeerCertificate (C4Socket *socket, C4Slice certData, C4String hostname)
	Notifies LiteCore that a socket is making a TLS connection and has received the peer's (usually server's) certificate, so that it knows the cert and can call any custom auth callbacks.
CBL_CORE_API void	c4socket_gotHTTPResponse (C4Socket *socket, int httpStatus, C4Slice responseHeadersFleece)
	Notification that a client socket has received an HTTP response, with the headers encoded as a Fleece dictionary.
CBL_CORE_API void	c4socket_opened (C4Socket *socket)
	Notifies LiteCore that a socket has opened, i.e.
CBL_CORE_API void	c4socket_closed (C4Socket *socket, C4Error errorIfAny)
	Notifies LiteCore that a socket has finished closing, or disconnected, or failed to open.
CBL_CORE_API void	c4socket_closeRequested (C4Socket *socket, int status, C4String message)
	Notifies LiteCore that the peer has requested to close the socket using the WebSocket protocol.
CBL_CORE_API void	c4socket_completedWrite (C4Socket *socket, size_t byteCount)
	Notifies LiteCore that a C4SocketFactory.write request has been completed, i.e.
CBL_CORE_API void	c4socket_received (C4Socket *socket, C4Slice data)
	Notifies LiteCore that data was received from the socket.
NODISCARD CBL_CORE_API C4Socket *	c4socket_fromNative (C4SocketFactory factory, void *nativeHandle, const C4Address *address)
NODISCARD CBL_CORE_API C4Socket *	c4socket_fromNative2 (C4SocketFactory factory, void *nativeHandle, const C4Address *address, bool incoming)
	Constructs a C4Socket from a "native handle", whose interpretation is up to the C4SocketFactory.

Detailed Description

Enumeration Type Documentation

C4SocketFraming

enum C4SocketFraming : uint8_t

Enumerator
kC4WebSocketClientFraming	Frame as WebSocket client messages (masked)
kC4NoFraming	No framing; use messages as-is.
kC4WebSocketServerFraming	Frame as WebSocket server messages (not masked)

C4WebSocketCloseCode

enum C4WebSocketCloseCode : int32_t

Enumerator
kWebSocketCloseNormal
kWebSocketCloseGoingAway
kWebSocketCloseProtocolError
kWebSocketCloseDataError
kWebSocketCloseNoCode
kWebSocketCloseAbnormal
kWebSocketCloseBadMessageFormat
kWebSocketClosePolicyError
kWebSocketCloseMessageTooBig
kWebSocketCloseMissingExtension
kWebSocketCloseCantFulfill
kWebSocketCloseTLSFailure
kWebSocketCloseAppTransient
kWebSocketCloseAppPermanent
kWebSocketCloseFirstAvailable

Function Documentation

c4socket_closed()

CBL_CORE_API void c4socket_closed	(	C4Socket *	socket,
		C4Error	errorIfAny )

Notifies LiteCore that a socket has finished closing, or disconnected, or failed to open.

• If this is a normal close in response to a C4SocketFactory.close request, the error parameter should have a code of 0.
• If it's a socket-level error, set the C4Error appropriately.
• If it's a WebSocket-level close (when the factory's framing equals to kC4NoFraming), set the error domain to WebSocketDomain and the code to the WebSocket status code.

  Note

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

  Parameters

  socket	The socket.
  errorIfAny	the status of the close; see description above.

c4socket_closeRequested()

CBL_CORE_API void c4socket_closeRequested	(	C4Socket *	socket,
		int	status,
		C4String	message )

Notifies LiteCore that the peer has requested to close the socket using the WebSocket protocol.

(Should only be called by sockets whose factory's framing equals to kC4NoFraming.) LiteCore will call the factory's requestClose callback in response when it's ready to acknowledge the close.

Note

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

Parameters

socket	The socket.
status	The WebSocket status sent by the peer, typically 1000.
message	An optional human-readable message sent by the peer.

c4socket_completedWrite()

CBL_CORE_API void c4socket_completedWrite	(	C4Socket *	socket,
		size_t	byteCount )

Notifies LiteCore that a C4SocketFactory.write request has been completed, i.e.

the bytes have been written to the socket.

Note

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

Parameters

socket	The socket.
byteCount	The number of bytes that were written.

c4socket_fromNative()

NODISCARD CBL_CORE_API C4Socket * c4socket_fromNative	(	C4SocketFactory	factory,
		void *	nativeHandle,
		const C4Address *	address )

c4socket_fromNative2()

NODISCARD CBL_CORE_API C4Socket * c4socket_fromNative2	(	C4SocketFactory	factory,
		void *	nativeHandle,
		const C4Address *	address,
		bool	incoming )

Constructs a C4Socket from a "native handle", whose interpretation is up to the C4SocketFactory.

Note

This function is thread-safe.

Unlike c4socket_fromNative, this returns a retained C4Socket you are responsible for releasing.

Parameters

factory	The C4SocketFactory that will manage the socket.
nativeHandle	A value known to the factory that represents the underlying socket, such as a file descriptor or a native object pointer.
address	The address of the remote peer.
incoming	True if this is an incoming (server) connection, false if outgoing (client).

Returns

A new C4Socket initialized with the nativeHandle.

c4Socket_getNativeHandle()

CBL_CORE_API void * c4Socket_getNativeHandle

(

C4Socket *

)

Returns the opaque "native handle" associated with this object.

Note

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

c4socket_gotHTTPResponse()

CBL_CORE_API void c4socket_gotHTTPResponse	(	C4Socket *	socket,
		int	httpStatus,
		C4Slice	responseHeadersFleece )

Notification that a client socket has received an HTTP response, with the headers encoded as a Fleece dictionary.

This call is required for a client socket (where the socket factory's open function was called.) It should not be called on a server/incoming socket (where c4socket_fromNative was called.)

This should be called just before c4socket_opened or c4socket_closed.

Note

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

Parameters

socket	The socket being opened.
httpStatus	The HTTP/WebSocket status code from the peer; expected to be 200 if the connection is successful, else an HTTP status >= 300 or WebSocket status >= 1000.
responseHeadersFleece	The HTTP response headers, encoded as a Fleece dictionary whose keys are the header names (with normalized case) and values are header values as strings.

c4socket_gotPeerCertificate()

CBL_CORE_API bool c4socket_gotPeerCertificate	(	C4Socket *	socket,
		C4Slice	certData,
		C4String	hostname )

Notifies LiteCore that a socket is making a TLS connection and has received the peer's (usually server's) certificate, so that it knows the cert and can call any custom auth callbacks.

This function MUST be called if there is a valid peer cert.

You should first perform other TLS validation, both platform-specific and as specified by the options kC4ReplicatorOptionRootCerts, kC4ReplicatorOptionPinnedServerCert, kC4ReplicatorOptionOnlySelfSignedServerCert. If any of those fail, close the socket. (But if kC4ReplicatorOptionAcceptAllCerts is set, none of the above checks are done.)

After other validation succeeds, call this function – before c4socket_gotHTTPResponse() or c4socket_opened(). If it returns true, proceed. If it returns false, the certificate is rejected and you should close the socket immediately with error kC4NetErrTLSCertUntrusted.

Note

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

Parameters

socket	The socket being opened.
certData	The DER-encoded data of the peer's TLS certificate.
hostname	The DNS hostname of the peer. (This may be different from the original Address given, if there were HTTP redirects.)

Returns

True to proceed, false to abort the connection.

c4socket_opened()

CBL_CORE_API void c4socket_opened

(

C4Socket *

socket

)

Notifies LiteCore that a socket has opened, i.e.

a C4SocketFactory.open request has completed successfully.

Note

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

Parameters

socket

The socket.

c4socket_received()

CBL_CORE_API void c4socket_received	(	C4Socket *	socket,
		C4Slice	data )

Notifies LiteCore that data was received from the socket.

If the factory's framing equals to kC4NoFraming, the data must be a single complete message; otherwise it's raw bytes that will be un-framed by LiteCore. LiteCore will acknowledge when it's received and processed the data, by calling C4SocketFactory.completedReceive. For flow-control purposes, the client should keep track of the number of unacknowledged bytes, and stop reading from the underlying stream if that grows too large.

Note

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

Parameters

socket	The socket.
data	The data received, either a message or raw bytes.

c4socket_registerFactory()

CBL_CORE_API void c4socket_registerFactory

(

C4SocketFactory

factory

)

One-time registration of default socket callbacks.

If used, must be called before using any socket-based API including the replicator. Do not call multiple times.

c4Socket_setNativeHandle()

CBL_CORE_API void c4Socket_setNativeHandle	(	C4Socket *	,
		void *	)

Associates an opaque "native handle" with this object.

You can use this to store whatever you need to represent the socket's implementation, like a file descriptor.

Note

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