liblogging: sockets.h File Reference

Main Page | Compound List | File List | Compound Members | File Members | Related Pages

# 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.