/usr/include/gwenhywfar4/gwenhywfar/inetsocket.h is in libgwenhywfar-core-dev 4.20.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 | /***************************************************************************
$RCSfile$
-------------------
cvs : $Id$
begin : Tue Oct 02 2002
copyright : (C) 2002 by Martin Preuss
email : martin@libchipcard.de
***************************************************************************
* *
* This library is free software; you can redistribute it and/or *
* modify it under the terms of the GNU Lesser General Public *
* License as published by the Free Software Foundation; either *
* version 2.1 of the License, or (at your option) any later version. *
* *
* This library is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
* Lesser General Public License for more details. *
* *
* You should have received a copy of the GNU Lesser General Public *
* License along with this library; if not, write to the Free Software *
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, *
* MA 02111-1307 USA *
* *
***************************************************************************/
/**
* @file inetsocket.h
* @short This file contains sockets and socket sets.
*/
#ifndef GWEN_SOCKET_H
#define GWEN_SOCKET_H
#include <gwenhywfar/gwenhywfarapi.h>
#include <gwenhywfar/error.h>
#include <gwenhywfar/inetaddr.h>
#include <gwenhywfar/list1.h>
#include <gwenhywfar/list2.h>
typedef struct GWEN_SOCKET GWEN_SOCKET;
typedef struct GWEN_SOCKETSETSTRUCT GWEN_SOCKETSET;
GWEN_LIST_FUNCTION_LIB_DEFS(GWEN_SOCKET, GWEN_Socket, GWENHYWFAR_API)
GWEN_LIST2_FUNCTION_LIB_DEFS(GWEN_SOCKET, GWEN_Socket, GWENHYWFAR_API)
#ifdef __cplusplus
extern "C" {
#endif
/**
* @defgroup MOD_SOCKETSANDSETS Sockets and Socket Sets
* @ingroup MOD_OS
*
* This module handles sockets and socket sets.
* @{
*/
/** @name Error Codes */
/*@{*/
#define GWEN_SOCKET_ERROR_TYPE "Socket"
#define GWEN_SOCKET_ERROR_BAD_SOCKETTYPE (-1)
#define GWEN_SOCKET_ERROR_NOT_OPEN (-2)
#define GWEN_SOCKET_ERROR_TIMEOUT (-3)
#define GWEN_SOCKET_ERROR_IN_PROGRESS (-4)
#define GWEN_SOCKET_ERROR_STARTUP (-5)
#define GWEN_SOCKET_ERROR_INTERRUPTED (-6)
#define GWEN_SOCKET_ERROR_UNSUPPORTED (-7)
#define GWEN_SOCKET_ERROR_ABORTED (-8)
#define GWEN_SOCKET_ERROR_BROKEN_PIPE (-9)
/*@}*/
/**
* Socket types
*/
typedef enum {
GWEN_SocketTypeTCP=1,
GWEN_SocketTypeUDP,
GWEN_SocketTypeRAW,
GWEN_SocketTypeUnix,
GWEN_SocketTypeFile
}
GWEN_SOCKETTYPE;
/**
* @defgroup MOD_SOCKETSET Socket Set Functions
*
* These functions operate on socket sets. A socket set is used by the socket
* function @ref GWEN_Socket_Select() to check on which socket changes in state
* occurred.
* @{
*/
/**
* @name 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
* @ref GWEN_Socket_Select.
*/
/*@{*/
GWENHYWFAR_API GWEN_SOCKETSET *GWEN_SocketSet_new(void);
GWENHYWFAR_API void GWEN_SocketSet_free(GWEN_SOCKETSET *ssp);
GWENHYWFAR_API int GWEN_SocketSet_Clear(GWEN_SOCKETSET *ssp);
/*@}*/
/**
* @name 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
int GWEN_SocketSet_AddSocket(GWEN_SOCKETSET *ssp,
const GWEN_SOCKET *sp);
GWENHYWFAR_API
int GWEN_SocketSet_RemoveSocket(GWEN_SOCKETSET *ssp,
const GWEN_SOCKET *sp);
GWENHYWFAR_API int GWEN_SocketSet_HasSocket(GWEN_SOCKETSET *ssp,
const GWEN_SOCKET *sp);
GWENHYWFAR_API int GWEN_SocketSet_GetSocketCount(GWEN_SOCKETSET *ssp);
/*@}*/
/*end of group socketset */
/*@}*/
/**
* @defgroup MOD_SOCKET Socket Functions
*
* This group operates on IP sockets.
* @{
*/
/**
* @name Creation and Destruction
*/
/*@{*/
/**
* Constructor. You should always use this to create socket variables.
*/
GWENHYWFAR_API GWEN_SOCKET *GWEN_Socket_new(GWEN_SOCKETTYPE socketType);
GWENHYWFAR_API GWEN_SOCKET *GWEN_Socket_fromFile(int fd);
/**
* Destructor.
*/
GWENHYWFAR_API void GWEN_Socket_free(GWEN_SOCKET *sp);
/**
* Arms the socket so that it can be used. This really creates a system
* socket.
*/
GWENHYWFAR_API int GWEN_Socket_Open(GWEN_SOCKET *sp);
/**
* Unarms a socket thus closing any connection associated with this socket.
*/
GWENHYWFAR_API int GWEN_Socket_Close(GWEN_SOCKET *sp);
/*@}*/
/**
* @name 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);
/**
* This accepts a new connection on the given socket. This socket must be
* listening (achieved by calling @ref GWEN_Socket_Listen).
* @param sp socket which is listening
* @param 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 !
* @param 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
int GWEN_Socket_Accept(GWEN_SOCKET *sp,
GWEN_INETADDRESS **addr,
GWEN_SOCKET **newsock);
/*@}*/
/**
* @name Informational Functions
*
* These functions return some usefull information about sockets or
* connections.
*/
/*@{*/
/**
* Returns the socket type.
* @param sp socket
*/
GWENHYWFAR_API GWEN_SOCKETTYPE GWEN_Socket_GetSocketType(GWEN_SOCKET *sp);
/**
* Retrieves the peer's address
* @param sp socket
* @param addr pointer to a pointer to an @ref 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
int GWEN_Socket_GetPeerAddr(GWEN_SOCKET *sp,
GWEN_INETADDRESS **addr);
/**
* This function waits for a group of sockets to change their state.
* @param rs socket set, wait for readability of those sockets
* @param ws socket set, wait for writeability of those sockets
* @param xs socket set, wait for "exceptional events" on those sockets
* @param 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
int GWEN_Socket_Select(GWEN_SOCKETSET *rs,
GWEN_SOCKETSET *ws,
GWEN_SOCKETSET *xs,
int timeout);
/**
* Wait until the given socket becomes readable or a timeout occurrs.
* @param sp socket
* @param timeout please see @ref GWEN_Socket_Select for details
*/
GWENHYWFAR_API
int GWEN_Socket_WaitForRead(GWEN_SOCKET *sp, int timeout);
/**
* Wait until the given socket becomes writeable or a timeout occurrs.
* @param sp socket
* @param timeout please see @ref GWEN_Socket_Select for details
*/
GWENHYWFAR_API
int GWEN_Socket_WaitForWrite(GWEN_SOCKET *sp, int timeout);
/*@}*/
/**
* @name Data Exchange Functions
*
* These functions handle exchange of data with other hosts via the Internet
* Protocol.
*/
/*@{*/
/**
* 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.
* @param sp socket
* @param buffer pointer to the buffer to receive the data
* @param 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 int GWEN_Socket_Read(GWEN_SOCKET *sp,
char *buffer,
int *bsize);
/**
* Write bytes to an open socket.
* @param sp socket
* @param buffer pointer to a buffer containing the bytes to be written
* @param 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 int GWEN_Socket_Write(GWEN_SOCKET *sp,
const char *buffer,
int *bsize);
/**
* Reads bytes from an UDP socket, which is connectionless.
* @param sp socket
* @param 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 !
* @param buffer pointer to a buffer to store the received data in
* @param 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
int GWEN_Socket_ReadFrom(GWEN_SOCKET *sp,
GWEN_INETADDRESS **addr,
char *buffer,
int *bsize);
/**
* Writes data to an UDP socket, which is connectionless.
* @param sp socket
* @param addr pointer to the address struct specifying the recipient
* @param buffer pointer to a buffer containing the bytes to be written
* @param 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
int GWEN_Socket_WriteTo(GWEN_SOCKET *sp,
const GWEN_INETADDRESS *addr,
const char *buffer,
int *bsize);
/*@}*/
/**
* @name Socket Settings Functions
*
* These functions manipulate settings on a socket.
*/
/*@{*/
/**
* Toggles the sockets blocking/non-blocking mode.
* @param sp socket
* @param fl if 0 then nonblocking is requested, otherwise blocking is assumed
*/
GWENHYWFAR_API int GWEN_Socket_SetBlocking(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.
* @param sp socket
* @param fl if nonzero then broadcast is enabled
*/
GWENHYWFAR_API int GWEN_Socket_SetBroadcast(GWEN_SOCKET *sp, int fl);
/**
* 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 ;-)
* @param sp socket
*/
GWENHYWFAR_API int GWEN_Socket_GetSocketError(GWEN_SOCKET *sp);
/**
* 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.
* @param sp socket
* @param fl if nonzero then reusing the address is enabled
*/
GWENHYWFAR_API
int GWEN_Socket_SetReuseAddress(GWEN_SOCKET *sp, int fl);
/*@}*/
/**
* This function should only be used if it is absolutely necessary,
* because it might not be supported by every system.
* Hoever, 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().
*/
GWENHYWFAR_API
int GWEN_Socket_GetSocketInt(const GWEN_SOCKET *sp);
/* end of group socket */
/*@}*/
/* end of group socketsandsets */
/*@}*/
#ifdef __cplusplus
}
#endif
#endif /* GWEN_SOCKET_H */
|