Player TCP library. More...

#define	PLAYERTCP_EXPORT
	Default TCP port.
#define	PLAYERTCP_DEFAULT_PORT 6665
	Default TCP port.
#define	PLAYERTCP_READBUFFER_SIZE 65536
	We try to read() incoming messages in chunks of this size.
#define	PLAYERTCP_WRITEBUFFER_SIZE 65536
	We try to write() outgoing messages in chunks of this size.

Detailed Description

Player TCP library.

This library moves messages between Player message queues and TCP sockets.

Data modes

Clients can use two modes for receiving data. These are PUSH and PULL modes. There are some important differences between them. These are summarised here. These modes only affect the clients' message queues, that is they do not affect how messages are received from clients.

In PUSH mode all messages are sent as soon as possible. This is usually when there is room in the operating system's buffer for the message. Clients should read these messages as usual. For example, the libplayerc client library will read exactly one message for each call to the client read function.

In PULL mode:

Messages are only sent to the client when they are marked as ready in the client's message queue.
PLAYER_MSGTYPE_DATA messages are not marked as ready until the client requests data.
All other messages (PLAYER_MSGTYPE_RESP_ACK and PLAYER_MSGTYPE_RESP_NACK messages) are marked as ready upon entering the queue.
When a PLAYER_PLAYER_REQ_DATA message is received, all messages in the client's queue are marked as ready. A PLAYER_MSGTYPE_SYNCH message is pushed onto the end of the queue.

A client in PULL mode should request data before performing a read by sending a PLAYER_PLAYER_REQ_DATA request message. The client should then continue to receive and handle all messages until it receives the PLAYER_MSGTYPE_SYNCH message. Note that the PLAYER_MSGTYPE_RESP_ACK for the PLAYER_PLAYER_REQ_DATA will come at the end of all other waiting data (but before the PLAYER_MSGTYPE_SYNCH message), due to the way the message queue system functions. This means that client libraries should read and store all other messages when waiting for a PLAYER_MSGTYPE_RESP_ACK, then process them at the beginning of their read function after sending the PLAYER_PLAYER_REQ_DATA message.

Todo:

- More verbose documentation on this library, including the protocol

Define Documentation

#define PLAYERTCP_READBUFFER_SIZE 65536

We try to read() incoming messages in chunks of this size.

We also calloc() and realloc() read buffers in multiples of this size.

#define PLAYERTCP_WRITEBUFFER_SIZE 65536

We try to write() outgoing messages in chunks of this size.

We also calloc() and realloc() write buffers in multiples of this size.