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