C4SocketFactory Struct Reference

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...

#include <c4SocketTypes.h>

Data Fields
C4SocketFraming	framing
	This should be set to kC4NoFraming if the socket factory acts as a stream of messages, kC4WebSocketClientFraming or kC4WebSocketServerFraming if it's a byte stream.
void *	context
	An arbitrary value that will be passed to the open callback.
void(*	open )(C4Socket *socket, const C4Address *addr, C4Slice options, void *context)
	Called to open a socket to a destination address.
void(*	write )(C4Socket *socket, C4SliceResult allocatedData)
	Called to write to the socket.
void(*	completedReceive )(C4Socket *socket, size_t byteCount)
	Called to inform the socket that LiteCore has finished processing the data from a c4socket_received call.
void(*	close )(C4Socket *socket)
	Called to close the socket.
void(*	requestClose )(C4Socket *socket, int status, C4String message)
	Called to close the socket.
void(*	dispose )(C4Socket *socket)
	Called to tell the client that a C4Socket object is being disposed/freed after it's closed.

Detailed Description

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.

A group of callbacks that define the implementation of sockets.

These callbacks will be invoked on arbitrary background threads owned by LiteCore. They should return quickly, and perform the operation asynchronously without blocking.

Field Documentation

close

void(* C4SocketFactory::close) (C4Socket *socket)

Called to close the socket.

This is only called if framing doesn't equal kC4NoFraming, i.e. the socket operates at the byte level. Otherwise it may be left NULL. No more write calls will be made; you should process any remaining incoming bytes by calling c4socket_received, then call c4socket_closed when the socket closes.

Warning

You MUST call c4socket_closed, or the replicator will wait forever!

Parameters

socket

The socket to close.

completedReceive

void(* C4SocketFactory::completedReceive) (C4Socket *socket, size_t byteCount)

Called to inform the socket that LiteCore has finished processing the data from a c4socket_received call.

This can be used for flow control: you should keep track of the number of bytes you've sent to LiteCore, incrementing the number when you call c4socket_received, and decrementing it when completedReceived is called. If the number goes above some threshold, you should take measures to stop receiving more data, e.g. by not reading more bytes from the socket. Otherwise memory usage can balloon as more and more data arrives and must be buffered in memory.

Parameters

socket	The socket that whose incoming data was processed.
byteCount	The number of bytes of data processed (the size of the data slice passed to a c4socket_received() call.)

context

void* C4SocketFactory::context

An arbitrary value that will be passed to the open callback.

dispose

void(* C4SocketFactory::dispose) (C4Socket *socket)

Called to tell the client that a C4Socket object is being disposed/freed after it's closed.

The implementation of this function can then dispose any state associated with the nativeHandle.

Set this to NULL if you don't need the call.

Parameters

socket

The socket being disposed.

framing

C4SocketFraming C4SocketFactory::framing

This should be set to kC4NoFraming if the socket factory acts as a stream of messages, kC4WebSocketClientFraming or kC4WebSocketServerFraming if it's a byte stream.

open

void(* C4SocketFactory::open) (C4Socket *socket, const C4Address *addr, C4Slice options, void *context)

Called to open a socket to a destination address.

This function should operate asynchronously, returning immediately. When the socket opens, call c4socket_opened, or if it fails to open, call c4socket_closed with an appropriate error.

Parameters

socket	A new C4Socket instance to be opened. Its nativeHandle will be NULL; the implementation of this function will probably store a native socket reference there.
addr	The address (URL) to connect to.
options	A Fleece-encoded dictionary containing additional parameters, such as kC4SocketOptionWSProtocols, which provides the WebSocket protocol names to include in the HTTP request header.
context	The value of the C4SocketFactory's context field.

requestClose

void(* C4SocketFactory::requestClose) (C4Socket *socket, int status, C4String message)

Called to close the socket.

This is only called if framing equals to kC4NoFraming, i.e. the socket operates at the message level. Otherwise it may be left NULL.

Your implementation should:

1. send a message that tells the remote peer that it's closing the connection;
2. wait for acknowledgement;
3. while waiting, handle any further incoming messages by calling c4socket_received;
4. after 5 seconds of waiting, give up and go to step 5;
5. upon acknowledgement or timeout, close its connection and call c4socket_closed.

This call can also occur before the socket has opened, if the replicator decides to time out. In this situation – i.e. if you have not yet called c4socket_opened – you should tear down your connection and call c4socket_closed.

Warning

You MUST call c4socket_closed, or the replicator will wait forever!

Parameters

socket	The C4Socket to close.
status	The WebSocket status code to send in the CLOSE message.
message	The text to send in the CLOSE message.

write

void(* C4SocketFactory::write) (C4Socket *socket, C4SliceResult allocatedData)

Called to write to the socket.

If framing equals kC4NoFraming, the data is a complete message, and your socket implementation is responsible for framing it; otherwise, it's just raw bytes to write to the stream, including the necessary WebSocket framing.

After data has been written, you must call c4socket_completedWrite. (You can call this once after all the data is written, or multiple times with smaller numbers, as long as the total byte count equals the size of the allocatedData.)

Parameters

socket	The socket to write to.
allocatedData	The data/message to send. As this is a C4SliceResult, your implementation of this function is responsible for releasing it when done.

---

The documentation for this struct was generated from the following file:

• c4SocketTypes.h