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 rev 43302 10 * src/kits/network/libnetapi/AbstractSocket.cpp rev 43302 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 includes datagrams, TCP sockets and SSL 26 secure sockets. 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 New subclasses of BAbstractSocket may be created to allow communication 33 using more protocols. 34*/ 35 36/*! 37 \fn BAbstractSocket::BAbstractSocket() 38 \brief Default constructor. 39 40 The socket is disconnected and unbound, and the status is B_NO_INIT. 41 Use Bind or Connect to initialize it. 42*/ 43 44/*! 45 \fn BAbstractSocket::BAbstractSocket(const BAbstractSocket& other) 46 \brief Copy constructor 47 48 There is no new connection to the server. Instead, data sent using several 49 copy of the class will be intermixed, and the first instance to read data 50 will steal it from the others. 51 52 This is probably not what you want, unless you work with datagrams. In 53 that case, the messages read and written are atomic and can be safely sent 54 and received from different places. 55*/ 56 57/*! 58 \fn BAbstractSocket::~BAbstractSocket() 59 \brief Destructor 60 61 Disconnects the socket by calling Disconnect(). 62*/ 63 64/*! 65 \fn status_t BAbstractSocket::InitCheck() const 66 \brief Check connection status 67 68 \returns B_OK if the connection is working, or an error code if something 69 went wrong. 70*/ 71 72/*! 73 \fn bool BAbstractSocket::IsBound() const 74 75 A socket becomes bound when Bind succeeds, and stops being bound when 76 Disconnect is called. 77 78 \returns wether the socket is currently bound 79*/ 80 81/*! 82 \fn bool BAbstractSocket::IsConnected() const 83 84 A socket becomes connected when Connect succeeds, and disconnected when 85 Disconnect is called. 86 87 \returns wether the socket is currently connected 88*/ 89 90/*! 91 \fn void BAbstractSocket::Disconnect() 92 \brief Close the connection 93 94 The socket becomes disconnected and unbound. You can Connect or Bind it 95 again, either to the same or another peer. 96*/ 97 98/*! 99 \fn status_t BAbstractSocket::SetTimeout(bigtime_t timeout) 100 \brief sets the read and write timeout 101 102 A negative value disables timeouts, so the Read and Write calls will wait 103 until data is available or can be sent. 104 105 \param timeout The timeout in microseconds, or B_INFINITE_TIMEOUT. 106*/ 107 108/*! 109 \fn bigtime_t BAbstractSocket::Timeout() const 110 \brief gets the socket timeout 111 112 \returns the timeout in microseconds, or B_INFINITE_TIMEOUT 113*/ 114 115/*! 116 \fn const BNetworkAddress& BAbstractSocket::Local() const 117 \brief gets the local address for this socket 118 119 This gives useful results only if the socket is either connected or bound. 120 Otherwise, an uninitialized address is returned. 121*/ 122 123/*! 124 \fn const BNetworkAddress& BAbstractSocket::Peer() const 125 \brief gets the peer address 126 127 This gives useful results only if the socket is either connected or bound. 128 Otherwise, an uninitialized address is returned. 129*/ 130 131/*! 132 \fn size_t BAbstractSocket::MaxTransmissionSize() const 133 \brief Return the maximal size of a transmission on this socket. 134 135 The default implementation always returns SSIZE_MAX, but subclasses may 136 restrict this to a smaller size. 137*/ 138 139/*! 140 \fn status_t BAbstractSocket::WaitForReadable(bigtime_t timeout) const 141 \brief wait for incoming data 142 143 Wait until data comes in, or the timeout expires. After this function 144 returns B_OK, Read can be called without blocking. 145 146 \param timeout the timeout in microseconds, or B_INFINITE_TIMEOUT 147 \returns B_OK when data is available, B_TIMED_OUT when the timeout expires, 148 or B_WOULD_BLOCK when the wait was interrupted for other reasons. 149*/ 150 151/*! 152 \fn status_t BAbstractSocket::WaitForWritable(bigtime_t timeout) const 153 \brief wait until writing is possible 154 155 Wait until the socket becomes ready for writing, or the timeout expires. 156 After this function returns B_OK, Write can be called without blocking. 157 158 \param timeout the timeout in microseconds, or B_INFINITE_TIMEOUT 159 \returns B_OK when the socket is ready to accept writes, B_TIMED_OUT when 160 the timeout expires, or B_WOULD_BLOCK when the wait was interrupted for 161 another reason. 162*/ 163 164/*! 165 \fn int BAbstractSocket::Socket() const 166 \brief get the underlying socket descriptor 167 168 The BSD socket descriptor can be used to modify advanced connection 169 paramters using the POSIX socket API. 170 171 \returns the socket descriptor 172*/ 173 174/*! 175 \fn status_t BAbstractSocket::Bind(const BNetworkAddress& local, int type) 176 \brief binds the socket to the given address 177 178 If the socket was already bound, the previous binding is removed. 179 180 \param local the local address to bind 181 \param type the socket type 182 \return B_OK on success, other error codes on error. 183*/ 184 185/*! 186 \fn status_t BAbstractSocket::Connect(const BNetworkAddress& peer, 187 int type, bigtime_t timeout) 188 \brief Connect the socket to the given peer. 189 190 The socket is disconnected from any previous connections. 191 192 \param peer the peer to connect to 193 \param type the socket type 194 \param timeout The timeout in microseconds or B_INFINITE_TIMEOUT. This is 195 used for subsequent reads and writes as well. 196*/ 197