Internetprotocol-Sockets

int unittest_io_ipsocket( void )

Unittest client/server tcp/udp communications.

int init_ipsocket( /*out*/ipsocket_t  * ipsock, const struct  ipaddr_t  * localaddr )

Creates a new unconnected UDP network communication endpoint.  If localaddr does not describe an ipprotocol_UDP address EPROTONOSUPPORT is returned.  Unconnected sockets can be used to send and receive to/from a many network peers.

int initconnect_ipsocket( /*out*/ipsocket_t  * ipsock,    const struct  ipaddr_t  * remoteaddr,    const struct  ipaddr_t  * localaddr/*0  =  newany_ipaddr*/ )

Creates a connected network communication endpoint.  The socket has a local address described by localaddr and tries to establish a connection to a remote peer with its network address stored in remoteaddr.  The connection is only established if ipprotocol_TCP is used.  In case of ipprotocol_UDP the socket is configured to allow only to send to and receive from from a network peer with address remoteaddr.

EINVAL is returned if localaddr or remoteaddr is invalid or if they have different protocols.  Error code EAFNOSUPPORT indicates that ipversion_e from localaddr differs from remoteaddr.

Special value

In case localaddr is 0 it is set to newany_ipaddr with the same version and protocol as remoteaddr and the port number set to 0 (choose next free number).  After successfull connection the local address of the created ipsocket_t ipsock is assigned a free ip port and has an ip address of the network interface which connects to remoteaddr.

Performance

For TCP it is possible that this call needs some time to complete especially with a slow network connection.  So calling this function in a dedicated system worker thread is a good idea.

int initlisten_ipsocket( /*out*/ipsocket_t  * ipsock, const struct  ipaddr_t  * localaddr, uint16_t  max_outstanding_connections )

Creates a TCP server socket for accepting connections from peers (clients).  The parameter max_outstanding_connections sets the number of connections which are established automatically from the underlying operating system without calling initaccept_ipsocket.  To establish a new connections call initaccept_ipsocket.

Returns EOPNOTSUPP if localaddr uses a protocol other than TCP.

int initaccept_ipsocket( /*out*/ipsocket_t  * ipsock,    ipsocket_t  * listensock,    struct  ipaddr_t  * remoteaddr/*0  =  > ignored*/ )

Waits for an incoming connection request from a peer (client).  The parameter listensock must point to an ipsocket_t created with initlisten_ipsocket.  On successfull return the newly established connection is stored in ipsock.  The remote peer network address is returned in remoteaddr (if set != 0).

Returns

int free_ipsocket( /*out*/ipsocket_t  * ipsock )

Closes communication channel and frees system resources.

sys_iochannel_t io_ipsocket( const  ipsocket_t  * ipsock )

Returns the file descriptor sys_iochannel_t of the socket.

bool isconnected_ipsocket( const  ipsocket_t  * ipsock )

Returns if the socket is connected to a peer.  In case of an error false is returned.

bool islisten_ipsocket( const  ipsocket_t  * ipsock )

Returns true if the socket listens for incoming connections.  With this socket type you can wait for incoming connection requests from peers.  Use initaccept_ipsocket to query for neyl established connections.  In case of an error false is returned.

uint16_t protocol_ipsocket( const  ipsocket_t  * ipsock )

Returns protocol ipprotocol_e of the socket.  In case of error ipprotocol_ANY is returned.

uint16_t version_ipsocket( const  ipsocket_t  * ipsock )

Returns protocol version ipversion_e.  In case of an error ipversion_ANY is returned.

int localaddr_ipsocket( const  ipsocket_t  * ipsock, struct  ipaddr_t  * localaddr )

Returns local ip address in localaddr.  The parameter localaddr must have been allocated with <new_ipaddr> before this function is called.  Returns EAFNOSUPPORT in case ipversion of localaddr is not the same as of ipsock.

int remoteaddr_ipsocket( const  ipsocket_t  * ipsock, struct  ipaddr_t  * remoteaddr )

Returns remote ip address of peer in remoteaddr.  The parameter remoteaddr must have been allocated with <new_ipaddr> before this function is called.  Returns EAFNOSUPPORT in case ipversion of remoteaddr is not the same as of ipsock.

int bytestoread_ipsocket( const  ipsocket_t  * ipsock, /*out*/size_t  * unread_bytes )

Returns the number of bytes in the receive queue.  They can be read without waiting.  If you try to read more byte than the returned value in unread_bytes the read operation will not block.  But it could be return less than unread_bytes bytes in case socket is of type TCP and a out-of-band (urgent) data byte is stored in the receive queue.

int bytestowrite_ipsocket( const  ipsocket_t  * ipsock, /*out*/size_t  * unsend_bytes )

Returns the number of bytes in the send queue.  The number of bytes which can be written is the size of the send queue minus the returned value in unsend_bytes.  But the write operation is never blocking.  It writes only that much bytes as will fit into send queue.

