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