inetsocket.h File Reference

This file contains sockets and socket sets. More...

#include <gwenhywfar/gwenhywfarapi.h>
#include "gwenhywfar/error.h"
#include <gwenhywfar/inetaddr.h>

Go to the source code of this file.

Error Codes
#define	GWEN_SOCKET_ERROR_ABORTED   (-8)
#define	GWEN_SOCKET_ERROR_BAD_SOCKETTYPE   (-1)
#define	GWEN_SOCKET_ERROR_BROKEN_PIPE   (-9)
#define	GWEN_SOCKET_ERROR_IN_PROGRESS   (-4)
#define	GWEN_SOCKET_ERROR_INTERRUPTED   (-6)
#define	GWEN_SOCKET_ERROR_NOT_OPEN   (-2)
#define	GWEN_SOCKET_ERROR_STARTUP   (-5)
#define	GWEN_SOCKET_ERROR_TIMEOUT   (-3)
#define	GWEN_SOCKET_ERROR_TYPE   "Socket"
#define	GWEN_SOCKET_ERROR_UNSUPPORTED   (-7)
Connecting and Disconnecting
These functions allow active and passive connections to other hosts.
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Accept (GWEN_SOCKET *sp, GWEN_INETADDRESS **addr, GWEN_SOCKET **newsock)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Accept_Wait (GWEN_SOCKET *sp, GWEN_INETADDRESS **addr, GWEN_SOCKET **newsock, int timeout)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Bind (GWEN_SOCKET *sp, const GWEN_INETADDRESS *addr)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Connect (GWEN_SOCKET *sp, const GWEN_INETADDRESS *addr)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Connect_Wait (GWEN_SOCKET *sp, const GWEN_INETADDRESS *addr, int timeout)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Listen (GWEN_SOCKET *sp, int backlog)
Creation and Destruction
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Close (GWEN_SOCKET *sp)
GWENHYWFAR_API void	GWEN_Socket_free (GWEN_SOCKET *sp)
GWENHYWFAR_API GWEN_SOCKET *	GWEN_Socket_new (GWEN_SOCKETTYPE socketType)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Open (GWEN_SOCKET *sp)
Informational Functions
These functions return some usefull information about sockets or connections.
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_GetPeerAddr (GWEN_SOCKET *sp, GWEN_INETADDRESS **addr)
GWENHYWFAR_API GWEN_SOCKETTYPE	GWEN_Socket_GetSocketType (GWEN_SOCKET *sp)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Select (GWEN_SOCKETSET *rs, GWEN_SOCKETSET *ws, GWEN_SOCKETSET *xs, int timeout)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_WaitForRead (GWEN_SOCKET *sp, int timeout)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_WaitForWrite (GWEN_SOCKET *sp, int timeout)
Socket Settings Functions
These functions manipulate settings on a socket.
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_GetSocketError (GWEN_SOCKET *sp)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_SetBlocking (GWEN_SOCKET *sp, int fl)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_SetBroadcast (GWEN_SOCKET *sp, int fl)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_SetReuseAddress (GWEN_SOCKET *sp, int fl)
Data Exchange Functions
These functions handle exchange of data with other hosts via the Internet Protocol.
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Read (GWEN_SOCKET *sp, char *buffer, int *bsize)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Read_Wait (GWEN_SOCKET *sp, char *buffer, int *bsize, int timeout, int force)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_ReadFrom (GWEN_SOCKET *sp, GWEN_INETADDRESS **addr, char *buffer, int *bsize)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Write (GWEN_SOCKET *sp, const char *buffer, int *bsize)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_Write_Wait (GWEN_SOCKET *sp, const char *buffer, int *bsize, int timeout, int force)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_Socket_WriteTo (GWEN_SOCKET *sp, const GWEN_INETADDRESS *addr, const char *buffer, int *bsize)
Add, remove, check sockets
These functions allow adding and removing sockets to/from a socket set as well as checking whether a specific socket is part of a socket set.
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_SocketSet_AddSocket (GWEN_SOCKETSET *ssp, const GWEN_SOCKET *sp)
GWENHYWFAR_API int	GWEN_SocketSet_GetSocketCount (GWEN_SOCKETSET *ssp)
GWENHYWFAR_API int	GWEN_SocketSet_HasSocket (GWEN_SOCKETSET *ssp, const GWEN_SOCKET *sp)
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_SocketSet_RemoveSocket (GWEN_SOCKETSET *ssp, const GWEN_SOCKET *sp)
Creation and destruction
These functions initialize and de-initialize socket sets. A socket set is a group of sockets. They are used for the function GWEN_Socket_Select.
GWENHYWFAR_API GWEN_ERRORCODE	GWEN_SocketSet_Clear (GWEN_SOCKETSET *ssp)
GWENHYWFAR_API void	GWEN_SocketSet_free (GWEN_SOCKETSET *ssp)
GWENHYWFAR_API GWEN_SOCKETSET *	GWEN_SocketSet_new ()
Typedefs
typedef GWEN_SOCKETSTRUCT	GWEN_SOCKET
typedef GWEN_SOCKETSETSTRUCT	GWEN_SOCKETSET
Enumerations
enum	GWEN_SOCKETTYPE { GWEN_SocketTypeTCP = 1, GWEN_SocketTypeUDP, GWEN_SocketTypeRAW, GWEN_SocketTypeUnix }

