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