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 void	c4socket_gotHTTPResponse (C4Socket *socket, int httpStatus, C4Slice responseHeadersFleece)
	Notification that a socket has received an HTTP response, with the given headers (encoded as a Fleece dictionary.) This should be called just before c4socket_opened or c4socket_closed.
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)
	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 )

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

This is used by listeners to handle an incoming replication connection.

Note

This function is thread-safe.

Warning

You MUST immediately call c4socket_retain on this pointer (and the usual c4socket_release when done.) This is inconsistent with the general ref-counting convention, but fixing this function to return a retained value would cause all existing platforms to leak C4Sockets, so we're leaving it alone.

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 making the connection.

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 socket has received an HTTP response, with the given headers (encoded as a Fleece dictionary.) 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_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.