include/osl/socket.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_OSL_SOCKET_H
  21 #define INCLUDED_OSL_SOCKET_H
  22
  23 #include <rtl/ustring.h>
  24 #include <rtl/byteseq.h>
  25
  26 #include <osl/time.h>
  27 #include <rtl/tencinfo.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /* error returns */
  34 #define OSL_INADDR_NONE             0xffffffff
  35 #define OSL_INVALID_PORT (-1)
  36 #define OSL_INVALID_IPX_SOCKET_NO   0xffffffff
  37
  38 /**
  39     Opaque datatype SocketAddr.
  40 */
  41 typedef struct oslSocketAddrImpl * oslSocketAddr;
  42
  43
  44 /**
  45     Represents the address-family of a socket
  46 */
  47 typedef enum {
  48     osl_Socket_FamilyInet,      /* IP */
  49     osl_Socket_FamilyIpx,       /* Novell IPX/SPX */
  50     osl_Socket_FamilyInvalid,   /* always last entry in enum! */
  51     osl_Socket_Family_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  52 } oslAddrFamily;
  53
  54 /**
  55     represent a specific protocol within a address-family
  56 */
  57 typedef enum {
  58     osl_Socket_ProtocolIp,      /* for all af_inet */
  59     osl_Socket_ProtocolIpx,     /* af_ipx datagram sockets (IPX) */
  60     osl_Socket_ProtocolSpx,     /* af_ipx seqpacket or stream for SPX */
  61     osl_Socket_ProtocolSpxII,   /* af_ipx seqpacket or stream for SPX II */
  62     osl_Socket_ProtocolInvalid,
  63     osl_Socket_Protocol_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  64 } oslProtocol;
  65
  66
  67 /**
  68     Represents the type of a socket
  69 */
  70 typedef enum {
  71     osl_Socket_TypeStream,
  72     osl_Socket_TypeDgram,
  73     osl_Socket_TypeRaw,
  74     osl_Socket_TypeRdm,
  75     osl_Socket_TypeSeqPacket,
  76     osl_Socket_TypeInvalid,     /* always last entry in enum! */
  77     osl_Socket_Type_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
  78 } oslSocketType;
  79
  80
  81 /**
  82     Represents socket-options
  83 */
  84 typedef enum {
  85     osl_Socket_OptionDebug,
  86     osl_Socket_OptionAcceptConn,
  87     osl_Socket_OptionReuseAddr,
  88     osl_Socket_OptionKeepAlive,
  89     osl_Socket_OptionDontRoute,
  90     osl_Socket_OptionBroadcast,
  91     osl_Socket_OptionUseLoopback,
  92     osl_Socket_OptionLinger,
  93     osl_Socket_OptionOOBinLine,
  94     osl_Socket_OptionSndBuf,
  95     osl_Socket_OptionRcvBuf,
  96     osl_Socket_OptionSndLowat,
  97     osl_Socket_OptionRcvLowat,
  98     osl_Socket_OptionSndTimeo,
  99     osl_Socket_OptionRcvTimeo,
 100     osl_Socket_OptionError,
 101     osl_Socket_OptionType,
 102     osl_Socket_OptionTcpNoDelay,
 103     osl_Socket_OptionInvalid,       /* always last entry in enum! */
 104     osl_Socket_Option_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 105 } oslSocketOption;
 106
 107 /**
 108     Represents the different socket-option levels
 109 */
 110 typedef enum  {
 111     osl_Socket_LevelSocket,
 112     osl_Socket_LevelTcp,
 113     osl_Socket_LevelInvalid,            /* always last entry in enum! */
 114     osl_Socket_Level_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 115 } oslSocketOptionLevel;
 116
 117
 118 /**
 119     Represents flags to be used with send/recv-calls.
 120 */
 121 typedef enum {
 122     osl_Socket_MsgNormal,
 123     osl_Socket_MsgOOB,
 124     osl_Socket_MsgPeek,
 125     osl_Socket_MsgDontRoute,
 126     osl_Socket_MsgMaxIOVLen,
 127     osl_Socket_MsgInvalid,          /* always last entry in enum! */
 128     osl_Socket_Msg_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 129 } oslSocketMsgFlag;
 130
 131 /**
 132     Used by shutdown to denote which end of the socket to "close".
 133 */
 134 typedef enum {
 135     osl_Socket_DirRead,
 136     osl_Socket_DirWrite,
 137     osl_Socket_DirReadWrite,
 138     osl_Socket_DirInvalid,          /* always last entry in enum! */
 139     osl_Socket_Dir_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 140 } oslSocketDirection;
 141
 142 /** Describes the various error socket error conditions, which may
 143     occur */
 144 typedef enum {
 145     osl_Socket_E_None,              /* no error */
 146     osl_Socket_E_NotSocket,         /* Socket operation on non-socket */
 147     osl_Socket_E_DestAddrReq,       /* Destination address required */
 148     osl_Socket_E_MsgSize,           /* Message too long */
 149     osl_Socket_E_Prototype,         /* Protocol wrong type for socket */
 150     osl_Socket_E_NoProtocol,        /* Protocol not available */
 151     osl_Socket_E_ProtocolNoSupport, /* Protocol not supported */
 152     osl_Socket_E_TypeNoSupport,     /* Socket type not supported */
 153     osl_Socket_E_OpNotSupport,      /* Operation not supported on socket */
 154     osl_Socket_E_PfNoSupport,       /* Protocol family not supported */
 155     osl_Socket_E_AfNoSupport,       /* Address family not supported by */
 156                                     /* protocol family */
 157     osl_Socket_E_AddrInUse,         /* Address already in use */
 158     osl_Socket_E_AddrNotAvail,      /* Can't assign requested address */
 159     osl_Socket_E_NetDown,           /* Network is down */
 160     osl_Socket_E_NetUnreachable,    /* Network is unreachable */
 161     osl_Socket_E_NetReset,          /* Network dropped connection because */
 162                                     /* of reset */
 163     osl_Socket_E_ConnAborted,       /* Software caused connection abort */
 164     osl_Socket_E_ConnReset,         /* Connection reset by peer */
 165     osl_Socket_E_NoBufferSpace,     /* No buffer space available */
 166     osl_Socket_E_IsConnected,       /* Socket is already connected */
 167     osl_Socket_E_NotConnected,      /* Socket is not connected */
 168     osl_Socket_E_Shutdown,          /* Can't send after socket shutdown */
 169     osl_Socket_E_TooManyRefs,       /* Too many references: can't splice */
 170     osl_Socket_E_TimedOut,          /* Connection timed out */
 171     osl_Socket_E_ConnRefused,       /* Connection refused */
 172     osl_Socket_E_HostDown,          /* Host is down */
 173     osl_Socket_E_HostUnreachable,   /* No route to host */
 174     osl_Socket_E_WouldBlock,        /* call would block on non-blocking socket */
 175     osl_Socket_E_Already,           /* operation already in progress */
 176     osl_Socket_E_InProgress,        /* operation now in progress */
 177     osl_Socket_E_InvalidError,      /* unmapped error: always last entry in enum! */
 178     osl_Socket_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 179 } oslSocketError;
 180
 181 /** Common return codes of socket related functions.
 182  */
 183 typedef enum {
 184     osl_Socket_Ok,          /* successful completion */
 185     osl_Socket_Error,       /* error occurred, check osl_getLastSocketError() for details */
 186     osl_Socket_TimedOut,    /* blocking operation timed out */
 187     osl_Socket_Interrupted, /* blocking operation was interrupted */
 188     osl_Socket_InProgress,  /* nonblocking operation is in progress */
 189     osl_Socket_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 190 } oslSocketResult;
 191
 192 typedef sal_uInt8 oslSocketIpxNetNumber[4];
 193 typedef sal_uInt8 oslSocketIpxNodeNumber[6];
 194
 195 /**@} end section types
 196 */
 197
 198 /**@{ begin section oslSocketAddr
 199 */
 200
 201 /** Creates a socket-address for the given family.
 202     @param Family If family == osl_Socket_FamilyInet the address is
 203                   set to INADDR_ANY port 0.
 204     @return 0 if address could not be created.
 205 */
 206 SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createEmptySocketAddr(
 207         oslAddrFamily Family);
 208
 209
 210 /** Creates a new SocketAddress and fills it from Addr.
 211 */
 212 SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_copySocketAddr(
 213         oslSocketAddr Addr);
 214
 215 /** Compares the values of two SocketAddresses.
 216     @return <code>sal_True</code> if both addresses denote the same socket address,
 217             <code>sal_False</code> otherwise.
 218 */
 219 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isEqualSocketAddr(
 220     oslSocketAddr Addr1, oslSocketAddr Addr2);
 221
 222 /** Uses the systems name-service interface to find an address for strHostname.
 223     @param[in] strHostname The name for which you search for an address.
 224     @return The desired address if one could be found, otherwise 0.
 225     Don't forget to destroy the address if you don't need it any longer.
 226 */
 227 SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_resolveHostname(
 228         rtl_uString *strHostname);
 229
 230 /** Create an internet address usable for sending broadcast datagrams.
 231     To limit the broadcast to your subnet, pass your hosts IP address
 232     in dotted decimal notation as first argument.
 233     @see    osl_sendToSocket()
 234     @see    oslSocketAddr
 235     @param[in]  strDottedAddr dotted decimal internet address, may be 0.
 236     @param[in]  Port port number in host byte order.
 237     @return 0 if address could not be created.
 238 */
 239 SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createInetBroadcastAddr (
 240     rtl_uString *strDottedAddr, sal_Int32 Port);
 241
 242
 243 /** Create an internet-address, consisting of hostaddress and port.
 244     We interpret strDottedAddr as a dotted-decimal inet-addr
 245     (e.g. "141.99.128.50").
 246     @param strDottedAddr [in] String with dotted address.
 247     @param Port [in] portnumber in host byte order.
 248     @return 0 if address could not be created.
 249 */
 250 SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createInetSocketAddr (
 251     rtl_uString *strDottedAddr, sal_Int32 Port);
 252
 253
 254 /** Frees all resources allocated by Addr. The handle Addr must not
 255     be used after the call anymore.
 256 */
 257 SAL_DLLPUBLIC void SAL_CALL osl_destroySocketAddr(
 258         oslSocketAddr Addr);
 259
 260 /** Looks up the port-number designated to the specified service/protocol-pair.
 261     (e.g. "ftp" "tcp").
 262     @return OSL_INVALID_PORT if no appropriate entry was found, otherwise the port-number.
 263 */
 264 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getServicePort(
 265         rtl_uString *strServicename, rtl_uString *strProtocol);
 266
 267
 268
 269 /** Retrieves the address-family from the Addr.
 270     @return the family of the socket-address.
 271     In case of an unknown family you get <code>osl_Socket_FamilyInvalid</code>.
 272 */
 273 SAL_DLLPUBLIC oslAddrFamily SAL_CALL osl_getFamilyOfSocketAddr(
 274         oslSocketAddr Addr);
 275
 276
 277 /** Retrieves the internet port-number of Addr.
 278     @return the port-number of the address in host-byte order. If Addr
 279     is not an address of type <code>osl_Socket_FamilyInet</code>, it returns <code>OSL_INVALID_PORT</code>
 280 */
 281 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getInetPortOfSocketAddr(
 282         oslSocketAddr Addr);
 283
 284
 285 /** Sets the Port of Addr.
 286     @param[in] Addr the SocketAddr to perfom the operation on.
 287     @param[in] Port is expected in host byte-order.
 288     @return <code>sal_False</code> if Addr is not an inet-addr.
 289 */
 290 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setInetPortOfSocketAddr(
 291         oslSocketAddr Addr, sal_Int32 Port);
 292
 293
 294 /** Returns the hostname represented by Addr.
 295     @param[in] Addr The socket address from which to extract the hostname.
 296     @param[out] strHostname The hostname represented by the address. If
 297     there is no hostname to be found, it returns 0.
 298 */
 299 SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getHostnameOfSocketAddr(
 300         oslSocketAddr Addr, rtl_uString **strHostname);
 301
 302
 303 /** Gets the address in dotted decimal format.
 304     @param[in] Addr The socket address from which to extract the dotted decimal address.
 305     @param[out] strDottedInetAddr Contains the dotted decimal address
 306     (e.g. 141.99.20.34) represented by the address.
 307     If the address is invalid or not of type <code>osl_Socket_FamilyInet</code>,
 308     it returns 0.
 309     @return <code>osl_Socket_Ok</code> or <code>osl_Socket_Error</code>
 310 */
 311 SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getDottedInetAddrOfSocketAddr(
 312         oslSocketAddr Addr, rtl_uString **strDottedInetAddr);
 313
 314 /** Sets the addr field in the struct sockaddr with pByteSeq. pByteSeq must be in network byte order.
 315  */
 316 SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_setAddrOfSocketAddr(
 317         oslSocketAddr Addr, sal_Sequence *pByteSeq );
 318
 319 /** Returns the addr field in the struct sockaddr.
 320     @param[in] Addr The socket address from which to extract the ipaddress.
 321     @param[out] ppByteSeq After the call, *ppByteSeq contains the ipaddress
 322                      in network byteorder. *ppByteSeq may be 0 in case of an invalid socket handle.
 323     @return <code>osl_Socket_Ok</code> or <code>osl_Socket_Error</code>
 324  */
 325 SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getAddrOfSocketAddr(
 326         oslSocketAddr Addr, sal_Sequence **ppByteSeq );
 327
 328 /*
 329     Opaque datatype HostAddr.
 330 */
 331 typedef struct oslHostAddrImpl * oslHostAddr;
 332
 333
 334 /** Create an oslHostAddr from given hostname and socket address.
 335     @param[in] strHostname The hostname to be stored.
 336     @param[in] Addr The socket address to be stored.
 337     @return The created address or 0 upon failure.
 338 */
 339 SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddr(
 340         rtl_uString *strHostname, const oslSocketAddr Addr);
 341
 342
 343 /** Create an oslHostAddr by resolving the given strHostname.
 344     Successful name resolution should result in the fully qualified
 345     domain name (FQDN) and it's address as hostname and socket address
 346     members of the resulting oslHostAddr.
 347     @param[in] strHostname The hostname to be resolved.
 348     @return The resulting address or 0 upon failure.
 349 */
 350 SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddrByName(rtl_uString *strHostname);
 351
 352
 353 /** Create an oslHostAddr by reverse resolution of the given Addr.
 354     Successful name resolution should result in the fully qualified
 355     domain name (FQDN) and it's address as hostname and socket address
 356     members of the resulting oslHostAddr.
 357     @param[in] Addr The socket address to be reverse resolved.
 358     @return The resulting address or 0 upon failure.
 359 */
 360 SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddrByAddr(const oslSocketAddr Addr);
 361
 362
 363 /** Create a copy of the given Addr.
 364     @return The copied address or 0 upon failure.
 365 */
 366 SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_copyHostAddr(const oslHostAddr Addr);
 367
 368
 369 /** Frees all resources allocated by Addr. The handle Addr must not
 370     be used after the call anymore.
 371 */
 372 SAL_DLLPUBLIC void SAL_CALL osl_destroyHostAddr(oslHostAddr Addr);
 373
 374
 375 /** Get the hostname member of Addr.
 376     @return The hostname or 0 upon failure.
 377 */
 378 SAL_DLLPUBLIC void SAL_CALL osl_getHostnameOfHostAddr(const oslHostAddr Addr, rtl_uString **strHostname);
 379
 380
 381 /** Get the socket address member of Addr.
 382     @return The socket address or 0 upon failure.
 383 */
 384 SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getSocketAddrOfHostAddr(const oslHostAddr Addr);
 385
 386 /** Retrieve this machines hostname.
 387     May not always be a fully qualified domain name (FQDN).
 388     @param  strLocalHostname out-parameter. The string that receives the local host name.
 389     @return <code>sal_True</code> upon success, <code>sal_False</code> otherwise.
 390 */
 391 SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getLocalHostname(rtl_uString **strLocalHostname);
 392
 393
 394 /**@} end section oslHostAddr
 395 */
 396
 397 /**@{ begin section oslSocket
 398 */
 399
 400
 401 /*-***************************************************************************/
 402 /* oslSocket */
 403 /*-***************************************************************************/
 404
 405 typedef struct oslSocketImpl * oslSocket;
 406
 407 /** increases the refcount of the socket handle by one
 408  */
 409 SAL_DLLPUBLIC void SAL_CALL osl_acquireSocket( oslSocket Socket );
 410
 411 /** decreases the refcount of the socket handle by one.
 412
 413     If the refcount drops to zero, the underlying socket handle
 414     is destroyed and becomes invalid.
 415  */
 416 SAL_DLLPUBLIC void SAL_CALL osl_releaseSocket( oslSocket Socket );
 417
 418 /** Create a socket of the specified Family and Type. The semantic of
 419     the Protocol parameter depends on the given family and type.
 420     @return 0 if socket could not be created, otherwise you get a handle
 421     to the allocated socket-datastructure.
 422 */
 423 SAL_DLLPUBLIC oslSocket SAL_CALL osl_createSocket(
 424                                     oslAddrFamily   Family,
 425                                     oslSocketType   Type,
 426                                     oslProtocol     Protocol);
 427
 428 /** Retrieves the Address of the local end of the socket.
 429     Note that a socket must be bound or connected before
 430     a vaild address can be returned.
 431     @return 0 if socket-address could not be created, otherwise you get
 432     the created Socket-Address.
 433 */
 434 SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getLocalAddrOfSocket(oslSocket Socket);
 435
 436 /** Retrieves the Address of the remote end of the socket.
 437     Note that a socket must be connected before
 438     a vaild address can be returned.
 439     @return 0 if socket-address could not be created, otherwise you get
 440     the created Socket-Address.
 441 */
 442 SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getPeerAddrOfSocket(oslSocket Socket);
 443
 444 /** Binds the given address to the socket.
 445     @param[in] Socket
 446     @param[in] Addr
 447     @return <code>sal_False</code> if the bind failed, <code> sal_True</code> if successful.
 448     @see osl_getLastSocketError()
 449 */
 450 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_bindAddrToSocket(
 451                                        oslSocket Socket,
 452                                        oslSocketAddr Addr);
 453
 454 /** Connects the socket to the given address.
 455
 456     @param[in] Socket a bound socket.
 457     @param[in] Addr the peer address.
 458     @param pTimeout Timeout value or NULL for blocking.
 459
 460     @return <code>osl_Socket_Ok</code> on successful connection,
 461             <code>osl_Socket_TimedOut</code> if operation timed out,
 462             <code>osl_Socket_Interrupted</code> if operation was interrupted
 463             <code>osl_Socket_Error</code> if the connection failed.
 464 */
 465 SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_connectSocketTo(
 466                                         oslSocket Socket,
 467                                         oslSocketAddr Addr,
 468                                         const TimeValue* pTimeout);
 469
 470
 471 /** Prepares the socket to act as an acceptor of incoming connections.
 472     You should call "listen" before you use "accept".
 473     @param[in] Socket The socket to listen on.
 474     @param[in] MaxPendingConnections denotes the length of the queue of
 475     pending connections for this socket. If MaxPendingConnections is
 476     -1, the systems default value will be used (Usually 5).
 477     @return <code>sal_False</code> if the listen failed.
 478 */
 479 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_listenOnSocket(
 480                            oslSocket Socket,
 481                            sal_Int32 MaxPendingConnections);
 482
 483
 484 /** Waits for an ingoing connection on the socket.
 485     This call blocks if there is no incoming connection present.
 486     @param[in] Socket The socket to accept the connection on.
 487     @param[in] pAddr if pAddr is != 0, the peers address is returned.
 488     @return 0 if the accept-call failed, otherwise you get a socket
 489     representing the new connection.
 490 */
 491 SAL_DLLPUBLIC oslSocket SAL_CALL osl_acceptConnectionOnSocket
 492                                        (oslSocket Socket,
 493                                        oslSocketAddr* pAddr);
 494
 495 /** Tries to receive BytesToRead data from the connected socket,
 496     if no error occurs. Note that incomplete recvs due to
 497     packet boundaries may occur.
 498
 499     @param[in] Socket A connected socket to be used to listen on.
 500     @param[out] pBuffer Points to a buffer that will be filled with the received
 501     data.
 502     @param[in] BytesToRead The number of bytes to read. pBuffer must have at least
 503     this size.
 504     @param[in] Flag Modifier for the call. Valid values are:
 505     <ul>
 506     <li><code>osl_Socket_MsgNormal</code>
 507     <li><code>osl_Socket_MsgOOB</code>
 508     <li><code>osl_Socket_MsgPeek</code>
 509     <li><code>osl_Socket_MsgDontRoute</code>
 510     <li><code>osl_Socket_MsgMaxIOVLen</code>
 511     </ul>
 512
 513     @return the number of received bytes.
 514 */
 515 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_receiveSocket(
 516                           oslSocket Socket,
 517                           void* pBuffer,
 518                            sal_uInt32 BytesToRead,
 519                           oslSocketMsgFlag Flag);
 520
 521 /** Tries to receives BufferSize data from the (usually unconnected)
 522     (datagram-)socket, if no error occurs.
 523
 524     @param[in] Socket A bound socket to be used to listen for a datagram.
 525     @param[out] SenderAddr A pointer to a created oslSocketAddr handle
 526     or to a null handle. After the call, it will contain the constructed
 527     oslSocketAddr of the datagrams sender. If pSenderAddr itself is 0,
 528     it is ignored.
 529     @param[out] pBuffer Points to a buffer that will be filled with the received
 530     datagram.
 531     @param[in] BufferSize The size of pBuffer.
 532     @param[in] Flag Modifier for the call. Valid values are:
 533     <ul>
 534     <li><code>osl_Socket_MsgNormal</code>
 535     <li><code>osl_Socket_MsgOOB</code>
 536     <li><code>osl_Socket_MsgPeek</code>
 537     <li><code>osl_Socket_MsgDontRoute</code>
 538     <li><code>osl_Socket_MsgMaxIOVLen</code>
 539     </ul>
 540
 541     @return the number of received bytes.
 542 */
 543 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_receiveFromSocket(
 544                               oslSocket Socket,
 545                               oslSocketAddr SenderAddr,
 546                               void* pBuffer,
 547                               sal_uInt32 BufferSize,
 548                               oslSocketMsgFlag Flag);
 549
 550 /** Tries to send BytesToSend data from the connected socket,
 551     if no error occurs.
 552
 553     @param[in] Socket A connected socket.
 554     @param[in] pBuffer Points to a buffer that contains the send-data.
 555     @param[in] BytesToSend The number of bytes to send. pBuffer must have at least
 556     this size.
 557     @param[in] Flag Modifier for the call. Valid values are:
 558     <ul>
 559     <li><code>osl_Socket_MsgNormal</code>
 560     <li><code>osl_Socket_MsgOOB</code>
 561     <li><code>osl_Socket_MsgPeek</code>
 562     <li><code>osl_Socket_MsgDontRoute</code>
 563     <li><code>osl_Socket_MsgMaxIOVLen</code>
 564     </ul>
 565
 566     @return the number of transfered bytes.
 567 */
 568 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendSocket(
 569                        oslSocket Socket,
 570                        const void* pBuffer,
 571                         sal_uInt32 BytesToSend,
 572                        oslSocketMsgFlag Flag);
 573
 574 /** Tries to send one datagram with BytesToSend data to the given ReceiverAddr
 575     via the (implicitly unconnected) datagram-socket.
 576     Since there is only sent one packet, the function sends the data always complete
 577     even with incomplete packet boundaries.
 578
 579     @param[in] Socket A bound or unbound socket. Socket will be bound
 580     after a successful call.
 581
 582     @param[in] ReceiverAddr An initialized oslSocketAddress that contains
 583     the destination address for this send.
 584
 585     @param[in] pBuffer Points to a buffer that contains the send-data.
 586     @param[in] BytesToSend The number of bytes to send. pBuffer must have at least
 587     this size.
 588     @param Flag [in] Modifier for the call. Valid values are:
 589     <ul>
 590     <li><code>osl_Socket_MsgNormal</code>
 591     <li><code>osl_Socket_MsgOOB</code>
 592     <li><code>osl_Socket_MsgPeek</code>
 593     <li><code>osl_Socket_MsgDontRoute</code>
 594     <li><code>osl_Socket_MsgMaxIOVLen</code>
 595     </ul>
 596
 597     @return the number of transfered bytes.
 598 */
 599 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendToSocket(
 600                          oslSocket Socket,
 601                          oslSocketAddr ReceiverAddr,
 602                           const void* pBuffer,
 603                          sal_uInt32 BytesToSend,
 604                          oslSocketMsgFlag Flag);
 605
 606 /** Checks if read operations will block.
 607
 608     You can specify a timeout-value in seconds/microseconds that denotes
 609     how long the operation will block if the Socket is not ready.
 610
 611     @return <code>sal_True</code> if read operations (recv, recvFrom, accept) on the Socket
 612     will NOT block; <code>sal_False</code> if it would block or if an error occurred.
 613
 614     @param Socket the Socket to perfom the operation on.
 615     @param pTimeout if NULL, the operation will block without a timeout.
 616 */
 617 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isReceiveReady(
 618         oslSocket Socket, const TimeValue* pTimeout);
 619
 620 /** Checks if send operations will block.
 621     You can specify a timeout-value in seconds/microseconds that denotes
 622     how long the operation will block if the Socket is not ready.
 623     @return <code>sal_True</code> if send operations (send, sendTo) on the Socket
 624     will NOT block; <code>sal_False</code> if it would block or if an error occurred.
 625
 626     @param Socket the Socket to perfom the operation on.
 627     @param pTimeout if NULL, the operation will block without a timeout. Otherwise
 628     the time define by timeout value.
 629 */
 630 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isSendReady(
 631         oslSocket Socket, const TimeValue* pTimeout);
 632
 633 /** Checks if a request for out-of-band data will block.
 634     You can specify a timeout-value in seconds/microseconds that denotes
 635     how long the operation will block if the Socket has no pending OOB data.
 636     @return <code>sal_True</code> if OOB-request operations (recv with appropriate flags)
 637     on the Socket will NOT block; <code>sal_False</code> if it would block or if an error occurred.
 638
 639     @param Socket the Socket to perfom the operation on.
 640     @param pTimeout if NULL, the operation will block without a timeout.
 641 */
 642 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isExceptionPending(
 643         oslSocket Socket, const TimeValue* pTimeout);
 644
 645 /** Shuts down communication on a connected socket.
 646     @param[in] Socket the Socket to perfom the operation on.
 647     @param[in] Direction denotes which end of the socket
 648     should be closed:
 649     <ul>
 650     <li> <code>osl_Socket_DirRead</code>    closes read operations.
 651     <li> <code>osl_Socket_DirReadWrite</code> closes write operations.
 652     <li> <code>osl_Socket_DirWrite</code> closes read and write operations.
 653     </ul>
 654     @return <code>sal_True</code> if the socket could be closed down.
 655 */
 656 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_shutdownSocket(oslSocket Socket,
 657                            oslSocketDirection Direction);
 658
 659 /** Retrieves attributes associated with the socket.
 660     @param Socket is the socket to query.
 661
 662     @param Level selects the level for which an option should be queried.
 663     Valid values are:
 664     <ul>
 665     <li> osl_sol_socket:    Socket Level
 666     <li> osl_sol_tcp:       Level of Transmission Control Protocol
 667     </ul>
 668
 669     @param Option denotes the option to query.
 670     Valid values (depending on the Level) are:
 671     <ul>
 672     <li> <code>osl_Socket_Option_Debug</code><br>
 673     (sal_Bool) Socket debug flag 1 = enabled, 0 = disabled.
 674
 675     <li> <code>osl_Socket_OptionAcceptConn</code><br>
 676     <li> <code>osl_Socket_OptionReuseAddr</code><br>
 677     (sal_Bool) Allows the socket to be bound to an address that is
 678     already in use.
 679     1 = multiple bound allowed, 0 = no multiple bounds allowed
 680
 681     <li><code>osl_Socket_OptionKeepAlive</code><br>
 682     (sal_Bool) Keepalive packets are sent by the underlying socket.
 683     1 = enabled, 0 = disabled
 684
 685     <li><code>osl_Socket_OptionDontRoute</code><br>
 686     (sal_Bool) Do not route: send directly to interface.
 687     1 = do not route , 0 = routing possible
 688
 689     <li><code>osl_Socket_OptionBroadcast</code><br>
 690     (sal_Bool) Transmission of broadcast messages are allowed on the socket.
 691     1 = transmission allowed, 0 = transmission disallowed
 692
 693     <li><code>osl_Socket_OptionUseLoopback</code><br>
 694
 695     <li><code>osl_Socket_OptionLinger</code><br>
 696     (sal_Int32) Linger on close if unsent data is present.
 697     0 = linger is off, > 0  = timeout in seconds.
 698
 699     <li><code>osl_Socket_OptionOOBinLine</code><br>
 700
 701
 702     <li><code>osl_Socket_OptionSndBuf</code><br>
 703     (sal_Int32) Size of the send buffer in bytes. Data is sent after
 704     SndTimeo or when the buffer is full. This allows faster writing
 705     to the socket.
 706
 707     <li><code>osl_Socket_OptionRcvBuf</code><br>
 708     (sal_Int32) Size of the receive buffer in bytes. Data is sent after
 709     SndTimeo or when the buffer is full. This allows faster writing
 710     to the socket and larger packet sizes.
 711
 712     <li><code>osl_Socket_OptionSndLowat</code><br>
 713
 714     <li><code>osl_Socket_OptionRcvLowat</code><br>
 715
 716     <li><code>osl_Socket_OptionSndTimeo</code><br>
 717     (sal_Int32) Data is sent after this timeout. This allows gathering
 718     of data to send larger packages but increases latency times.
 719
 720     <li><code>osl_Socket_OptionRcvTimeo</code><br>
 721
 722     <li><code>osl_Socket_OptionError</code><br>
 723     <li><code>osl_Socket_OptionType</code><br>
 724
 725     <li><code>osl_Socket_OptionTcpNoDelay</code><br>
 726     Disables the Nagle algorithm for send coalescing. (Do not
 727     collect data until a packet is full, instead send immediately.
 728     This increases network traffic but might improve latency-times.)
 729     1 = disables the algorithm, 0 = keeps it enabled.
 730     </ul>
 731     If not above mentioned otherwise, the options are only valid for
 732     level <code>osl_Socket_LevelSocket</code>.
 733
 734     @param pBuffer Pointer to a buffer large enough to take the desired
 735     attribute-value.
 736
 737     @param BufferLen contains the length of the Buffer.
 738
 739     @return -1 if an error occurred or else the size of the data copied into
 740     pBuffer.
 741     @see osl_setSocketOption()
 742 */
 743 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getSocketOption( oslSocket Socket,
 744                                oslSocketOptionLevel Level,
 745                             oslSocketOption      Option,
 746                             void*                pBuffer,
 747                             sal_uInt32               BufferLen);
 748
 749 /** Sets the sockets attributes.
 750
 751     @param Socket is the socket to modify.
 752
 753     @param Level selects the level for which an option should be changed.
 754     Valid values are:
 755     <ul>
 756     <li> osl_sol_socket:    Socket Level
 757     <li> osl_sol_tcp:       Level of Transmission Control Protocol
 758     </ul>
 759
 760     @param Option denotes the option to modify. See osl_setSocketOption() for more
 761     details.
 762
 763     @param pBuffer Pointer to a Buffer which contains the attribute-value.
 764
 765     @param BufferLen contains the length of the Buffer.
 766
 767     @return True if the option could be changed.
 768 */
 769 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setSocketOption( oslSocket Socket,
 770                             oslSocketOptionLevel    Level,
 771                             oslSocketOption         Option,
 772                             void*                   pBuffer,
 773                             sal_uInt32              BufferLen);
 774
 775 /** Enables/disables non-blocking-mode of the socket.
 776     @param Socket Change mode for this socket.
 777     @param On <code>sal_True</code> enables non-blocking mode,
 778               <code>sal_False</code> disables non-blocking mode.
 779     @return <code>sal_True</code> if mode could be changed.
 780 */
 781 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_enableNonBlockingMode(
 782         oslSocket Socket, sal_Bool On);
 783
 784
 785 /** Query state of non-blocking-mode of the socket.
 786     @param Socket Query mode for this socket.
 787     @return True if non-blocking-mode is enabled.
 788 */
 789 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isNonBlockingMode(
 790         oslSocket Socket);
 791
 792
 793 /** Queries the socket for its type.
 794     @param[in] Socket The socket to query.
 795     @return one of:
 796     <ul>
 797     <li> osl_Socket_TypeStream
 798     <li> osl_Socket_TypeDgram
 799     <li> osl_Socket_TypeRaw
 800     <li> osl_Socket_TypeRdm
 801     <li> osl_Socket_TypeSeqPacket
 802     <li> osl_invalid_SocketType, if an error occurred
 803     </ul>
 804 */
 805 SAL_DLLPUBLIC oslSocketType SAL_CALL osl_getSocketType(
 806         oslSocket Socket);
 807
 808 /** returns  a string which describes the last socket error.
 809     @param[in] Socket The socket to query.
 810     @param[out] strError The string that receives the error message.
 811 */
 812 SAL_DLLPUBLIC void SAL_CALL osl_getLastSocketErrorDescription(
 813         oslSocket Socket, rtl_uString **strError);
 814
 815 /** returns a constant decribing the last error for the socket system.
 816     @return <code>osl_Socket_E_NONE</code> if no error occurred,
 817             <code>osl_invalid_SocketError</code> if an unknown (unmapped)
 818             error occurred, otherwise an enum describing the    error.
 819 */
 820 SAL_DLLPUBLIC oslSocketError SAL_CALL osl_getLastSocketError(
 821         oslSocket Socket);
 822
 823 /** Type for the representation of socket sets.
 824 */
 825 typedef struct oslSocketSetImpl * oslSocketSet;
 826
 827 /** Creates a set of sockets to be used with osl_demultiplexSocketEvents().
 828     @return A oslSocketSet or 0 if creation failed.
 829 */
 830 SAL_DLLPUBLIC oslSocketSet SAL_CALL osl_createSocketSet(void);
 831
 832 /** Destroys a oslSocketSet.
 833 */
 834 SAL_DLLPUBLIC void SAL_CALL osl_destroySocketSet(oslSocketSet Set);
 835
 836 /** Clears the set from all previously added sockets.
 837     @param Set the set to be cleared.
 838 */
 839 SAL_DLLPUBLIC void SAL_CALL osl_clearSocketSet(oslSocketSet Set);
 840
 841
 842 /** Adds a socket to the set.
 843     @param Set the set were the socket is added.
 844     @param Socket the socket to be added.
 845 */
 846 SAL_DLLPUBLIC void SAL_CALL osl_addToSocketSet(oslSocketSet Set, oslSocket Socket);
 847
 848 /** Removes a socket from the set.
 849     @param Set the set were the socket is removed from.
 850     @param Socket the socket to be removed.
 851 */
 852 SAL_DLLPUBLIC void SAL_CALL osl_removeFromSocketSet(oslSocketSet Set, oslSocket Socket);
 853
 854 /** Checks if socket is in the set.
 855     @param Set the set to be checked.
 856     @param Socket check if this socket is in the set.
 857     @return <code>sal_True</code> if socket is in the set.
 858 */
 859 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isInSocketSet(oslSocketSet Set, oslSocket Socket);
 860
 861 /** Checks multiple sockets for events.
 862     @param IncomingSet Checks the sockets in this set
 863     for incoming events (read, accept). If the set is 0,
 864     it is just skipped.
 865     @param OutgoingSet Checks the sockets in this set
 866     for outgoing events (write, connect). If the set is 0,
 867     it is just skipped.
 868     @param OutOfBandSet Checks the sockets in this set
 869     for out-of-band events. If the set is 0, it is just skipped.
 870     @param pTimeout Address of the number of milliseconds to wait for events. If
 871     *pTimeout is -1, the call will block until an event or an error
 872     occurs.
 873     @return -1 on errors, otherwise the number of sockets with
 874     pending events. In case of timeout, the number might be 0.
 875 */
 876 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_demultiplexSocketEvents(oslSocketSet IncomingSet,
 877                                     oslSocketSet OutgoingSet,
 878                                     oslSocketSet OutOfBandSet,
 879                                     const TimeValue* pTimeout);
 880
 881 /** Closes the socket terminating any ongoing dataflow.
 882     @param[in] Socket The socket to close.
 883  */
 884 SAL_DLLPUBLIC void SAL_CALL osl_closeSocket(oslSocket Socket);
 885
 886
 887 /** Retrieves n bytes from the stream and copies them into pBuffer.
 888     The function avoids incomplete reads due to packet boundaries.
 889     @param[in] Socket The socket to read from.
 890     @param[out] pBuffer receives the read data.
 891     @param[out] nSize the number of bytes to read. pBuffer must be large enough
 892     to hold the n bytes!
 893     @return the number of read bytes. The number will only be smaller than
 894     n if an exceptional condition (e.g. connection closed) occurs.
 895 */
 896 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_readSocket( oslSocket Socket, void *pBuffer, sal_Int32 nSize );
 897
 898
 899 /** Writes n bytes from pBuffer to the stream. The method avoids
 900     incomplete writes due to packet boundaries.
 901     @param[out] Socket The socket to write to.
 902     @param[in] pBuffer contains the data to be written.
 903     @param[in] nSize the number of bytes to write.
 904     @return the number of written bytes. The number will only be smaller than
 905     nSize if an exceptional condition (e.g. connection closed) occurs.
 906 */
 907 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_writeSocket( oslSocket Socket, const void *pBuffer, sal_Int32 nSize );
 908
 909 /**@} end section oslSocket
 910 */
 911
 912
 913
 914 #ifdef __cplusplus
 915 }
 916 #endif
 917
 918 #endif // INCLUDED_OSL_SOCKET_H
 919
 920 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */