include/osl/socket_decl.hxx

   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_DECL_HXX
  21 #define INCLUDED_OSL_SOCKET_DECL_HXX
  22
  23 #include <sal/config.h>
  24
  25 #include <cstddef>
  26
  27 #include <osl/socket.h>
  28 #include <rtl/ustring.hxx>
  29 #include <rtl/byteseq.hxx>
  30
  31 namespace osl
  32 {
  33     enum __osl_socket_NoCopy { SAL_NO_COPY };
  34
  35     /** The class should be understood as a reference to a socket address handle ( struct sockaddr ).
  36
  37         The handle is mutable.
  38      */
  39     class SocketAddr
  40     {
  41     protected:
  42         oslSocketAddr m_handle;
  43     public:
  44
  45         /** Creates socket address of unknown type.
  46          */
  47         inline SocketAddr();
  48
  49         /** Copy constructor.
  50          */
  51         inline SocketAddr(const SocketAddr& Addr);
  52
  53 #if defined LIBO_INTERNAL_ONLY
  54         inline SocketAddr(SocketAddr && other);
  55 #endif
  56
  57         /** The SocketAddr takes over the responsibility of the handle ( which means,
  58             that the handle gets destructed by the destructor of this reference)
  59             @param Addr a handle
  60             @param nocopy use SAL_NO_COPY
  61          */
  62         inline SocketAddr(const oslSocketAddr Addr, __osl_socket_NoCopy nocopy );
  63
  64         /** Copyconstructs the oslSocketAddr handle.
  65          */
  66         inline SocketAddr(oslSocketAddr Addr);
  67
  68         /** tcpip-specific constructor.
  69             @param strAddrOrHostName strAddrOrHostName hostname or dotted ip-number of the network
  70                                      interface, the socket shall be created on.
  71             @param nPort             tcp-ip port number
  72          */
  73         inline SocketAddr( const ::rtl::OUString& strAddrOrHostName, sal_Int32 nPort );
  74
  75         /** destroys underlying oslSocketAddress
  76          */
  77         inline ~SocketAddr();
  78
  79         /** checks, if the SocketAddr was created successful.
  80             @return <code>true</code> if there is a valid underlying handle,
  81                     otherwise false.
  82          */
  83         inline bool is() const;
  84
  85         /** Converts the address to a (human readable) domain-name.
  86
  87             @param pResult 0, if you are not interested in errors,
  88                            otherwise *pResult contains an error code on failure
  89                            or osl_Socket_Ok on success
  90             @return the hostname of this SocketAddr or an empty string on failure.
  91             @see osl_getHostnameOfSocketAddr()
  92         */
  93         inline ::rtl::OUString SAL_CALL getHostname( oslSocketResult *pResult = NULL ) const;
  94
  95         /** Sets the ipaddress or hostname of the SocketAddress
  96          */
  97         inline bool SAL_CALL setHostname( const ::rtl::OUString &sDottedIpOrHostname );
  98
  99         /** Returns the port number of the address.
 100             @return the port in host-byte order or OSL_INVALID_PORT on errors.
 101         */
 102         inline sal_Int32 SAL_CALL getPort() const;
 103
 104         /** Sets the port number of the address.
 105            @return true if successful.
 106          */
 107         inline bool SAL_CALL setPort( sal_Int32 nPort );
 108
 109         /** Sets the address of the underlying socket address struct in network byte order.
 110             @return true on success, false signals failure.
 111          */
 112         inline bool SAL_CALL setAddr( const ::rtl::ByteSequence & address );
 113
 114         /** Returns the address of the underlying socket in network byte order
 115           */
 116         inline ::rtl::ByteSequence  SAL_CALL getAddr( oslSocketResult *pResult = NULL ) const;
 117
 118         /** assign the handle to this reference. The previous handle is released.
 119         */
 120         inline SocketAddr & SAL_CALL operator= (oslSocketAddr Addr);
 121
 122         inline SocketAddr & SAL_CALL operator= (const SocketAddr& Addr);
 123
 124 #if defined LIBO_INTERNAL_ONLY
 125         inline SocketAddr & operator =(SocketAddr && other);
 126 #endif
 127
 128         /** Assigns the socket addr without copyconstructing it.
 129             @param Addr the socket address.
 130             @param nocopy use SAL_NO_COPY
 131           */
 132         inline SocketAddr & SAL_CALL assign( oslSocketAddr Addr, __osl_socket_NoCopy nocopy );
 133
 134         /** Returns true if the underlying handle is identical to the Addr handle.
 135          */
 136         inline bool SAL_CALL operator== (oslSocketAddr Addr) const;
 137
 138         /** Returns true if the underlying handle is identical to the Addr handle.
 139          */
 140         inline bool SAL_CALL operator== (const SocketAddr & Addr) const;
 141
 142         /** Returns the underlying SocketAddr handle without copyconstructing it.
 143          */
 144         inline oslSocketAddr SAL_CALL getHandle() const;
 145
 146         /** Get the hostname for the local interface.
 147             @param pResult after the call *pResult contains osl_Socket_Ok on success or
 148                    an error on failure.
 149             @return the hostname
 150         */
 151         static inline ::rtl::OUString SAL_CALL getLocalHostname( oslSocketResult *pResult = NULL);
 152
 153         /** Tries to find an address for a host.
 154             @see osl_resolveHostname()
 155             @return A new created socket-address or 0 if the name could not be found.
 156         */
 157         static inline void SAL_CALL resolveHostname(
 158             const ::rtl::OUString & strHostName , SocketAddr & Addr );
 159
 160         /**
 161            Tries to find the port associated with the given service/protocol-
 162            pair (e.g. "ftp"/"tcp").
 163            @return the port number in host-byte order or <code>OSL_INVALID_PORT</code>
 164            if no service/protocol pair could be found.
 165         */
 166         static inline sal_Int32 SAL_CALL getServicePort(
 167             const ::rtl::OUString& strServiceName,
 168             const ::rtl::OUString & strProtocolName= ::rtl::OUString("tcp") );
 169     };
 170
 171
 172     class Socket
 173     {
 174     protected:
 175         oslSocket m_handle;
 176     protected:
 177         /** Creates a socket. Note it's protected.
 178             @param Type
 179             @param Family
 180             @param Protocol
 181         */
 182         inline Socket(oslSocketType Type,
 183                       oslAddrFamily Family = osl_Socket_FamilyInet,
 184                       oslProtocol   Protocol = osl_Socket_ProtocolIp);
 185     public:
 186         inline Socket( );
 187
 188         inline Socket( const Socket & socket );
 189
 190         inline Socket( oslSocket socketHandle );
 191
 192         /** The instance takes over the handle's ownership without acquiring the
 193             handle, but releases it within the dtor.
 194             @param socketHandle the handle
 195             @param noacquire use SAL_NO_ACQUIRE
 196          */
 197         inline Socket( oslSocket socketHandle, __sal_NoAcquire noacquire );
 198
 199         /** Destructor. Releases the underlying handle
 200          */
 201         inline ~Socket();
 202
 203         /** Assignment operator. If socket was already created, the old one will
 204             be discarded.
 205         */
 206         inline Socket& SAL_CALL operator= ( oslSocket socketHandle);
 207
 208         /** Assignment operator. If socket was already created, the old one will
 209             be discarded.
 210         */
 211         inline Socket& SAL_CALL operator= (const Socket& sock);
 212
 213         /**
 214            @return <code>true</code>, when the underlying handle of both
 215                          Socket instances are identical, <code>false</code> otherwise.
 216          */
 217         inline bool SAL_CALL operator==( const Socket& rSocket ) const ;
 218
 219         /**
 220            @return <code>true</code>, when the underlying handle of both
 221                          Socket instances are identical, <code>false</code> otherwise.
 222          */
 223         inline bool SAL_CALL operator==( const oslSocket socketHandle ) const;
 224
 225         /** Closes a definite or both directions of the bidirectional stream.
 226
 227            @param Direction
 228            @see osl_shutdownSocket()
 229          */
 230         inline void SAL_CALL shutdown( oslSocketDirection Direction = osl_Socket_DirReadWrite );
 231
 232         /** Closes a socket.
 233             Note that closing a socket is identical to shutdown( osl_Socket_DirReadWrite ),
 234             as the operating system distinguish both cases, both functions or offered in this API.
 235             @see osl_closeSocket()
 236          */
 237         inline void SAL_CALL close();
 238
 239         /** Retrieves the address of the local interface of this socket.
 240             @param Addr [out] receives the address.
 241             @see osl_getLocalAddrOfSocket()
 242         */
 243         inline void SAL_CALL getLocalAddr( SocketAddr &Addr ) const;
 244
 245         /** Get the local port of the socket. Usually used after bind().
 246             @return the port number or OSL_INVALID_PORT on errors.
 247         */
 248         inline sal_Int32    SAL_CALL getLocalPort() const;
 249
 250         /** Get the hostname for the local interface.
 251             @return the hostname or an empty string ("").
 252         */
 253         inline ::rtl::OUString SAL_CALL getLocalHost() const;
 254
 255         /** Retrieves the address of the remote host of this socket.
 256             @param Addr [out] receives the address.
 257         */
 258         inline void SAL_CALL getPeerAddr( SocketAddr & Addr) const;
 259
 260         /** Get the remote port of the socket.
 261             @return the port number or OSL_INVALID_PORT on errors.
 262         */
 263         inline sal_Int32    SAL_CALL getPeerPort() const;
 264
 265         /** Get the hostname for the remote interface.
 266             @return the hostname or an empty string ("").
 267         */
 268         inline ::rtl::OUString SAL_CALL getPeerHost() const;
 269
 270         /** Binds the socket to the specified (local) interface.
 271             @param LocalInterface Address of the Interface
 272             @return True if bind was successful.
 273         */
 274         inline bool SAL_CALL bind(const SocketAddr& LocalInterface);
 275
 276         /** Checks if read operations will block.
 277
 278             You can specify a timeout-value in seconds/nanoseconds that denotes
 279             how the operation will block if the Socket is not ready.
 280             @return <code>true</code> if read operations (recv, recvFrom, accept) on the Socket
 281             will NOT block; <code>false</code> if it would block or if an error occurred.
 282
 283             @param pTimeout if 0, the operation will block without a timeout. Otherwise
 284             the specified amount of time.
 285         */
 286         inline bool SAL_CALL isRecvReady(const TimeValue *pTimeout = NULL) const;
 287
 288         /** Checks if send operations will block.
 289
 290             You can specify a timeout-value in seconds/nanoseconds that denotes
 291             how the operation will block if the Socket is not ready.
 292             @return <code>true</code> if send operations (send, sendTo) on the Socket
 293             will NOT block; <code>false</code> if it would block or if an error occurred.
 294
 295             @param pTimeout if 0, the operation will block without a timeout. Otherwise
 296             the specified amount of time.
 297         */
 298         inline bool SAL_CALL isSendReady(const TimeValue *pTimeout = NULL) const;
 299
 300
 301         /** Checks if a request for out-of-band data will block.
 302
 303             You can specify a timeout-value in seconds/nanoseconds that denotes
 304             how the operation will block if the Socket has no pending OOB data.
 305
 306             @return <code>true</code> if OOB-request operations (recv with appropriate flags)
 307             on the Socket will NOT block; <code>false</code> if it would block or if
 308             an error occurred.
 309
 310             @param pTimeout if 0, the operation will block without a timeout. Otherwise
 311             the specified amount of time.
 312         */
 313         inline bool SAL_CALL isExceptionPending(const TimeValue *pTimeout = NULL) const;
 314
 315
 316         /** Queries the socket for its type.
 317             @return one of:
 318             <ul>
 319             <li> <code>osl_Socket_TypeStream</code>
 320             <li> <code>osl_Socket_TypeDgram</code>
 321             <li> <code>osl_Socket_TypeRaw</code>
 322             <li> <code>osl_Socket_TypeRdm</code>
 323             <li> <code>osl_Socket_TypeSeqPacket</code>
 324             <li> <code>osl_invalid_SocketType</code>, if an error occurred
 325             </ul>
 326         */
 327         inline oslSocketType    SAL_CALL getType() const;
 328
 329         /** Retrieves option-attributes associated with the socket.
 330             @param Option The attribute to query.
 331             Valid values (depending on the Level) are:
 332             <ul>
 333             <li> <code>osl_Socket_Option_Debug</code><br>
 334                  (sal_Bool) Socket debug flag 1 = enabled, 0 = disabled.
 335
 336             <li> <code>osl_Socket_OptionAcceptConn</code><br>
 337             <li> <code>osl_Socket_OptionReuseAddr</code><br>
 338               (sal_Bool) Allows the socket to be bound to an address that is
 339               already in use.
 340               1 = multiple bound allowed, 0 = no multiple bounds allowed
 341
 342             <li><code>osl_Socket_OptionKeepAlive</code><br>
 343                (sal_Bool) Keepalive packets are sent by the underlying socket.
 344                1 = enabled, 0 = disabled
 345
 346             <li><code>osl_Socket_OptionDontRoute</code><br>
 347                (sal_Bool) Do not route: send directly to interface.
 348                   1 = do not route , 0 = routing possible
 349
 350             <li><code>osl_Socket_OptionBroadcast</code><br>
 351                (sal_Bool) Transmission of broadcast messages are allowed on the socket.
 352                1 = transmission allowed, 0 = transmission disallowed
 353
 354             <li><code>osl_Socket_OptionUseLoopback</code><br>
 355
 356             <li><code>osl_Socket_OptionLinger</code><br>
 357                (linger) Linger on close if unsent data is present.
 358                linger has two members: l_onoff, l_linger
 359                l_onoff = 0 is off, l_onoff > 0 and l_linger= timeout in seconds.
 360
 361             <li><code>osl_Socket_OptionOOBinLine</code><br>
 362
 363
 364             <li><code>osl_Socket_OptionSndBuf</code><br>
 365               (sal_Int32) Size of the send buffer in bytes. Data is sent after
 366               SndTimeo or when the buffer is full. This allows faster writing
 367               to the socket.
 368
 369             <li><code>osl_Socket_OptionRcvBuf</code><br>
 370               (sal_Int32) Size of the receive buffer in bytes. Data is sent after
 371               SndTimeo or when the buffer is full. This allows faster writing
 372               to the socket and larger packet sizes.
 373
 374             <li><code>osl_Socket_OptionSndLowat</code><br>
 375
 376             <li><code>osl_Socket_OptionRcvLowat</code><br>
 377
 378             <li><code>osl_Socket_OptionSndTimeo</code><br>
 379               (sal_Int32) Data is sent after this timeout. This allows gathering
 380               of data to send larger packages but increases latency times.
 381
 382             <li><code>osl_Socket_OptionRcvTimeo</code><br>
 383
 384             <li><code>osl_Socket_OptionError</code><br>
 385             <li><code>osl_Socket_OptionType</code><br>
 386
 387             <li><code>osl_Socket_OptionTcpNoDelay</code><br>
 388               Disables the Nagle algorithm for send coalescing. (Do not
 389               collect data until a packet is full, instead send immediately.
 390               This increases network traffic but might improve latency-times.)
 391               1 = disables the algorithm, 0 = keeps it enabled.
 392             </ul>
 393
 394               If not above mentioned otherwise, the options are only valid for
 395               level <code>osl_Socket_LevelSocket</code>.
 396             @param pBuffer The Buffer will be filled with the attribute.
 397
 398             @param BufferLen The size of pBuffer.
 399
 400             @param Level The option level.
 401
 402             Valid values are:
 403             <ul>
 404             <li><code>osl_Socket_LevelSocket</code> : Socket Level
 405             <li><code>osl_Socket_LevelTcp</code>    : Level of Transmission Control Protocol
 406             </ul>
 407             @return The size of the attribute copied into pBuffer or -1 if an error
 408             occurred.
 409         */
 410         inline sal_Int32 SAL_CALL getOption(
 411             oslSocketOption Option,
 412             void* pBuffer,
 413             sal_uInt32 BufferLen,
 414             oslSocketOptionLevel Level= osl_Socket_LevelSocket) const;
 415
 416         /** Sets the sockets attributes.
 417
 418             @param Option denotes the option to modify.
 419             Valid values (depending on the Level) are:
 420             <ul>
 421             <li> osl_Socket_Option_Debug
 422             <li> osl_Socket_OptionAcceptConn
 423             <li> osl_Socket_OptionReuseAddr
 424             <li> osl_Socket_OptionKeepAlive
 425             <li> osl_Socket_OptionDontRoute
 426             <li> osl_Socket_OptionBroadcast
 427             <li> osl_Socket_OptionUseLoopback
 428             <li> osl_Socket_OptionLinger
 429             <li> osl_Socket_OptionOOBinLine
 430             <li> osl_Socket_OptionSndBuf
 431             <li> osl_Socket_OptionRcvBuf
 432             <li> osl_Socket_OptionSndLowat
 433             <li> osl_Socket_OptionRcvLowat
 434             <li> osl_Socket_OptionSndTimeo
 435             <li> osl_Socket_OptionRcvTimeo
 436             <li> osl_Socket_OptionError
 437             <li> osl_Socket_OptionType
 438             <li> osl_Socket_OptionTcpNoDelay
 439             </ul>
 440
 441             If not above mentioned otherwise, the options are only valid for
 442             level osl_Socket_LevelSocket.
 443
 444             @param pBuffer Pointer to a Buffer which contains the attribute-value.
 445
 446             @param BufferLen contains the length of the Buffer.
 447
 448             @param Level selects the level for which an option should be changed.
 449             Valid values are:
 450             <ul>
 451             <li> osl_Socket_evel_Socket : Socket Level
 452             <li> osl_Socket_Level_Tcp   : Level of Transmission Control Protocol
 453             </ul>
 454
 455             @return True if the option could be changed.
 456         */
 457         inline bool SAL_CALL setOption( oslSocketOption Option,
 458                                             void* pBuffer,
 459                                             sal_uInt32 BufferLen,
 460                                             oslSocketOptionLevel Level= osl_Socket_LevelSocket ) const;
 461
 462         /** Convenience function for setting sal_Bool and sal_Int32 option values.
 463             @see setOption()
 464          */
 465         inline bool setOption( oslSocketOption option, sal_Int32 nValue  );
 466
 467         /** Convenience function for retrieving sal_Bool and sal_Int32 option values.
 468             @see setOption()
 469          */
 470         inline sal_Int32 getOption( oslSocketOption option ) const;
 471
 472         /** Enables/disables non-blocking mode of the socket.
 473             @param bNonBlockingMode If <code>true</code>, blocking mode will be switched off
 474                    If <code>false</code>, the socket will become a blocking
 475                    socket (which is the default behaviour of a socket).
 476             @return <code>true</code> if mode could be set.
 477         */
 478         inline bool SAL_CALL enableNonBlockingMode( bool bNonBlockingMode);
 479
 480         /** Query blocking mode of the socket.
 481             @return <code>true</code> if non-blocking mode is set.
 482         */
 483         inline bool SAL_CALL isNonBlockingMode() const;
 484
 485
 486         /** clears the error status
 487         */
 488         inline void SAL_CALL clearError() const;
 489
 490         /** returns a constant describing the last error for the socket system.
 491
 492             @return osl_Socket_E_NONE if no error occurred, invalid_SocketError if
 493             an unknown (unmapped) error occurred, otherwise an enum describing the
 494             error.
 495             @see osl_getLastSocketError()
 496         */
 497         inline oslSocketError getError() const;
 498
 499         /** Builds a string with the last error-message for the socket.
 500          */
 501         inline ::rtl::OUString getErrorAsString( ) const;
 502
 503         /** Returns the underlying handle unacquired  (The caller must acquire it to keep it).
 504          */
 505         inline oslSocket getHandle() const;
 506     };
 507
 508
 509     class StreamSocket : public Socket
 510     {
 511     public:
 512         /** Creates a socket.
 513             @param Family the Family of the socket (Inet by default)
 514             @param Protocol the Protocon of the socket (IP by default)
 515             @param Type For some protocols it might be desirable to
 516             use a different type than <code>osl_Socket_TypeStream</code>
 517             (like <code>osl_Socket_TypeSeqPacket</code>).
 518             Therefore this parameter is not hidden.
 519         */
 520           inline StreamSocket(oslAddrFamily Family = osl_Socket_FamilyInet,
 521                             oslProtocol Protocol = osl_Socket_ProtocolIp,
 522                             oslSocketType   Type = osl_Socket_TypeStream);
 523
 524         inline StreamSocket( const StreamSocket & );
 525
 526         inline StreamSocket( oslSocket Socket , __sal_NoAcquire noacquire );
 527
 528         inline StreamSocket( oslSocket Socket );
 529
 530         /** Retrieves n bytes from the stream and copies them into pBuffer.
 531             The method avoids incomplete reads due to packet boundaries and is thus
 532             blocking.
 533             @param pBuffer receives the read data. pBuffer must be large enough
 534             to hold n bytes.
 535             @param n the number of bytes to read.
 536             @return the number of read bytes. The number will only be smaller than
 537             n if an exceptional condition (e.g. connection closed) occurs.
 538         */
 539         inline sal_Int32 SAL_CALL read(void* pBuffer, sal_uInt32 n);
 540
 541         /** Writes n bytes from pBuffer to the stream. The method avoids
 542             incomplete writes due to packet boundaries and is thus blocking.
 543             @param pBuffer contains the data to be written.
 544             @param n the number of bytes to write.
 545             @return the number of written bytes. The number will only be smaller than
 546             n if an exceptional condition (e.g. connection closed) occurs.
 547         */
 548         inline sal_Int32 SAL_CALL write(const void* pBuffer, sal_uInt32 n);
 549
 550
 551         /** Tries to receive BytesToRead data from the connected socket,
 552
 553             @param[out] pBuffer Points to a buffer that will be filled with the received
 554             data. pBuffer must have at least have a size of BytesToRead.
 555             @param[in] BytesToRead The number of bytes to read.
 556             @param[in] flags Modifier for the call. Valid values are:
 557
 558             <ul>
 559             <li><code>osl_Socket_MsgNormal</code>
 560             <li><code>osl_Socket_MsgOOB</code>
 561             <li><code>osl_Socket_MsgPeek</code>
 562             <li><code>osl_Socket_MsgDontRoute</code>
 563             <li><code>osl_Socket_MsgMaxIOVLen</code>
 564             </ul>
 565             @return the number of received bytes, which may be less than BytesToRead.
 566         */
 567         inline sal_Int32 SAL_CALL recv(void* pBuffer,
 568                                        sal_uInt32 BytesToRead,
 569                                        oslSocketMsgFlag flags= osl_Socket_MsgNormal);
 570
 571         /** Tries to send BytesToSend data to the connected socket.
 572
 573             @param pBuffer [in] Points to a buffer that contains the send-data.
 574             @param BytesToSend [in] The number of bytes to send. pBuffer must have at least
 575             this size.
 576             @param Flag [in] Modifier for the call. Valid values are:
 577             <ul>
 578             <li><code>osl_Socket_MsgNormal</code>
 579             <li><code>osl_Socket_MsgOOB</code>
 580             <li><code>osl_Socket_MsgPeek</code>
 581             <li><code>osl_Socket_MsgDontRoute</code>
 582             <li><code>osl_Socket_MsgMaxIOVLen</code>
 583             </ul>
 584
 585             @return the number of transferred bytes. It may be less than BytesToSend.
 586         */
 587         sal_Int32 SAL_CALL send(const void* pBuffer,
 588                                 sal_uInt32 BytesToSend,
 589                                 oslSocketMsgFlag= osl_Socket_MsgNormal);
 590     };
 591
 592     class ConnectorSocket : public StreamSocket
 593     {
 594     public:
 595         /** Creates a socket that can connect to a (remote) host.
 596             @param Family the Family of the socket (Inet by default)
 597             @param Protocol the Protocon of the socket (IP by default)
 598             @param Type For some protocols it might be desirable to
 599             use a different type than sock_stream <code>osl_Socket_TypeSeqPacket</code>
 600             (like <code>osl_Socket_TypeSeqPacket</code>).
 601             Therefore we do not hide this parameter here.
 602         */
 603           ConnectorSocket(oslAddrFamily Family = osl_Socket_FamilyInet,
 604                         oslProtocol Protocol = osl_Socket_ProtocolIp,
 605                         oslSocketType   Type = osl_Socket_TypeStream);
 606
 607
 608         /** Connects the socket to a (remote) host.
 609             @param TargetHost The address of the target.
 610             @param pTimeout The timeout for blocking. If 0, a default system dependent timeout
 611                             us used.
 612             @return <code> osl_Socket_Ok</code> if connected successfully,
 613             <code>osl_Socket_TimedOut</code> on timeout,
 614             <code>osl_Socket_Interrupted</code> if unblocked forcefully (by osl::Socket::close()),
 615             <code>osl_Socket_Error</code> if connect failed.
 616         */
 617         oslSocketResult SAL_CALL connect(const SocketAddr& TargetHost, const TimeValue* pTimeout = NULL);
 618     };
 619
 620     /** Allows to accept socket connections.
 621      */
 622     class AcceptorSocket : public Socket
 623     {
 624     public:
 625         inline AcceptorSocket(oslAddrFamily Family = osl_Socket_FamilyInet,
 626                               oslProtocol   Protocol = osl_Socket_ProtocolIp,
 627                               oslSocketType Type = osl_Socket_TypeStream);
 628
 629         /** Prepare a socket for the accept-call. The socket must have been
 630             bound before to the local address.
 631             @param MaxPendingConnections The maximum number of pending
 632             connections (waiting to be accepted) on this socket. If you use
 633             -1, a system default value is used.
 634             @return <code>true</code> if call was successful.
 635         */
 636         inline bool SAL_CALL listen(sal_Int32 MaxPendingConnections= -1);
 637
 638         /** Accepts incoming connections on the socket. You must
 639             precede this call with osl::Socket::bind() and listen().
 640             @param Connection receives the incoming connection.
 641             @return <code>osl_Socket_Ok</code>, if a connection has been accepted,
 642             <code>osl_Socket_TimedOut</code>, if m_RecvTimeout milliseconds passed without connect,
 643             <code>osl_Socket_Error</code> on errors.
 644         */
 645         inline oslSocketResult SAL_CALL acceptConnection( StreamSocket& Connection);
 646
 647         /** Accepts incoming connections on the socket. You must
 648             precede this call with osl::Socket::bind() and listen().
 649             @param PeerAddr receives the address of the connecting entity
 650             (your communication partner).
 651             @param Connection receives the incoming connection.
 652             @return <code>osl_Socket_Ok</code>, if a connection has been accepted,
 653             <code>osl_Socket_TimedOut</code>, if m_RecvTimeout milliseconds passed without connect,
 654             <code>osl_Socket_Error</code> on errors.
 655         */
 656         inline oslSocketResult SAL_CALL acceptConnection( StreamSocket& Connection, SocketAddr & PeerAddr);
 657     };
 658
 659
 660     /** A connectionless socket to send and receive datagrams.
 661      */
 662     class DatagramSocket : public Socket
 663     {
 664     public:
 665
 666         /** Creates a datagram socket.
 667             @param Family the Family of the socket (Inet by default)
 668             @param Protocol the Protocon of the socket (IP by default)
 669             @param Type is sock_dgram by default.
 670         */
 671         inline DatagramSocket(oslAddrFamily Family= osl_Socket_FamilyInet,
 672                               oslProtocol   Protocol= osl_Socket_ProtocolIp,
 673                               oslSocketType Type= osl_Socket_TypeDgram);
 674
 675         /** Tries to receives BufferSize data from the socket, if no error occurs.
 676
 677             @param pSenderAddr [out] You must provide pointer to a SocketAddr.
 678             It will be  filled with the address of the datagrams sender.
 679             If pSenderAddr is 0, it is ignored.
 680             @param pBuffer [out] Points to a buffer that will be filled with the received
 681             datagram.
 682             @param BufferSize [in] The size of pBuffer.
 683             @param Flag [in] Modifier for the call. Valid values are:
 684             <ul>
 685             <li><code>osl_Socket_MsgNormal</code>
 686             <li><code>osl_Socket_MsgOOB</code>
 687             <li><code>osl_Socket_MsgPeek</code>
 688             <li><code>osl_Socket_MsgDontRoute</code>
 689             <li><code>osl_Socket_MsgMaxIOVLen</code>
 690             </ul>
 691
 692             @return the number of received bytes.
 693         */
 694         inline sal_Int32 SAL_CALL recvFrom(void*  pBuffer,
 695                                            sal_uInt32 BufferSize,
 696                                            SocketAddr* pSenderAddr= NULL,
 697                                            oslSocketMsgFlag Flag= osl_Socket_MsgNormal);
 698
 699         /** Tries to send one datagram with BytesToSend size to the given ReceiverAddr.
 700             Since there is only send one packet, the function doesn't care about
 701             packet boundaries.
 702
 703             @param ReceiverAddr [in] A SocketAddr that contains
 704             the destination address for this send.
 705
 706             @param pBuffer [in] Points to a buffer that contains the send-data.
 707             @param BufferSize [in] The number of bytes to send. pBuffer must have at least
 708             this size.
 709             @param Flag [in] Modifier for the call. Valid values are:
 710
 711             <ul>
 712             <li><code>osl_Socket_MsgNormal</code>
 713             <li><code>osl_Socket_MsgOOB</code>
 714             <li><code>osl_Socket_MsgPeek</code>
 715             <li><code>osl_Socket_MsgDontRoute</code>
 716             <li><code>osl_Socket_MsgMaxIOVLen</code>
 717             </ul>
 718
 719             @return the number of transferred bytes.
 720         */
 721         inline sal_Int32    SAL_CALL sendTo( const SocketAddr& ReceiverAddr,
 722                                              const void* pBuffer,
 723                                              sal_uInt32 BufferSize,
 724                                              oslSocketMsgFlag Flag= osl_Socket_MsgNormal);
 725     };
 726
 727 }
 728
 729 #endif
 730
 731 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */