Parasol Framework Manual

Represents a single socket connection to a client IP address.

If a Netsocket is running in server mode then it will create a new ClientSocket object every time that a new connection is opened by a client. This is a very simple class that assists in the management of I/O between the client and server.

Structure

The ClientSocket class consists of the following fields:

Name	Type	Comment
Client	struct NetClient *	Parent client structure
ClientData	APTR	Free for user data storage.
ConnectTime	BIGINT	System time for the creation of this socket
Incoming	FUNCTION	Callback for data being received from the socket
MsgLen	INT	Length of the current incoming message
Next	*ClientSocket	Next socket in the chain
Outgoing	FUNCTION	Callback for data being sent over the socket
Prev	*ClientSocket	Previous socket in the chain
ReadCalled	INT	TRUE if the Read action has been called

Actions

The following actions are currently supported:

Read

Read incoming data from a client socket.

ERR acRead(*Object, APTR Buffer, LONG Length, LONG *Result)

Parameter	Description
Buffer	Points a buffer that will receive the data.
Length	The total number of bytes to read from the object. This value cannot exceed the size of the Buffer.
Result	The Read action will write this parameter with the total number of bytes read into the Buffer.

The Read() action will read incoming data from the socket and write it to the provided buffer. If the socket connection is safe, success will always be returned by this action regardless of whether or not data was available. Almost all other return codes indicate permanent failure, and the socket connection will be closed when the action returns.

Error Codes

Okay	Read successful (if no data was on the socket, success is still indicated).
Failed	A permanent failure has occurred and socket has been closed.
Disconnected	The socket connection is closed.
NullArgs	Function call missing argument value(s)

Write

Writes data to the socket.

ERR acWrite(*Object, APTR Buffer, LONG Length, LONG Result)

Parameter	Description
Buffer	A buffer containing the data that will be written to the object.
Length	The total number of bytes to write to the object.
Result	This parameter with be updated with the total number of bytes written from the Buffer.

Write raw data to a client socket with this action. Write connections are buffered, so any data overflow generated in a call to this action will be buffered into a software queue. Resource limits placed on the software queue are governed by the NetSocket⇒MsgLimit value.

Methods

The following methods are currently supported:

ReadClientMsg Read a message from the socket.

ERR cs::ReadClientMsg(OBJECTPTR Object, APTR * Message, LONG * Length, LONG * Progress, LONG * CRC)

Parameter	Description
Message	A pointer to the message buffer will be placed here if a message has been received.
Length	The length of the message is returned here.
Progress	The number of bytes that have been read for the incoming message.
CRC	Indicates the CRC value that the message is expected to match.

This method reads messages that have been sent to the socket using Parasol Message Protocols. Any message sent with the WriteClientMsg() method will conform to this protocol, thus simplifying message transfers between programs based on the core platform at either point of the network link.

This method never returns a successful error code unless an entire message has been received from the sender.

Error Codes

Okay	A complete message has been read and indicated in the result parameters.
BadData	The message header or tail was invalid, or the message length exceeded internally imposed limits.
LimitedSuccess	Some data has arrived, but the entire message is incomplete. The length of the incoming message may be indicated in the Length parameter.
Args	Invalid arguments passed to function.
NoData	No new data was found for the socket.
AllocMemory	A message buffer could not be allocated.
NullArgs	Function call missing argument value(s)

WriteClientMsg Writes a message to the socket.

ERR cs::WriteClientMsg(OBJECTPTR Object, APTR Message, LONG Length)

Parameter	Description
Message	Pointer to the message to send.
Length	The length of the `Message`.

Messages can be written to sockets with the WriteClientMsg method and read back by the receiver with ReadClientMsg(). The message data is sent through the Write() action, so the standard process will apply (the message will be queued and does not block if buffers are full).

Error Codes

Okay	Operation successful.
Args	Invalid arguments passed to function.
OutOfRange	A specified number is outside of the valid range.

ClientSocket Class

Structure

Actions

Methods

NetClient Structure

Field	Type	Description
IP	char	IP address in 4/8-byte format
Next	struct NetClient *	Next client in the chain
Prev	struct NetClient *	Previous client in the chain
NetSocket	objNetSocket *	Reference to the parent socket
Sockets	objClientSocket *	Pointer to a list of sockets opened with this client.
ClientData	APTR	Free for user data storage.
TotalSockets	LONG	Count of all created sockets