1/* 2 * Copyright 2013 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Adrien Destugues, pulkomandy@pulkomandy.tk 7 * 8 * Corresponds to: 9 * headers/os/net/AbstractSocket.h hrev50265 10 * src/kits/network/libnetapi/AbstractSocket.cpp hrev50265 11 */ 12 13/*! 14 \file AbstractSocket.h 15 \ingroup network 16 \brief Provides the BAbstractSocket interface. 17*/ 18 19/*! 20 \class BAbstractSocket 21 \ingroup network 22 \brief Abstract interface for all socket connections. 23 24 BAbstractSocket provides a common interface for all socket-based 25 communication streams. These include BDatagramSocket, BSocket, 26 BSecureSocket and BServerSocket. 27 28 BAbstractSocket implements common behavior between these different socket 29 types. This includes management of a BSD socket integer handle, knowledge 30 of the local and remote network addresses, as well as the connection state. 31*/ 32 33/*! 34 \fn BAbstractSocket::BAbstractSocket() 35 \brief Default constructor. 36 37 Creates an uninitialized socket in disconnected and unbound state. 38*/ 39 40/*! 41 \fn BAbstractSocket::BAbstractSocket(const BAbstractSocket& other) 42 \brief Copy constructor 43 44 The copied object accesses the same underlying socket. 45*/ 46 47/*! 48 \fn BAbstractSocket::~BAbstractSocket() 49 \brief Destructor 50 51*/ 52 53/*! 54 \fn status_t BAbstractSocket::InitCheck() const 55 \brief Check connection status 56 57 \returns B_OK if the connection is working, or an error code if something 58 went wrong. 59*/ 60 61/*! 62 \fn bool BAbstractSocket::IsBound() const 63 64 A socket becomes bound when Bind succeeds, and stops being bound when 65 Disconnect is called. 66 67 \returns wether the socket is currently bound 68*/ 69 70/*! 71 \fn bool BAbstractSocket::IsConnected() const 72 73 A socket becomes connected when Connect succeeds, and disconnected when 74 Disconnect is called. 75 76 \returns wether the socket is currently connected 77*/ 78 79/*! 80 \fn void BAbstractSocket::Disconnect() 81 \brief Close the connection 82 83 The socket becomes disconnected and unbound. You can Connect or Bind it 84 again, either to the same or another peer. 85*/ 86 87/*! 88 \fn status_t BAbstractSocket::SetTimeout(bigtime_t timeout) 89 \brief sets the read and write timeout 90 91 A negative value disables timeouts, so the Read and Write calls will wait 92 until data is available or can be sent. 93 94 \param timeout The timeout in microseconds, or B_INFINITE_TIMEOUT. 95*/ 96 97/*! 98 \fn bigtime_t BAbstractSocket::Timeout() const 99 \brief gets the socket timeout 100 101 \returns the timeout in microseconds, or B_INFINITE_TIMEOUT 102*/ 103 104/*! 105 \fn const BNetworkAddress& BAbstractSocket::Local() const 106 \brief gets the local address for this socket 107 108 This gives useful results only if the socket is either connected or bound. 109 Otherwise, an uninitialized address is returned. 110*/ 111 112/*! 113 \fn const BNetworkAddress& BAbstractSocket::Peer() const 114 \brief gets the peer address 115 116 This gives useful results only if the socket is either connected or bound. 117 Otherwise, an uninitialized address is returned. 118*/ 119 120/*! 121 \fn size_t BAbstractSocket::MaxTransmissionSize() const 122 \brief Return the maximal size of a transmission on this socket. 123 124 The default implementation always returns SSIZE_MAX, but subclasses may 125 restrict this to a smaller size. 126*/ 127 128/*! 129 \fn status_t BAbstractSocket::WaitForReadable(bigtime_t timeout) const 130 \brief wait for incoming data 131 132 Wait until data comes in, or the timeout expires. After this function 133 returns B_OK, Read can be called without blocking. 134 135 \param timeout the timeout in microseconds, or B_INFINITE_TIMEOUT 136 \returns B_OK when data is available, B_TIMED_OUT when the timeout expires, 137 or B_WOULD_BLOCK when the wait was interrupted for other reasons. 138*/ 139 140/*! 141 \fn status_t BAbstractSocket::WaitForWritable(bigtime_t timeout) const 142 \brief wait until writing is possible 143 144 Wait until the socket becomes ready for writing, or the timeout expires. 145 After this function returns B_OK, Write can be called without blocking. 146 147 \param timeout the timeout in microseconds, or B_INFINITE_TIMEOUT 148 \returns B_OK when the socket is ready to accept writes, B_TIMED_OUT when 149 the timeout expires, or B_WOULD_BLOCK when the wait was interrupted for 150 another reason. 151*/ 152 153/*! 154 \fn int BAbstractSocket::Socket() const 155 \brief get the underlying socket descriptor 156 157 The BSD socket descriptor can be used to modify advanced connection 158 paramters using the POSIX socket API. 159 160 \returns the socket descriptor 161*/ 162 163/*! 164 \fn status_t BAbstractSocket::Bind(const BNetworkAddress& local, 165 bool reuseAddr, int type) 166 \brief binds the socket to the given address 167 168 If the socket was already bound, the previous binding is removed. 169 170 \param local the local address to bind 171 \param reuseAddr if \c true, non-zero requests reuse \a local address 172 \param type the socket type 173 \return B_OK on success, other error codes on error. 174*/ 175 176/*! 177 \fn status_t BAbstractSocket::Connect(const BNetworkAddress& peer, 178 int type, bigtime_t timeout) 179 \brief Connect the socket to the given peer. 180 181 The socket is disconnected from any previous connections. 182 183 \param peer the peer to connect to 184 \param type the socket type 185 \param timeout The timeout in microseconds or B_INFINITE_TIMEOUT. This is 186 used for subsequent reads and writes as well. 187*/ 188