sockets.h File Reference

socket layer for slim beep More...

#include "config.h"
#include <sys/types.h>
#include <sys/time.h>
#include <sys/socket.h>
#include <sys/select.h>
#include <unistd.h>
#include <netinet/in.h>
#include <netdb.h>
#include <errno.h>

Go to the source code of this file.

Compounds
struct	sbSockObject
	The socket object. More...
Defines
#define	__LIB3195_SOCKETS_H_INCLUDED__   1
#define	sbSockCHECKVALIDOBJECT(x)   {assert(x != NULL); assert(x->OID == OIDsbSock);}
#define	sbSOCK_NO_CHAR   -1
	The value to return when no character could be read by a socket recv call.
#define	sbSockGetLastError(pThis)   pThis->iLastErr
	Getthe last error for this module.
#define	sbSockSetLastError(pThis, iRet)   pThis->iLastErr = iRet
	Set the last error for this module.
#define	sbSockResetLastError(pThis)   pThis->iLastErr = SR_RET_OK
	reset the last error for this module
#define	sbSockFD_ZERO(fdset)   FD_ZERO(fdset)
	wrapper for the FD_ZERO macro.
#define	sbSockFD_SET(sock, fdset)   FD_SET(sock, fdset)
	Wrapper for the FD_SET macro.
#define	sbSockFD_ISSET(sock, fdset)   FD_ISSET(sock, fdset)
	Wrapper for the FD_ISSET macro.
#define	SBSOCK_EWOULDBLOCK   EWOULDBLOCK
#define	SOCKET_ERROR   -1
Typedefs
typedef sbSockObject	sbSockObj
typedef fd_set	srSock_fd_set
	Wrapper for the fd_set data structure.
Functions
srRetVal	sbSockLayerInit (int bInitOSStack)
	Global Layer initialization.
srRetVal	sbSockLayerExit (int bExitOSStack)
	Global Layer destructor.
sbSockObj *	sbSockInit (void)
	Constructor for STREAM sockets, only.
sbSockObj *	sbSockInitEx (int af, int iSockType)
	Alternate Constructur.
srRetVal	sbSockExit (sbSockObj *)
	Destructor.
int	sbSockGetLastSockError (sbSockObj *)
	get last error code
srRetVal	sbSockConnectoToHost (sbSockObj *pThis, char *pszHost, int iPort)
	Connect a socket to a remote host.
int	sbSockHasReceiveData (sbSockObj *pThis)
	Check if the socket has data ready to be received.
int	sbSockReceive (sbSockObj *pThis, char *pszBuf, int iLen)
	Receive data from the socket.
int	sbSockSend (sbSockObj *pThis, const char *pszBuf, int iLen)
	Send the supplied buffer.
int	sbSockGetRcvChar (sbSockObj *pThis)
	Read the next character from the stream.
int	sbSockPeekRcvChar (sbSockObj *pThis)
	Peek at the next character from the stream.
srRetVal	sbSockClosesocket (sbSockObj *pThis)
	Close a socket.
srRetVal	sbSockWaitReceiveData (struct sbSockObject *pThis)
	Wait until the socket has some receive data.
int	sbSockSelectMulti (srSock_fd_set *fdsetRD, srSock_fd_set *fdsetWR, int iTimOutSecs, int iTimOutMSecs, int iHighestDesc)
	Wrapper for the socket select call on a fd_set structure.
srRetVal	sbSockListen (sbSockObj *pThis)
	Wrapper for the socket listen() call.
sbSockObj *	sbSockInitListenSock (srRetVal *iRet, int iType, char *szBindToAddress, unsigned uBindToPort)
	Initialize a listen socket.
srRetVal	sbSockAcceptConnection (sbSockObj *pThis, sbSockObj **pNew)
	This method accepts an incoming connection and creates a new socket object out of it.
srRetVal	sbSockSetNonblocking (sbSockObj *pThis)
	Set the socket to nonblocking state.
srRetVal	sbSockGetRemoteHostIP (sbSockObj *pThis, char **ppszHost)
	Return the IP Address of the remote host as a string.
