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     @retval sal_True if both addresses denote the same socket address.
 216     @retval sal_False if both addresses do not denote the same socket address.
 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     @retval 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 host address 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     @retval 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     @retval 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     @retval sal_False 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     @retval osl_Socket_Ok
 309     @retval osl_Socket_Error
 310 */
 311 SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getDottedInetAddrOfSocketAddr(
 312         oslSocketAddr Addr, rtl_uString **strDottedInetAddr);
 313
 314 /** Sets the addr field in the struct sockaddr with pByteSeq. pByteSeq must be in network byte order.
 315  */
 316 SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_setAddrOfSocketAddr(
 317         oslSocketAddr Addr, sal_Sequence *pByteSeq );
 318
 319 /** Returns the addr field in the struct sockaddr.
 320     @param[in] Addr The socket address from which to extract the ipaddress.
 321     @param[out] ppByteSeq After the call, *ppByteSeq contains the ipaddress
 322                      in network byteorder. *ppByteSeq may be 0 in case of an invalid socket handle.
 323     @retval osl_Socket_Ok
 324     @retval osl_Socket_Error
 325  */
 326 SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getAddrOfSocketAddr(
 327         oslSocketAddr Addr, sal_Sequence **ppByteSeq );
 328
 329 /*
 330     Opaque datatype HostAddr.
 331 */
 332 typedef struct oslHostAddrImpl * oslHostAddr;
 333
 334
 335 /** Create an oslHostAddr from given hostname and socket address.
 336     @param[in] strHostname The hostname to be stored.
 337     @param[in] Addr The socket address to be stored.
 338     @return The created address or 0 upon failure.
 339 */
 340 SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddr(
 341         rtl_uString *strHostname, const oslSocketAddr Addr);
 342
 343
 344 /** Create an oslHostAddr by resolving the given strHostname.
 345     Successful name resolution should result in the fully qualified
 346     domain name (FQDN) and its address as hostname and socket address
 347     members of the resulting oslHostAddr.
 348     @param[in] strHostname The hostname to be resolved.
 349     @return The resulting address or 0 upon failure.
 350 */
 351 SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddrByName(rtl_uString *strHostname);
 352
 353
 354 /** Create an oslHostAddr by reverse resolution of the given Addr.
 355     Successful name resolution should result in the fully qualified
 356     domain name (FQDN) and its address as hostname and socket address
 357     members of the resulting oslHostAddr.
 358     @param[in] Addr The socket address to be reverse resolved.
 359     @return The resulting address or 0 upon failure.
 360 */
 361 SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_createHostAddrByAddr(const oslSocketAddr Addr);
 362
 363
 364 /** Create a copy of the given Addr.
 365     @return The copied address or 0 upon failure.
 366 */
 367 SAL_DLLPUBLIC oslHostAddr SAL_CALL osl_copyHostAddr(const oslHostAddr Addr);
 368
 369
 370 /** Frees all resources allocated by Addr. The handle Addr must not
 371     be used after the call anymore.
 372 */
 373 SAL_DLLPUBLIC void SAL_CALL osl_destroyHostAddr(oslHostAddr Addr);
 374
 375
 376 /** Get the hostname member of Addr.
 377     @return The hostname or 0 upon failure.
 378 */
 379 SAL_DLLPUBLIC void SAL_CALL osl_getHostnameOfHostAddr(const oslHostAddr Addr, rtl_uString **strHostname);
 380
 381
 382 /** Get the socket address member of Addr.
 383     @return The socket address or 0 upon failure.
 384 */
 385 SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getSocketAddrOfHostAddr(const oslHostAddr Addr);
 386
 387 /** Retrieve this machines hostname.
 388     May not always be a fully qualified domain name (FQDN).
 389     @param  strLocalHostname out-parameter. The string that receives the local host name.
 390     @retval sal_True upon success
 391     @retval sal_False
 392 */
 393 SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getLocalHostname(rtl_uString **strLocalHostname);
 394
 395
 396 /**@} end section oslHostAddr
 397 */
 398
 399 /**@{ begin section oslSocket
 400 */
 401
 402
 403 /*-***************************************************************************/
 404 /* oslSocket */
 405 /*-***************************************************************************/
 406
 407 typedef struct oslSocketImpl * oslSocket;
 408
 409 /** increases the refcount of the socket handle by one
 410  */
 411 SAL_DLLPUBLIC void SAL_CALL osl_acquireSocket( oslSocket Socket );
 412
 413 /** decreases the refcount of the socket handle by one.
 414
 415     If the refcount drops to zero, the underlying socket handle
 416     is destroyed and becomes invalid.
 417  */
 418 SAL_DLLPUBLIC void SAL_CALL osl_releaseSocket( oslSocket Socket );
 419
 420 /** Create a socket of the specified Family and Type. The semantic of
 421     the Protocol parameter depends on the given family and type.
 422     @retval 0 if socket could not be created, otherwise you get a handle
 423     to the allocated socket-datastructure.
 424 */
 425 SAL_DLLPUBLIC oslSocket SAL_CALL osl_createSocket(
 426                                     oslAddrFamily   Family,
 427                                     oslSocketType   Type,
 428                                     oslProtocol     Protocol);
 429
 430 /** Retrieves the Address of the local end of the socket.
 431     Note that a socket must be bound or connected before
 432     a valid address can be returned.
 433     @retval 0 if socket-address could not be created, otherwise you get
 434     the created Socket-Address.
 435 */
 436 SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getLocalAddrOfSocket(oslSocket Socket);
 437
 438 /** Retrieves the Address of the remote end of the socket.
 439     Note that a socket must be connected before
 440     a valid address can be returned.
 441     @retval 0 if socket-address could not be created, otherwise you get
 442     the created Socket-Address.
 443 */
 444 SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getPeerAddrOfSocket(oslSocket Socket);
 445
 446 /** Binds the given address to the socket.
 447     @param[in] Socket
 448     @param[in] Addr
 449     @retval sal_False if the bind failed
 450     @retval sal_True if bind is successful
 451     @see osl_getLastSocketError()
 452 */
 453 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_bindAddrToSocket(
 454                                        oslSocket Socket,
 455                                        oslSocketAddr Addr);
 456
 457 /** Connects the socket to the given address.
 458
 459     @param[in] Socket a bound socket.
 460     @param[in] Addr the peer address.
 461     @param pTimeout Timeout value or NULL for blocking.
 462
 463     @retval osl_Socket_Ok on successful connection,
 464     @retval osl_Socket_TimedOut if operation timed out,
 465     @retval osl_Socket_Interrupted if operation was interrupted
 466     @retval osl_Socket_Error if the connection failed.
 467 */
 468 SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_connectSocketTo(
 469                                         oslSocket Socket,
 470                                         oslSocketAddr Addr,
 471                                         const TimeValue* pTimeout);
 472
 473
 474 /** Prepares the socket to act as an acceptor of incoming connections.
 475     You should call "listen" before you use "accept".
 476     @param[in] Socket The socket to listen on.
 477     @param[in] MaxPendingConnections denotes the length of the queue of
 478     pending connections for this socket. If MaxPendingConnections is
 479     -1, the systems default value will be used (Usually 5).
 480     @retval sal_False if the listen failed.
 481 */
 482 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_listenOnSocket(
 483                            oslSocket Socket,
 484                            sal_Int32 MaxPendingConnections);
 485
 486
 487 /** Waits for an ingoing connection on the socket.
 488     This call blocks if there is no incoming connection present.
 489     @param[in] Socket The socket to accept the connection on.
 490     @param[in] pAddr if pAddr is != 0, the peers address is returned.
 491     @retval 0 if the accept-call failed, otherwise you get a socket
 492     representing the new connection.
 493 */
 494 SAL_DLLPUBLIC oslSocket SAL_CALL osl_acceptConnectionOnSocket
 495                                        (oslSocket Socket,
 496                                        oslSocketAddr* pAddr);
 497
 498 /** Tries to receive BytesToRead data from the connected socket,
 499     if no error occurs. Note that incomplete recvs due to
 500     packet boundaries may occur.
 501
 502     @param[in] Socket A connected socket to be used to listen on.
 503     @param[out] pBuffer Points to a buffer that will be filled with the received
 504     data.
 505     @param[in] BytesToRead The number of bytes to read. pBuffer must have at least
 506     this size.
 507     @param[in] Flag Modifier for the call. Valid values are:
 508     osl_Socket_MsgNormal
 509     osl_Socket_MsgOOB
 510     osl_Socket_MsgPeek
 511     osl_Socket_MsgDontRoute
 512     osl_Socket_MsgMaxIOVLen
 513
 514     @return the number of received bytes.
 515 */
 516 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_receiveSocket(
 517                           oslSocket Socket,
 518                           void* pBuffer,
 519                            sal_uInt32 BytesToRead,
 520                           oslSocketMsgFlag Flag);
 521
 522 /** Tries to receives BufferSize data from the (usually unconnected)
 523     (datagram-)socket, if no error occurs.
 524
 525     @param[in] Socket A bound socket to be used to listen for a datagram.
 526     @param[out] SenderAddr A pointer to a created oslSocketAddr handle
 527     or to a null handle. After the call, it will contain the constructed
 528     oslSocketAddr of the datagrams sender. If pSenderAddr itself is 0,
 529     it is ignored.
 530     @param[out] pBuffer Points to a buffer that will be filled with the received
 531     datagram.
 532     @param[in] BufferSize The size of pBuffer.
 533     @param[in] Flag Modifier for the call. Valid values are:
 534     osl_Socket_MsgNormal
 535     osl_Socket_MsgOOB
 536     osl_Socket_MsgPeek
 537     osl_Socket_MsgDontRoute
 538     osl_Socket_MsgMaxIOVLen
 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     <li><code>osl_Socket_MsgNormal</code>
 558     <li><code>osl_Socket_MsgOOB</code>
 559     <li><code>osl_Socket_MsgPeek</code>
 560     <li><code>osl_Socket_MsgDontRoute</code>
 561     <li><code>osl_Socket_MsgMaxIOVLen</code>
 562
 563     @return the number of transferred bytes.
 564 */
 565 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendSocket(
 566                        oslSocket Socket,
 567                        const void* pBuffer,
 568                         sal_uInt32 BytesToSend,
 569                        oslSocketMsgFlag Flag);
 570
 571 /** Tries to send one datagram with BytesToSend data to the given ReceiverAddr
 572     via the (implicitly unconnected) datagram-socket.
 573     Since there is only sent one packet, the function sends the data always complete
 574     even with incomplete packet boundaries.
 575
 576     @param[in] Socket A bound or unbound socket. Socket will be bound
 577     after a successful call.
 578
 579     @param[in] ReceiverAddr An initialized oslSocketAddress that contains
 580     the destination address for this send.
 581
 582     @param[in] pBuffer Points to a buffer that contains the send-data.
 583     @param[in] BytesToSend The number of bytes to send. pBuffer must have at least
 584     this size.
 585     @param Flag [in] Modifier for the call. Valid values are:
 586     <li><code>osl_Socket_MsgNormal</code>
 587     <li><code>osl_Socket_MsgOOB</code>
 588     <li><code>osl_Socket_MsgPeek</code>
 589     <li><code>osl_Socket_MsgDontRoute</code>
 590     <li><code>osl_Socket_MsgMaxIOVLen</code>
 591
 592     @return the number of transferred bytes.
 593 */
 594 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendToSocket(
 595                          oslSocket Socket,
 596                          oslSocketAddr ReceiverAddr,
 597                           const void* pBuffer,
 598                          sal_uInt32 BytesToSend,
 599                          oslSocketMsgFlag Flag);
 600
 601 /** Checks if read operations will block.
 602
 603     You can specify a timeout-value in seconds/microseconds that denotes
 604     how long the operation will block if the Socket is not ready.
 605
 606     @retval sal_True if read operations (recv, recvFrom, accept) on the Socket
 607     will NOT block;
 608     @retval sal_False if it would block or if an error occurred.
 609
 610     @param Socket the Socket to perfom the operation on.
 611     @param pTimeout if NULL, the operation will block without a timeout.
 612 */
 613 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isReceiveReady(
 614         oslSocket Socket, const TimeValue* pTimeout);
 615
 616 /** Checks if send operations will block.
 617     You can specify a timeout-value in seconds/microseconds that denotes
 618     how long the operation will block if the Socket is not ready.
 619     @retval sal_True if send operations (send, sendTo) on the Socket
 620     will NOT block
 621     @retval sal_False if it would block or if an error occurred.
 622
 623     @param Socket the Socket to perfom the operation on.
 624     @param pTimeout if NULL, the operation will block without a timeout. Otherwise
 625     the time define by timeout value.
 626 */
 627 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isSendReady(
 628         oslSocket Socket, const TimeValue* pTimeout);
 629
 630 /** Checks if a request for out-of-band data will block.
 631     You can specify a timeout-value in seconds/microseconds that denotes
 632     how long the operation will block if the Socket has no pending OOB data.
 633     @retval sal_True if OOB-request operations (recv with appropriate flags)
 634     on the Socket will NOT block
 635     @retval sal_False if it would block or if an error occurred.
 636
 637     @param Socket the Socket to perfom the operation on.
 638     @param pTimeout if NULL, the operation will block without a timeout.
 639 */
 640 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isExceptionPending(
 641         oslSocket Socket, const TimeValue* pTimeout);
 642
 643 /** Shuts down communication on a connected socket.
 644     @param[in] Socket the Socket to perfom the operation on.
 645     @param[in] Direction denotes which end of the socket
 646     should be closed:
 647     <ul>
 648     <li> <code>osl_Socket_DirRead</code>    closes read operations.
 649     <li> <code>osl_Socket_DirReadWrite</code> closes write operations.
 650     <li> <code>osl_Socket_DirWrite</code> closes read and write operations.
 651     </ul>
 652     @return <code>sal_True</code> if the socket could be closed down.
 653 */
 654 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_shutdownSocket(oslSocket Socket,
 655                            oslSocketDirection Direction);
 656
 657 /** Retrieves attributes associated with the socket.
 658     @param Socket is the socket to query.
 659
 660     @param Level selects the level for which an option should be queried.
 661     Valid values are:
 662     <ul>
 663     <li> osl_sol_socket:    Socket Level
 664     <li> osl_sol_tcp:       Level of Transmission Control Protocol
 665     </ul>
 666
 667     @param Option denotes the option to query.
 668     Valid values (depending on the Level) are:
 669     <ul>
 670     <li> <code>osl_Socket_Option_Debug</code><br>
 671     (sal_Bool) Socket debug flag 1 = enabled, 0 = disabled.
 672
 673     <li> <code>osl_Socket_OptionAcceptConn</code><br>
 674     <li> <code>osl_Socket_OptionReuseAddr</code><br>
 675     (sal_Bool) Allows the socket to be bound to an address that is
 676     already in use.
 677     1 = multiple bound allowed, 0 = no multiple bounds allowed
 678
 679     <li><code>osl_Socket_OptionKeepAlive</code><br>
 680     (sal_Bool) Keepalive packets are sent by the underlying socket.
 681     1 = enabled, 0 = disabled
 682
 683     <li><code>osl_Socket_OptionDontRoute</code><br>
 684     (sal_Bool) Do not route: send directly to interface.
 685     1 = do not route , 0 = routing possible
 686
 687     <li><code>osl_Socket_OptionBroadcast</code><br>
 688     (sal_Bool) Transmission of broadcast messages are allowed on the socket.
 689     1 = transmission allowed, 0 = transmission disallowed
 690
 691     <li><code>osl_Socket_OptionUseLoopback</code><br>
 692
 693     <li><code>osl_Socket_OptionLinger</code><br>
 694     (sal_Int32) Linger on close if unsent data is present.
 695     0 = linger is off, > 0  = timeout in seconds.
 696
 697     <li><code>osl_Socket_OptionOOBinLine</code><br>
 698
 699
 700     <li><code>osl_Socket_OptionSndBuf</code><br>
 701     (sal_Int32) Size of the send buffer in bytes. Data is sent after
 702     SndTimeo or when the buffer is full. This allows faster writing
 703     to the socket.
 704
 705     <li><code>osl_Socket_OptionRcvBuf</code><br>
 706     (sal_Int32) Size of the receive buffer in bytes. Data is sent after
 707     SndTimeo or when the buffer is full. This allows faster writing
 708     to the socket and larger packet sizes.
 709
 710     <li><code>osl_Socket_OptionSndLowat</code><br>
 711
 712     <li><code>osl_Socket_OptionRcvLowat</code><br>
 713
 714     <li><code>osl_Socket_OptionSndTimeo</code><br>
 715     (sal_Int32) Data is sent after this timeout. This allows gathering
 716     of data to send larger packages but increases latency times.
 717
 718     <li><code>osl_Socket_OptionRcvTimeo</code><br>
 719
 720     <li><code>osl_Socket_OptionError</code><br>
 721     <li><code>osl_Socket_OptionType</code><br>
 722
 723     <li><code>osl_Socket_OptionTcpNoDelay</code><br>
 724     Disables the Nagle algorithm for send coalescing. (Do not
 725     collect data until a packet is full, instead send immediately.
 726     This increases network traffic but might improve latency-times.)
 727     1 = disables the algorithm, 0 = keeps it enabled.
 728     </ul>
 729     If not above mentioned otherwise, the options are only valid for
 730     level <code>osl_Socket_LevelSocket</code>.
 731
 732     @param pBuffer Pointer to a buffer large enough to take the desired
 733     attribute-value.
 734
 735     @param BufferLen contains the length of the Buffer.
 736
 737     @return -1 if an error occurred or else the size of the data copied into
 738     pBuffer.
 739     @see osl_setSocketOption()
 740 */
 741 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getSocketOption( oslSocket Socket,
 742                                oslSocketOptionLevel Level,
 743                             oslSocketOption      Option,
 744                             void*                pBuffer,
 745                             sal_uInt32               BufferLen);
 746
 747 /** Sets the sockets attributes.
 748
 749     @param Socket is the socket to modify.
 750
 751     @param Level selects the level for which an option should be changed.
 752     Valid values are:
 753     <ul>
 754     <li> osl_sol_socket:    Socket Level
 755     <li> osl_sol_tcp:       Level of Transmission Control Protocol
 756     </ul>
 757
 758     @param Option denotes the option to modify. See osl_setSocketOption() for more
 759     details.
 760
 761     @param pBuffer Pointer to a Buffer which contains the attribute-value.
 762
 763     @param BufferLen contains the length of the Buffer.
 764
 765     @retval True if the option could be changed.
 766 */
 767 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setSocketOption( oslSocket Socket,
 768                             oslSocketOptionLevel    Level,
 769                             oslSocketOption         Option,
 770                             void*                   pBuffer,
 771                             sal_uInt32              BufferLen);
 772
 773 /** Enables/disables non-blocking-mode of the socket.
 774     @param Socket Change mode for this socket.
 775     @param On sal_True enables non-blocking mode,
 776               sal_False</code> disables non-blocking mode.
 777     @retval sal_True if mode could be changed.
 778 */
 779 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_enableNonBlockingMode(
 780         oslSocket Socket, sal_Bool On);
 781
 782
 783 /** Query state of non-blocking-mode of the socket.
 784     @param Socket Query mode for this socket.
 785     @retval True if non-blocking-mode is enabled.
 786 */
 787 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isNonBlockingMode(
 788         oslSocket Socket);
 789
 790
 791 /** Queries the socket for its type.
 792     @param[in] Socket The socket to query.
 793     @retval osl_Socket_TypeStream
 794     @retval osl_Socket_TypeDgram
 795     @retval osl_Socket_TypeRaw
 796     @retval osl_Socket_TypeRdm
 797     @retval osl_Socket_TypeSeqPacket
 798     @retval osl_invalid_SocketType if an error occurred
 799 */
 800 SAL_DLLPUBLIC oslSocketType SAL_CALL osl_getSocketType(
 801         oslSocket Socket);
 802
 803 /** returns  a string which describes the last socket error.
 804     @param[in] Socket The socket to query.
 805     @param[out] strError The string that receives the error message.
 806 */
 807 SAL_DLLPUBLIC void SAL_CALL osl_getLastSocketErrorDescription(
 808         oslSocket Socket, rtl_uString **strError);
 809
 810 /** returns a constant describing the last error for the socket system.
 811     @retval osl_Socket_E_NONE if no error occurred
 812     @retval osl_invalid_SocketError if an unknown (unmapped)
 813             error occurred, otherwise an enum describing the error.
 814 */
 815 SAL_DLLPUBLIC oslSocketError SAL_CALL osl_getLastSocketError(
 816         oslSocket Socket);
 817
 818 /** Type for the representation of socket sets.
 819 */
 820 typedef struct oslSocketSetImpl * oslSocketSet;
 821
 822 /** Creates a set of sockets to be used with osl_demultiplexSocketEvents().
 823     @return A oslSocketSet or 0 if creation failed.
 824 */
 825 SAL_DLLPUBLIC oslSocketSet SAL_CALL osl_createSocketSet(void);
 826
 827 /** Destroys a oslSocketSet.
 828 */
 829 SAL_DLLPUBLIC void SAL_CALL osl_destroySocketSet(oslSocketSet Set);
 830
 831 /** Clears the set from all previously added sockets.
 832     @param Set the set to be cleared.
 833 */
 834 SAL_DLLPUBLIC void SAL_CALL osl_clearSocketSet(oslSocketSet Set);
 835
 836
 837 /** Adds a socket to the set.
 838     @param Set the set were the socket is added.
 839     @param Socket the socket to be added.
 840 */
 841 SAL_DLLPUBLIC void SAL_CALL osl_addToSocketSet(oslSocketSet Set, oslSocket Socket);
 842
 843 /** Removes a socket from the set.
 844     @param Set the set were the socket is removed from.
 845     @param Socket the socket to be removed.
 846 */
 847 SAL_DLLPUBLIC void SAL_CALL osl_removeFromSocketSet(oslSocketSet Set, oslSocket Socket);
 848
 849 /** Checks if socket is in the set.
 850     @param Set the set to be checked.
 851     @param Socket check if this socket is in the set.
 852     @retval sal_True if socket is in the set.
 853 */
 854 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isInSocketSet(oslSocketSet Set, oslSocket Socket);
 855
 856 /** Checks multiple sockets for events.
 857     @param IncomingSet Checks the sockets in this set
 858     for incoming events (read, accept). If the set is 0,
 859     it is just skipped.
 860     @param OutgoingSet Checks the sockets in this set
 861     for outgoing events (write, connect). If the set is 0,
 862     it is just skipped.
 863     @param OutOfBandSet Checks the sockets in this set
 864     for out-of-band events. If the set is 0, it is just skipped.
 865     @param pTimeout Address of the number of milliseconds to wait for events. If
 866     *pTimeout is -1, the call will block until an event or an error
 867     occurs.
 868     @return -1 on errors, otherwise the number of sockets with
 869     pending events. In case of timeout, the number might be 0.
 870 */
 871 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_demultiplexSocketEvents(oslSocketSet IncomingSet,
 872                                     oslSocketSet OutgoingSet,
 873                                     oslSocketSet OutOfBandSet,
 874                                     const TimeValue* pTimeout);
 875
 876 /** Closes the socket terminating any ongoing dataflow.
 877     @param[in] Socket The socket to close.
 878  */
 879 SAL_DLLPUBLIC void SAL_CALL osl_closeSocket(oslSocket Socket);
 880
 881
 882 /** Retrieves n bytes from the stream and copies them into pBuffer.
 883     The function avoids incomplete reads due to packet boundaries.
 884     @param[in] Socket The socket to read from.
 885     @param[out] pBuffer receives the read data.
 886     @param[out] nSize the number of bytes to read. pBuffer must be large enough
 887     to hold the n bytes!
 888     @return the number of read bytes. The number will only be smaller than
 889     n if an exceptional condition (e.g. connection closed) occurs.
 890 */
 891 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_readSocket( oslSocket Socket, void *pBuffer, sal_Int32 nSize );
 892
 893
 894 /** Writes n bytes from pBuffer to the stream. The method avoids
 895     incomplete writes due to packet boundaries.
 896     @param[out] Socket The socket to write to.
 897     @param[in] pBuffer contains the data to be written.
 898     @param[in] nSize the number of bytes to write.
 899     @return the number of written bytes. The number will only be smaller than
 900     nSize if an exceptional condition (e.g. connection closed) occurs.
 901 */
 902 SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_writeSocket( oslSocket Socket, const void *pBuffer, sal_Int32 nSize );
 903
 904 /**@} end section oslSocket
 905 */
 906
 907
 908
 909 #ifdef __cplusplus
 910 }
 911 #endif
 912
 913 #endif // INCLUDED_OSL_SOCKET_H
 914
 915 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */