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