ColdC provides the ability to handle network sockets with the following functions:
| bind_port() | close_connection() | connection() |
| cwrite() | cwritef() | open_connection() |
| unbind_port() | reassign_connection() |
Connections are bound to a connection object. The driver will use the following methods on a connection object:
- .connect()
- .disconnect()
- .failed()
- .parse()
There are two types of connections which can be created. The first is a server connection, or a passive connection. To do this the driver listens on a network port and waits for incoming connections. The second type is an client connection, or an active connection. This type of connection is established by the driver to another network host.
Server Connection
To establish a server connection first call the function bind_port(). The argument to this function is the network port to listen on. Note: most operating systems will restrict low numbered ports (usually anything below 1024 is restricted and can only be opened with special privelages). If there are no errors, the current object will listen as a server on the specified port.
When an external client opens a connection the driver will call the method .connect() with two arguments. The first argument is a string specifying the remote IP address of the client. The second argument is an integer specifying the socket where the connection was established. In general this number can be ignored.
After the method .connect() is called, data received on the connection will be sent as a buffer to the method .parse(). Data is sent to the connection using the functions cwrite() and cwritef().
If the client terminates the connection, the method .disconnect() is called. This method will also be called if the object terminates the connection through close_connection().
If multiple connections will be received on a network port, it is suggested that when a connection is started the connection object either reassigns the connection to another connection object (using the function reassign_connection()), or it notifies a new connection object to rebind the port to itself. If this is not done, new connections will preempt and close the older connection (as only one connection can be on an object at a time).
Client Connection
To establish a client connection call the function open_connection() with the first argument as a string specifing the IP address of the host, and the second argument an integer specifying the network port to connect on. This function is not a blocking function. Calling it will simply start the process of opening a connection. If there are no immediate errors the function will return normally.
When a connection is opened the driver will call the method .connect() on the current object, with the argument being an integer task ID for the task which called open_connection(). Connection code may wish to suspend() after calling open_connection(), then have the method .connect() resume the task when it is received.
If the connection could not be established, the method .failed() is called instead. The first argument is once again the task ID, the second argument is an error representing the reason for the failure of the connection to be established.
Once the connection is established, input and output is handled the same as on a server connection.