---

Detailed Description

This file contains sockets and socket sets.

---

Define Documentation

#define GWEN_SOCKET_ERROR_ABORTED   (-8)

#define GWEN_SOCKET_ERROR_BAD_SOCKETTYPE   (-1)

#define GWEN_SOCKET_ERROR_BROKEN_PIPE   (-9)

#define GWEN_SOCKET_ERROR_IN_PROGRESS   (-4)

#define GWEN_SOCKET_ERROR_INTERRUPTED   (-6)

#define GWEN_SOCKET_ERROR_NOT_OPEN   (-2)

#define GWEN_SOCKET_ERROR_STARTUP   (-5)

#define GWEN_SOCKET_ERROR_TIMEOUT   (-3)

#define GWEN_SOCKET_ERROR_TYPE   "Socket"

#define GWEN_SOCKET_ERROR_UNSUPPORTED   (-7)

---

Typedef Documentation

typedef struct GWEN_SOCKETSTRUCT GWEN_SOCKET

typedef struct GWEN_SOCKETSETSTRUCT GWEN_SOCKETSET

---

Enumeration Type Documentation

enum GWEN_SOCKETTYPE

Socket types Enumerator: GWEN_SocketTypeTCP  GWEN_SocketTypeUDP  GWEN_SocketTypeRAW  GWEN_SocketTypeUnix

---

Function Documentation

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Accept (  GWEN_SOCKET *  sp, GWEN_INETADDRESS **  addr, GWEN_SOCKET **  newsock )

This accepts a new connection on the given socket. This socket must be listening (achieved by calling GWEN_Socket_Listen). Parameters: sp  socket which is listening addr  pointer to a pointer to an address. Upon return this pointer will point to a newly allocated address containing the address of the connected peer. Please note that if upon return this value is !=NULL then you are responsible for freeing this address ! newsock  pointer to a pointer to a socket. Upon return this holds the pointer to a newly allocated socket. Please note that if upon return this value is !=NULL then you are responsible for freeing this socket !

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Accept_Wait (  GWEN_SOCKET *  sp, GWEN_INETADDRESS **  addr, GWEN_SOCKET **  newsock, int  timeout )

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Bind (  GWEN_SOCKET *  sp, const GWEN_INETADDRESS *  addr )

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Close (  GWEN_SOCKET *  sp  )

Unarms a socket thus closing any connection associated with this socket.

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Connect (  GWEN_SOCKET *  sp, const GWEN_INETADDRESS *  addr )

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Connect_Wait (  GWEN_SOCKET *  sp, const GWEN_INETADDRESS *  addr, int  timeout )

Tries to connect to the given addres. This function calls GWEN_WaitCallback. Parameters: addr  address to connect to timeout  timeout in seconds, special values: 0: don ot wait <li-1: wait until hell freezes if necessary

GWENHYWFAR_API void GWEN_Socket_free (  GWEN_SOCKET *  sp  )

Destructor.

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_GetPeerAddr (  GWEN_SOCKET *  sp, GWEN_INETADDRESS **  addr )

Retrieves the peer's address Parameters: sp  socket addr  pointer to a pointer to an GWEN_INETADDRESS. Upon successful return that pointer will point to the address of the peer. In that case the caller is responsible for freeing that address.

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_GetSocketError (  GWEN_SOCKET *  sp  )

Returns a pending socket error. This is used when trying to connect to a server when in non-blocking mode. In this case the connect call will in some cases return with an error code indicating that the connect is in progress. Later you will then need to find out whether that connect succeeded or not. And this is the function which can tell you that ;-) Parameters: sp  socket

GWENHYWFAR_API GWEN_SOCKETTYPE GWEN_Socket_GetSocketType (  GWEN_SOCKET *  sp  )

Returns the socket type. Parameters: sp  socket

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Listen (  GWEN_SOCKET *  sp, int  backlog )

GWENHYWFAR_API GWEN_SOCKET* GWEN_Socket_new (  GWEN_SOCKETTYPE  socketType  )

Constructor. You should always use this to create socket variables.

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Open (  GWEN_SOCKET *  sp  )

Arms the socket so that it can be used. This really creates a system socket.

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Read (  GWEN_SOCKET *  sp, char *  buffer, int *  bsize )