srRetVal	sbSock_gethostname (char **psz)
	Wrapper for gethostname().
srRetVal	sbSockGetIPusedForSending (sbSockObj *pThis, char **ppsz)
	Provide the (local) IP address this session is sending to the remote peer on as a string.
srRetVal	sbSockRecvFrom (sbSockObj *pThis, char *pRecvBuf, int *piBufLen, char **ppFrom)
	Enhanced recvfrom() clone.

---

Detailed Description

socket layer for slim beep

This implements a very thin layer above the socket subsystem. If you intend to port the lib to a different environment, you should probably stick with that layer and create a new socketsXXX.c file.

The prefix for this file is sbSock.

All methods receive a pointer to their "object instance" as the first parameter.

Author:

Rainer Gerhards <rgerhards@adiscon.com>

Date:

2003-08-04 0.1 version created.

Copyright 2002-2003 Rainer Gerhards and Adiscon GmbH. All Rights Reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of Adiscon GmbH or Rainer Gerhards nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---

Define Documentation

#define sbSockFD_ISSET (  sock, fdset   )     FD_ISSET(sock, fdset)

Wrapper for the FD_ISSET macro. This may not work on every exotic OS, but it gives at least a small hook to porting it... Semantics are as with the original FD_ZERO.

#define sbSockFD_SET (  sock, fdset   )     FD_SET(sock, fdset)

Wrapper for the FD_SET macro. This may not work on every exotic OS, but it gives at least a small hook to porting it... Semantics are as with the original FD_ZERO.

#define sbSockFD_ZERO (  fdset   )     FD_ZERO(fdset)

wrapper for the FD_ZERO macro. This may not work on every exotic OS, but it gives at least a small hook to porting it... Semantics are as with the original FD_ZERO.

---

Function Documentation

srRetVal sbSock_gethostname (  char **  psz  )

Wrapper for gethostname(). Note: The Windows sockets API seems to be broken. We often have seen that only the computer name part (not the domain name) is returned by gethostname, even if the full identity is configured. A way to work around this may be to call gethostbyname() on the returned name and then call gethostbyaddr() on what is returned there. WE HAVE NOW IMPLEMENTED THIS WORKAROUND, but leave the text above in just in case... Parameters: psz  Pointer to Pointer to hostname. Must not be NULL. On return, this pointer will refer to a newly allocated buffer containing the hostname. This buffer must be free()ed by the caller!

srRetVal sbSockConnectoToHost (  sbSockObj *  pThis, char *  pszHost, int  iPort )

Connect a socket to a remote host. Parameters: pszHost  Name or IP address of host to connect to iPort  Port to connect to

srRetVal sbSockGetIPusedForSending (  sbSockObj *  pThis, char **  ppsz )

Provide the (local) IP address this session is sending to the remote peer on as a string. OK, the short description is probably not very well ;) What it does is, it looks up the local IP address that is used to talk to the remote Peer. This is especially important on multihomed machines, as different interfaces can be used to forward data (depending on which one is closest to the recipient). Then, it formats this as an IP Address string that then is handed back to the caller. Please note: the socket MUST be connected before you can use this method! It should NOT be used on UDP sockets. Parameters: ppsz  Pointer to a char* that will receive the IP string. The caller must free the returned pointer when he is done. The provided pointer must not be NULL.

int sbSockGetLastSockError (  sbSockObj *   )

get last error code Return values: last  error code (OS specific)

int sbSockGetRcvChar (  sbSockObj *  pThis  )

Read the next character from the stream. The character is removed from the stream. If no data is ready on the stream, a blocking read is carried out. So this function can block! Return values: character  read

srRetVal sbSockGetRemoteHostIP (  sbSockObj *  pThis, char **  ppszHost )

Return the IP Address of the remote host as a string. The caller must free the returned string.

int sbSockHasReceiveData (  sbSockObj *  pThis  )

Check if the socket has data ready to be received. Return values: TRUE  if data is ready, FALSE otherwise. The return value is only valid if no error occured. To make your app bullet-proof, you need to check the error indicator before using the retval... ;)

sbSockObj* sbSockInit (  void   )

