Socket Functions

Collaboration diagram for Socket Functions:

Creation and destruction
GWENHYWFAR_API GWEN_SOCKET *	GWEN_Socket_new (GWEN_SOCKETTYPE socketType)
GWENHYWFAR_API GWEN_SOCKET *	GWEN_Socket_fromFile (int fd)
GWENHYWFAR_API void	GWEN_Socket_free (GWEN_SOCKET *sp)
GWENHYWFAR_API int	GWEN_Socket_Open (GWEN_SOCKET *sp)
GWENHYWFAR_API int	GWEN_Socket_Close (GWEN_SOCKET *sp)

Connecting and Disconnecting
These functions allow active and passive connections to other hosts.
GWENHYWFAR_API int	GWEN_Socket_Connect (GWEN_SOCKET *sp, const GWEN_INETADDRESS *addr)
GWENHYWFAR_API int	GWEN_Socket_Bind (GWEN_SOCKET *sp, const GWEN_INETADDRESS *addr)
GWENHYWFAR_API int	GWEN_Socket_Listen (GWEN_SOCKET *sp, int backlog)
GWENHYWFAR_API int	GWEN_Socket_Accept (GWEN_SOCKET *sp, GWEN_INETADDRESS **addr, GWEN_SOCKET **newsock)

Informational Functions
These functions return some usefull information about sockets or connections.
GWENHYWFAR_API GWEN_SOCKETTYPE	GWEN_Socket_GetSocketType (GWEN_SOCKET *sp)
GWENHYWFAR_API int	GWEN_Socket_GetPeerAddr (GWEN_SOCKET *sp, GWEN_INETADDRESS **addr)
GWENHYWFAR_API uint32_t	GWEN_Socket_GetFlags (const GWEN_SOCKET *sp)
GWENHYWFAR_API void	GWEN_Socket_AddFlags (GWEN_SOCKET *sp, uint32_t f)
GWENHYWFAR_API void	GWEN_Socket_SubFlags (GWEN_SOCKET *sp, uint32_t f)
GWENHYWFAR_API int	GWEN_Socket_Select (GWEN_SOCKETSET *rs, GWEN_SOCKETSET *ws, GWEN_SOCKETSET *xs, int timeout)
GWENHYWFAR_API int	GWEN_Socket_WaitForRead (GWEN_SOCKET *sp, int timeout)
GWENHYWFAR_API int	GWEN_Socket_WaitForWrite (GWEN_SOCKET *sp, int timeout)

Data Exchange Functions
These functions handle exchange of data with other hosts via the Internet Protocol.
GWENHYWFAR_API int	GWEN_Socket_Read (GWEN_SOCKET *sp, char *buffer, int *bsize)
GWENHYWFAR_API int	GWEN_Socket_Write (GWEN_SOCKET *sp, const char *buffer, int *bsize)
GWENHYWFAR_API int	GWEN_Socket_ReadFrom (GWEN_SOCKET *sp, GWEN_INETADDRESS **addr, char *buffer, int *bsize)
GWENHYWFAR_API int	GWEN_Socket_WriteTo (GWEN_SOCKET *sp, const GWEN_INETADDRESS *addr, const char *buffer, int *bsize)

Socket Settings Functions
These functions manipulate settings on a socket.
GWENHYWFAR_API int	GWEN_Socket_SetBlocking (GWEN_SOCKET *sp, int fl)
GWENHYWFAR_API int	GWEN_Socket_SetBroadcast (GWEN_SOCKET *sp, int fl)
GWENHYWFAR_API int	GWEN_Socket_GetSocketError (GWEN_SOCKET *sp)
GWENHYWFAR_API int	GWEN_Socket_SetReuseAddress (GWEN_SOCKET *sp, int fl)
GWENHYWFAR_API int	GWEN_Socket_GetSocketInt (const GWEN_SOCKET *sp)

Detailed Description

This group operates on IP sockets.

Function Documentation

GWEN_Socket_Accept()

GWENHYWFAR_API int 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 !

Referenced by _checkSockets().

Here is the caller graph for this function:

GWEN_Socket_AddFlags()

GWENHYWFAR_API void GWEN_Socket_AddFlags	(	GWEN_SOCKET *	sp,
		uint32_t	f )

References GWENHYWFAR_API.

GWEN_Socket_Bind()

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

Referenced by _startListen().

Here is the caller graph for this function:

GWEN_Socket_Close()

GWENHYWFAR_API int GWEN_Socket_Close

(

GWEN_SOCKET *

sp

)

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

References GWENHYWFAR_API.

Referenced by GWEN_MsgEndpoint_Disconnect(), GWEN_MsgEndpoint_free(), GWEN_MsgEndpoint_SetSocket(), and GWEN_SyncIo_Socket_Disconnect().

Here is the caller graph for this function:

GWEN_Socket_Connect()

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

References GWENHYWFAR_API.

Referenced by _startConnect(), and GWEN_SyncIo_Socket_Connect().

Here is the caller graph for this function:

GWEN_Socket_free()

GWENHYWFAR_API void GWEN_Socket_free

(

GWEN_SOCKET *

sp

)

Destructor.

References GWENHYWFAR_API.

