Introduction

The socket interface allows creating a thread per socket that passes output to a callback when available.

TCP/TLSv1/SSLv3/UDP are supported on linux and windows, additionaly SSLv2 is supported depending on the openssl implementation. DTLSv1 is supported on linux only.

Steps to creating a socket

Create a SSL session if required use one of tlsv1_init() sslv2_init() sslv3_init() dtlsv1_init().
Create a socket either as a server [bind] or client [connect] choices are tcpbind() tcpconnect() udpbind() udpconnect()
Start up the client and or server threads using socketserver() and socketclient()
When done call close_sock() on the socket.

SSL Support

Internally this is supplied from openssl various other openssl functions are used in this library ie base64 encoding. you will require a CA certificate[s] and a signed client certificate and key supply the paths to the initilization routines. The verify flag can be used to pass openssl verification flags.

Todo:: passphrase support

Socket Creation

To create a socket pass the socket creation function the ipaddr/hostname either ipv4 or ipv6 the port and the optional ssl session created above.

the result from this function will be the socket used in all other interactions.

Starting A Socket

A socket is started when the thread for the socket starts with socketclient or socketserver the latter creates a bucketlist for children and enables some extra options for DTLSv1.

They both requre the socket structure created above a callback routine called when data is available and a reference to data that is passed back in the callback. For thread management a thread cleanup function can be supplied that is called on thread closure this will allow cleaning up the data reference will be passed to this function as well.

In addition there is a optional callback for servers that will be called when a connection is accepted to allow for any handling needed on the server.

See Also: socketrecv; threadcleanup

Reading/Writeing To Sockets

There are 2 functions each for reading and writing to sockets socketread_d() and socketwrite_d() are required for stateless datagram sockets (UDP), they differ from socketread() and socketwrite() in that they use a additional addr paramater containing the remote address. passing NULL for this value is equivilent too socketread() / socketwrite().

Unix Domain Sockets

These are supported for SOCK_DGRAM and SOCK_STREAM and are capable of multiple connections.

unixsocket_server() and unixsocket_client() return sockets (fwsocket) and use of socketread_d() and socketwrite_d().

SOCK_DGRAM requires creating a tempoary socket file for use as a endpoint to support multiple connections this is handled internally but its best to only use SOCK_STREAM.

Multicast Sockets

Multicast sockets can be created and used as any other socket they only support SOCK_DGRAM traffic as there is no concept of client/server communication. A thread will be opened as a client writing to the socket should be done with socketwrite().

There 2 helper routines that allow generating multicast groups mcast4_ip() and mcast6_ip().

See Also: mcast_socket(); socketclient()

Example Code

Socket Example (Echo Server/Client) contains a example of socket code implementing a a echo server with 2 clients.