int queuesize_ipsocket( const  ipsocket_t  * ipsock, /*out*/size_t  * queuesize_read, /*out*/size_t  * queuesize_write )

Returns the buffer size in bytes.  queuesize_read gives the number of bytes which can be received without reading.  queuesize_write gives the number of bytes which can be written without sending.

int setqueuesize_ipsocket( ipsocket_t  * ipsock,    size_t  queuesize_read/*0  =  > no change*/, size_t  queuesize_write/*0  =  > no change*/ )

Changes the size of the read and write queue.  To change only the read or write queue size set the other value to 0.

int read_ipsocket( ipsocket_t  * ipsock, size_t  maxdata_len, /*out*/uint8_t  data[maxdata_len], /*out*/size_t  * bytes_read )

Reads bytes from read queue at max maxdata_len bytes.  This call returns EAGAIN if the read queue is empty.  It returns less than maxdata_len bytes if the queue contains less bytes.

int write_ipsocket( ipsocket_t  * ipsock, size_t  maxdata_len, const  uint8_t  data[maxdata_len], /*out*/size_t  * bytes_written )

Transfers maxdata_len bytes into internal write (send) queue.  This call returns EAGAIN if the write queue is full.  It writes less than maxdata_len bytes if the queue contains less free space.

int readoob_ipsocket( ipsocket_t  * ipsock, size_t  maxdata_len, /*out*/uint8_t  data[maxdata_len], /*out*/size_t  * bytes_read, /*out*/size_t  * oob_offset )

Same as read_ipsocket excepts returns additional OOB index.  This index indicates if there is “out of band” data in the stream.  oob_offset is set to maxdata_len if there is no oob data byte in the stream.  If there is a oob data byte stored in the read queue oob_offset points to it (data[oob_offset]) and has a value smaller than maxdata_len.

OODB_INLINE

This option is set during init_ipsocket and all oob-data could also be read with a normal read_ipsocket.  The difference is that read_ipsocket returns less data than possible (see bytestoread_ipsocket) if it encounters an oob byte.  And only the next call to read_ipsocket will return the oob byte and any following data.  readoob_ipsocket will handle this for you and returns an index which indicates if an oob was read.

int writeoob_ipsocket( ipsocket_t  * ipsock, uint8_t  data )

Writes a single byte of “out of band” data (urgent data).  This operation is only supported by TCP and on an UDP socket EOPNOTSUPP is returned.  If you call it more than once and if the previous oob-data byte was not read by the receiver the previous written oob byte will loose its special oob state and is returned as normal data.

int readfrom_ipsocket( ipsocket_t  * ipsock, struct  ipaddr_t  * remoteaddr, size_t  maxdata_len, /*out*/uint8_t  data[maxdata_len], /*out*/size_t  * bytes_read )

Same as read_ipsocket but for unconnected (UDP) sockets.  In addition to the read bytes the address of the sender is also returned in remoteaddr.  Error code EAFNOSUPPORT is returned in case remoteaddr is not the same ipversion_e as ipsocket_t.

int writeto_ipsocket( ipsocket_t  * ipsock, const struct  ipaddr_t  * remoteaddr, size_t  maxdata_len, const  uint8_t  data[maxdata_len], /*out*/size_t  * bytes_written )

Same as write_ipsocket but for unconnected (UDP) sockets.  In addition to bytes to write the caller has to supply the network address of the receiver.

Returns

int initconnect_ipsocketasync( /*out*/ipsocket_async_t  * ipsockasync, const struct  ipaddr_t  * remoteaddr, const struct  ipaddr_t  * localaddr )

Same as <initconnect_ipsocket> except for async operation.  Call success_ipsocketasync to check if connect request operation has completed.

int free_ipsocketasync( ipsocket_async_t  * ipsockasync )

Closes socket and frees all resources.  Any pending connection operations are aborted.

int convert_ipsocketasync( ipsocket_async_t  * ipsockasync, /*out*/ipsocket_t  * ipsock )

Converts ipsocket_async_t into ipsocket_t.

In case of success (returns 0) ipsockasync is reset to ipsocket_async_FREE and ipsock contains a connected socket ready for read/write operations.

In case success_ipsocketasync does not return 0 this same error code is returned and nothing is done.

int success_ipsocketasync( ipsocket_async_t  * ipsockasync )

Returns 0 if async connect completed.  Returns EINPROGRESS if the operation is not completed yet.  Another value != 0 indicates that the operation completed with an error.

int waitms_ipsocketasync( ipsocket_async_t  * ipsockasync,    uint32_t  millisec/*0  =  > no timeout*/ )

Waits until operation completes.  Returns EINPROGRESS in case of timeout and 0 in case operation completed.  Call success_ipsocketasync to check if an error occurred.