Referenced by _checkSockets(), _createAndSetupSocket(), _createAndSetupSocket(), _startConnect(), _startListen(), GWEN_MsgEndpoint_Disconnect(), GWEN_MsgEndpoint_free(), GWEN_MsgEndpoint_SetSocket(), GWEN_SyncIo_Socket_Connect(), GWEN_SyncIo_Socket_Disconnect(), and GWEN_SyncIo_Socket_FreeData().

Here is the caller graph for this function:

GWEN_Socket_fromFile()

GWENHYWFAR_API GWEN_SOCKET * GWEN_Socket_fromFile

(

int

fd

)

References GWENHYWFAR_API.

GWEN_Socket_GetFlags()

GWENHYWFAR_API uint32_t GWEN_Socket_GetFlags

(

const GWEN_SOCKET *

sp

)

References GWENHYWFAR_API.

GWEN_Socket_GetPeerAddr()

GWENHYWFAR_API int 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.

GWEN_Socket_GetSocketError()

GWENHYWFAR_API int 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

References GWENHYWFAR_API.

Referenced by _checkSockets().

Here is the caller graph for this function:

GWEN_Socket_GetSocketInt()

GWENHYWFAR_API int GWEN_Socket_GetSocketInt

(

const GWEN_SOCKET *

sp

)

This function should only be used if it is absolutely necessary, because it might not be supported by every system. However, it is currently supported by all systems on which the Berkeley Socket API is used (e.g. most if not all POSIX systems, in this implementation also WIN32). What you can do with the value returned depends very much on the underlying operating system. For POSIX systems the value returned is just a file handle as returned by e.g. socket().

Referenced by _addSockets().

Here is the caller graph for this function:

GWEN_Socket_GetSocketType()

GWENHYWFAR_API GWEN_SOCKETTYPE GWEN_Socket_GetSocketType

(

GWEN_SOCKET *

sp

)

Returns the socket type.

Parameters

sp

socket

References GWENHYWFAR_API.

Referenced by GWEN_SyncIo_Socket_TakeOver().

Here is the caller graph for this function:

GWEN_Socket_Listen()

GWENHYWFAR_API int GWEN_Socket_Listen	(	GWEN_SOCKET *	sp,
		int	backlog )

References GWENHYWFAR_API.

Referenced by _startListen().

Here is the caller graph for this function:

GWEN_Socket_new()

GWENHYWFAR_API GWEN_SOCKET * GWEN_Socket_new

(

GWEN_SOCKETTYPE

socketType

)

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

References GWENHYWFAR_API.

Referenced by _createAndSetupSocket(), _createAndSetupSocket(), and GWEN_SyncIo_Socket_Connect().

Here is the caller graph for this function:

GWEN_Socket_Open()

GWENHYWFAR_API int GWEN_Socket_Open

(

GWEN_SOCKET *

sp

)

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

References GWENHYWFAR_API.

Referenced by _createAndSetupSocket(), _createAndSetupSocket(), and GWEN_SyncIo_Socket_Connect().

Here is the caller graph for this function:

GWEN_Socket_Read()

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

Read bytes from a socket. This function might return GWEN_ERROR_INTERRUPTED in case the read request was interrupted by a posix signal or GWEN_ERROR_TIMEOUT on non-blocking sockets which have currently no data available.

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.

References GWENHYWFAR_API.

Referenced by GWEN_MsgEndpoint_ReadFromSocket(), and GWEN_SyncIo_Socket_Read().

Here is the caller graph for this function:

GWEN_Socket_ReadFrom()

GWENHYWFAR_API int 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.

References GWENHYWFAR_API.

GWEN_Socket_Select()

GWENHYWFAR_API int 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.

References GWENHYWFAR_API.

Referenced by GWEN_Gui_WaitForSockets(), GWEN_MsgEndpoint_ChildrenIoLoop(), and GWEN_MsgEndpoint_IoLoop().

Here is the caller graph for this function:

GWEN_Socket_SetBlocking()

GWENHYWFAR_API int 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

References GWENHYWFAR_API.

Referenced by _createAndSetupSocket(), and _createAndSetupSocket().

Here is the caller graph for this function:

GWEN_Socket_SetBroadcast()

GWENHYWFAR_API int 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

References GWENHYWFAR_API.

GWEN_Socket_SetReuseAddress()

GWENHYWFAR_API int 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

References GWENHYWFAR_API.

Referenced by _createAndSetupSocket().

Here is the caller graph for this function:

GWEN_Socket_SubFlags()

GWENHYWFAR_API void GWEN_Socket_SubFlags	(	GWEN_SOCKET *	sp,
		uint32_t	f )

References GWENHYWFAR_API.

GWEN_Socket_WaitForRead()

GWENHYWFAR_API int 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

References GWENHYWFAR_API.

Referenced by GWEN_SyncIo_Socket_Read().

Here is the caller graph for this function:

GWEN_Socket_WaitForWrite()

GWENHYWFAR_API int 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

Referenced by GWEN_SyncIo_Socket_Write().

Here is the caller graph for this function:

GWEN_Socket_Write()

GWENHYWFAR_API int 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!

References GWENHYWFAR_API.

Referenced by GWEN_MsgEndpoint_WriteToSocket(), and GWEN_SyncIo_Socket_Write().

Here is the caller graph for this function:

GWEN_Socket_WriteTo()

GWENHYWFAR_API int 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!