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 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, int type) 165 \brief binds the socket to the given address 166 167 If the socket was already bound, the previous binding is removed. 168 169 \param local the local address to bind 170 \param type the socket type 171 \return B_OK on success, other error codes on error. 172*/ 173 174/*! 175 \fn status_t BAbstractSocket::Connect(const BNetworkAddress& peer, 176 int type, bigtime_t timeout) 177 \brief Connect the socket to the given peer. 178 179 The socket is disconnected from any previous connections. 180 181 \param peer the peer to connect to 182 \param type the socket type 183 \param timeout The timeout in microseconds or B_INFINITE_TIMEOUT. This is 184 used for subsequent reads and writes as well. 185*/ 186