Constructor for STREAM sockets, only. Return values: Returns  a pointer to the new instance or NULL, if it could not be created.

sbSockObj* sbSockInitEx (  int  af, int  iSockType )

Alternate Constructur. Socket TYPE (STREAM/DGRAM) can be specified

sbSockObj* sbSockInitListenSock (  srRetVal *  iRet, int  iType, char *  szBindToAddress, unsigned  uBindToPort )

Initialize a listen socket. This includes everything so that the next call can be listen(). Parameters: iRet  [out] Pointer to a variable holding the return code of this operation. Has the error code if initialisation failed. iType  sockets type to be used. Must be either SOCK_STREAM or SOCK_DGRAM. szBindToAdresse  string with IP address to which the socket should be bound. If NULL, do not bind to any specific address. iBindToPort  Port the socket should be bound to. For listening sockets, this is the port that the remote peer will to connect to. Return values: Pointer  to newly created socket or NULL, if an error occured. In case of NULL, the caller can examine the socket error code to learn the error cause.

srRetVal sbSockLayerExit (  int  bExitOSStack  )

Global Layer destructor. Call this only once at the end of the application. All sockets must be destroyed before calling this method. Parameters: bExitOSStack  Specifies if the library should shut down the operating system socket stack. If 1, it shuts it down, if 0, it does not. Set this to 0 if you integrate this lib into an app that otherwise shuts down the OS socket lib itself.

srRetVal sbSockLayerInit (  int  bInitOSStack  )

Global Layer initialization. Should be called only once per application. This will do all housekeeping necessary to use the layer. DO NOT CALL ANY OTHER METHODS BEFORE THIS ONE HAS BEEN CALLED! They will probably fail! Parameters: bInitOSStack  Specifies if the library should initialize the operating system socket stack. If 1, it initializes it, if 0, it does not. Set this to 0 if you integrate this lib into an app that otherwise initializes the socket lib itself.

int sbSockPeekRcvChar (  sbSockObj *  pThis  )

Peek at the next character from the stream. The character is NOT removed from the stream. If no data is ready on the stream, a blocking read is carried out. So this function can block! Return values: character  read

int sbSockReceive (  sbSockObj *  pThis, char *  pszBuf, int  iLen )

Receive data from the socket. This is done in a blocking way. If you would not like to block, call sbSockHasReceiveData before calling this method. Parameters: *pszBuf  [in] - data to be send iLen  [in] - length of pszBuf Return values: actual  bytes sent by socket subsystem

srRetVal sbSockRecvFrom (  sbSockObj *  pThis, char *  pRecvBuf, int *  piBufLen, char **  ppFrom )

Enhanced recvfrom() clone. Will receive an C sz String. That is, any received as part of the string will be replaced by ABNF SP (' '). Parameters: pRecvBuf  Pointer to buffer that will receive the incoming data. piBufLen  On entry, the size of the buffer pointed to by pRecvBuf. On exit, the number of bytes received ppFrom  Pointer to a char pointer that will receive a string with the senders' IP address. This buffer MUST be free()ed by the caller! Todo: handle the connection closed case (*piBuflen == 0)

int sbSockSelectMulti (  srSock_fd_set *  fdsetRD, srSock_fd_set *  fdsetWR, int  iTimOutSecs, int  iTimOutMSecs, int  iHighestDesc )

Wrapper for the socket select call on a fd_set structure. Parameters: iTimOutSecs  Seconds until timeout. -1 means indefinite blocking. iTimOutMSecs  Milliseconds until timeout. iHighestDesc  [*NIX ONLY!] The highest file descriptor in any of the fd_sets. Return values: Value  returned by select.

int sbSockSend (  sbSockObj *  pThis, const char *  pszBuf, int  iLen )

Send the supplied buffer. Parameters: *pszBuf  [in] - data to be sent. If NULL, no data is sent (but NULL is a VALID value for this param!). iLen  [in] - number of bytes to send Return values: number  of bytes actually sent

srRetVal sbSockWaitReceiveData (  struct sbSockObject *  pThis  )

Wait until the socket has some receive data. This is a blocking call.

---