Read bytes from a socket. Parameters: sp  socket buffer  pointer to the buffer to receive the data bsize  pointer to an integer variable. Upon call this should hold the number of bytes to read, upon return it will contain the number of bytes actually read.

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Read_Wait (  GWEN_SOCKET *  sp, char *  buffer, int *  bsize, int  timeout, int  force )

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_ReadFrom (  GWEN_SOCKET *  sp, GWEN_INETADDRESS **  addr, char *  buffer, int *  bsize )

Reads bytes from an UDP socket, which is connectionless. Parameters: sp  socket addr  pointer to pointer to an address to receive the address of the peer we have received data from. Please note that if upon return this value is !=NULL then you are responsible for freeing this address ! buffer  pointer to a buffer to store the received data in bsize  pointer to an integer variable. Upon call this should hold the number of bytes to read, upon return it will contain the number of bytes actually read.

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Select (  GWEN_SOCKETSET *  rs, GWEN_SOCKETSET *  ws, GWEN_SOCKETSET *  xs, int  timeout )

This function waits for a group of sockets to change their state. Parameters: rs  socket set, wait for readability of those sockets ws  socket set, wait for writeability of those sockets xs  socket set, wait for "exceptional events" on those sockets timeout  time to wait in milliseconds. If <0 then this function will wait forever, if ==0 then it won't wait at all.

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_SetBlocking (  GWEN_SOCKET *  sp, int  fl )

Toggles the sockets blocking/non-blocking mode. Parameters: sp  socket fl  if 0 then nonblocking is requested, otherwise blocking is assumed

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_SetBroadcast (  GWEN_SOCKET *  sp, int  fl )

Toggles the sockets broadcast/non-broadcast mode. If in broadcast mode (for UDP sockets only) the socket is able to receive packets that have been sent to a broadcast address, otherwise those packets are ignored. Parameters: sp  socket fl  if nonzero then broadcast is enabled

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_SetReuseAddress (  GWEN_SOCKET *  sp, int  fl )

Normally after closing a socket the occupied TCP/UDP port will be unavailable for another call to the system function bind (2). If reusing is allowed then this latency is removed. This function is usefull for servers. Parameters: sp  socket fl  if nonzero then reusing the address is enabled

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_WaitForRead (  GWEN_SOCKET *  sp, int  timeout )

Wait until the given socket becomes readable or a timeout occurrs. Parameters: sp  socket timeout  please see GWEN_Socket_Select for details

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_WaitForWrite (  GWEN_SOCKET *  sp, int  timeout )

Wait until the given socket becomes writeable or a timeout occurrs. Parameters: sp  socket timeout  please see GWEN_Socket_Select for details

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Write (  GWEN_SOCKET *  sp, const char *  buffer, int *  bsize )

Write bytes to an open socket. Parameters: sp  socket buffer  pointer to a buffer containing the bytes to be written bsize  pointer to an integer variable containing the number of bytes to write. Upon return this variable holds the number of bytes actually written. Please note that this function may write less bytes than expected!

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_Write_Wait (  GWEN_SOCKET *  sp, const char *  buffer, int *  bsize, int  timeout, int  force )

GWENHYWFAR_API GWEN_ERRORCODE GWEN_Socket_WriteTo (  GWEN_SOCKET *  sp, const GWEN_INETADDRESS *  addr, const char *  buffer, int *  bsize )

Writes data to an UDP socket, which is connectionless. Parameters: sp  socket addr  pointer to the address struct specifying the recipient buffer  pointer to a buffer containing the bytes to be written bsize  pointer to an integer variable containing the number of bytes to write. Upon return this variable holds the number of bytes actually written. Please note that this function may write less bytes than expected!

GWENHYWFAR_API GWEN_ERRORCODE GWEN_SocketSet_AddSocket (  GWEN_SOCKETSET *  ssp, const GWEN_SOCKET *  sp )

GWENHYWFAR_API GWEN_ERRORCODE GWEN_SocketSet_Clear (  GWEN_SOCKETSET *  ssp  )

GWENHYWFAR_API void GWEN_SocketSet_free (  GWEN_SOCKETSET *  ssp  )

GWENHYWFAR_API int GWEN_SocketSet_GetSocketCount (  GWEN_SOCKETSET *  ssp  )

GWENHYWFAR_API int GWEN_SocketSet_HasSocket (  GWEN_SOCKETSET *  ssp, const GWEN_SOCKET *  sp )

GWENHYWFAR_API GWEN_SOCKETSET* GWEN_SocketSet_new (   )

GWENHYWFAR_API GWEN_ERRORCODE GWEN_SocketSet_RemoveSocket (  GWEN_SOCKETSET *  ssp, const GWEN_SOCKET *  sp )

---