diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index 5d1d84d7d2..5e174f05d1 100644 --- a/docs/user/Doxyfile +++ b/docs/user/Doxyfile @@ -639,6 +639,7 @@ INPUT = . \ media \ midi \ midi2 \ + net \ posix \ storage \ support \ @@ -652,6 +653,7 @@ INPUT = . \ ../../headers/os/locale \ ../../headers/os/media \ ../../headers/os/midi2 \ + ../../headers/os/net \ ../../headers/os/storage \ ../../headers/os/support \ ../../headers/os/translation \ diff --git a/docs/user/book.dox b/docs/user/book.dox index 8d7db458fe..388478a6a2 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -48,6 +48,8 @@ - The \ref midi2 describes an interface to generating, processing, and playing music in MIDI format. For reference documentation on the \ref midi1 is also included. + - The \ref network handles everything network related, from interface + IP address settings to HTTP connections. - The \ref storage is a collection of classes that deal with storing and retrieving information from disk. - The \ref support contains support classes to use in your application @@ -469,6 +471,8 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE); \defgroup libmidi2 (libmidi2.so) + \defgroup network Network Kit + \brief Classes that deal with all network connections and communications. \defgroup storage Storage Kit \brief Collection of classes that deal with storing and retrieving @@ -570,4 +574,4 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE); ///// Special Topics ///// \defgroup drivers Device Drivers -\defgroup keyboard Keyboard \ No newline at end of file +\defgroup keyboard Keyboard diff --git a/docs/user/net/AbstractSocket.dox b/docs/user/net/AbstractSocket.dox new file mode 100644 index 0000000000..ceb3893390 --- /dev/null +++ b/docs/user/net/AbstractSocket.dox @@ -0,0 +1,196 @@ +/* + * Copyright 2013 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Adrien Destugues, pulkomandy@pulkomandy.tk + * + * Corresponds to: + * headers/os/net/AbstractSocket.h rev 43302 + * src/kits/network/libnetapi/AbstractSocket.cpp rev 43302 + */ + +/*! + \file AbstractSocket.h + \ingroup network + \brief Provides the BAbstractSocket interface. +*/ + +/*! + \class BAbstractSocket + \ingroup network + \brief Abstract interface for all socket connections. + + BAbstractSocket provides a common interface for all socket-based + communication streams. These includes datagrams, TCP sockets and SSL + secure sockets. + + BAbstractSocket implements common behavior between these different socket + types. This includes management of a BSD socket integer handle, knowledge + of the local and remote network addresses, as well as the connection state. + + New subclasses of BAbstractSocket may be created to allow communication + using more protocols. +*/ + +/*! + \fn BAbstractSocket::BAbstractSocket() + \brief Default constructor. + + The socket is disconnected and unbound, and the status is B_NO_INIT. + Use Bind or Connect to initialize it. +*/ + +/*! + \fn BAbstractSocket::BAbstractSocket(const BAbstractSocket& other) + \brief Copy constructor + + There is no new connection to the server. Instead, data sent using several + copy of the class will be intermixed, and the first instance to read data + will steal it from the others. + + This is probably not what you want, unless you work with datagrams. In + that case, the messages read and written are atomic and can be safely sent + and received from different places. +*/ + +/*! + \fn BAbstractSocket::~BAbstractSocket() + \brief Destructor + + Disconnects the socket by calling Disconnect(). +*/ + +/*! + \fn status_t BAbstractSocket::InitCheck() const + \brief Check connection status + + \returns B_OK if the connection is working, or an error code if something + went wrong. +*/ + +/*! + \fn bool BAbstractSocket::IsBound() const + + A socket becomes bound when Bind succeeds, and stops being bound when + Disconnect is called. + + \returns wether the socket is currently bound +*/ + +/*! + \fn bool BAbstractSocket::IsConnected() const + + A socket becomes connected when Connect succeeds, and disconnected when + Disconnect is called. + + \returns wether the socket is currently connected +*/ + +/*! + \fn void BAbstractSocket::Disconnect() + \brief Close the connection + + The socket becomes disconnected and unbound. You can Connect or Bind it + again, either to the same or another peer. +*/ + +/*! + \fn status_t BAbstractSocket::SetTimeout(bigtime_t timeout) + \brief sets the read and write timeout + + A negative value disables timeouts, so the Read and Write calls will wait + until data is available or can be sent. + + \param timeout The timeout in microseconds, or B_INFINITE_TIMEOUT. +*/ + +/*! + \fn bigtime_t BAbstractSocket::Timeout() const + \brief gets the socket timeout + + \returns the timeout in microseconds, or B_INFINITE_TIMEOUT +*/ + +/*! + \fn const BNetworkAddress& BAbstractSocket::Local() const + \brief gets the local address for this socket + + This gives useful results only if the socket is either connected or bound. + Otherwise, an uninitialized address is returned. +*/ + +/*! + \fn const BNetworkAddress& BAbstractSocket::Peer() const + \brief gets the peer address + + This gives useful results only if the socket is either connected or bound. + Otherwise, an uninitialized address is returned. +*/ + +/*! + \fn size_t BAbstractSocket::MaxTransmissionSize() const + \brief Return the maximal size of a transmission on this socket. + + The default implementation always returns SSIZE_MAX, but subclasses may + restrict this to a smaller size. +*/ + +/*! + \fn status_t BAbstractSocket::WaitForReadable(bigtime_t timeout) const + \brief wait for incoming data + + Wait until data comes in, or the timeout expires. After this function + returns B_OK, Read can be called without blocking. + + \param timeout the timeout in microseconds, or B_INFINITE_TIMEOUT + \returns B_OK when data is available, B_TIMED_OUT when the timeout expires, + or B_WOULD_BLOCK when the wait was interrupted for other reasons. +*/ + +/*! + \fn status_t BAbstractSocket::WaitForWritable(bigtime_t timeout) const + \brief wait until writing is possible + + Wait until the socket becomes ready for writing, or the timeout expires. + After this function returns B_OK, Write can be called without blocking. + + \param timeout the timeout in microseconds, or B_INFINITE_TIMEOUT + \returns B_OK when the socket is ready to accept writes, B_TIMED_OUT when + the timeout expires, or B_WOULD_BLOCK when the wait was interrupted for + another reason. +*/ + +/*! + \fn int BAbstractSocket::Socket() const + \brief get the underlying socket descriptor + + The BSD socket descriptor can be used to modify advanced connection + paramters using the POSIX socket API. + + \returns the socket descriptor +*/ + +/*! + \fn status_t BAbstractSocket::Bind(const BNetworkAddress& local, int type) + \brief binds the socket to the given address + + If the socket was already bound, the previous binding is removed. + + \param local the local address to bind + \param type the socket type + \return B_OK on success, other error codes on error. +*/ + +/*! + \fn status_t BAbstractSocket::Connect(const BNetworkAddress& peer, + int type, bigtime_t timeout) + \brief Connect the socket to the given peer. + + The socket is disconnected from any previous connections. + + \param peer the peer to connect to + \param type the socket type + \param timeout The timeout in microseconds or B_INFINITE_TIMEOUT. This is + used for subsequent reads and writes as well. +*/ diff --git a/docs/user/net/DatagramSocket.dox b/docs/user/net/DatagramSocket.dox new file mode 100644 index 0000000000..eef7b65524 --- /dev/null +++ b/docs/user/net/DatagramSocket.dox @@ -0,0 +1,169 @@ +/* + * Copyright 2013 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Adrien Destugues, pulkomandy@pulkomandy.tk + * + * Corresponds to: + * headers/os/net/DatagramSocket.h rev 43302 + * src/kits/network/libnetapi/DatagramSocket.cpp rev 43302 + */ + +/*! + \file DatagramSocket.h + \ingroup network + \brief BAbstractSocket implementation for UDP datagram connections. +*/ + +/*! + \class BDatagramSocket + \ingroup network + \brief BAbstractSocket implementation for UDP datagram connections. + + Datagrams are atomic messages. There is no notion of sequence and the data + sent in a sequence of Write calls may not get to the other end of the + connections in the same order. There is no flow control, so some of them + may not even make it to the peer. + + The main uses for datagram sockets are when performance is more important + than safety (the lack of acknowledge mechanism allows to send a lot of + datagram packets at once, whereas TCP is limited by its sliding window + mechanism), when the application wants to manage flow control and + acknowledges itself, and when lost packets don't matter (for example, in + a video stream, there is no use for receiving late video frames if they + were already skipped to play the following ones). + + To better match the atomic behavior of datagrams, this class provides + SendTo and ReceiveFrom methods. These allow to send datagrams to different + peers, and receive datagrams only from a single one at a time. This allows + the use of a single datagram connection to communicate with multiple peers + at the same time. +*/ + +/*! + \fn BDatagramSocket::BDatagramSocket() + \brief Default constructor. + + Does nothing. Call Bind or Connect to actually start network communications. + + \see BAbstractSocket::BAbstractSocket(). +*/ + +/*! + \fn BDatagramSocket::BDatagramSocket(const BNetworkAddress& peer, + bigtime_t timeout) + \brief Create and connect a datagram socket. + + The socket is immediately connected to the given peer. Use InitCheck to + make sure the connection was successful. + + \param peer host to connect to + \param timeout connection timeout, in microsecond. +*/ + +/*! + \fn BDatagramSocket::BDatagramSocket(const BDatagramSocket& other) + \brief Copy constructor. +*/ + +/*! + \fn BDatagramSocket::~BDatagramSocket() + \brief Destructor. + + The socket is disconnected. +*/ + +/*! + \fn BDatagramSocket::SetBroadcast(bool broadcast) + \brief enables or disable broadcast mode + + In broadcast mode, datagrams can be sent to multiple peers at once. + Calling this method is not enough, you must also set your peer address to + be INADDR_BROADCAST to effectively send a broadcast message. + + Note that broadcast messages usually don't propagate on Internet as they + would generate too much traffic. Their use is thus restricted to local + networks. + + \param broadcast the requested state for broadcast permissions. + \return B_OK on success, or other error codes on failure. +*/ + +/*! + \fn void BDatagramSocket::SetPeer(const BNetworkAddress& peer) + \brief Change the remote host for this connections. + + Datagram connections are not statically bound to a remote address, so it is + possible to change the destination of packets at runtime. + + Note that packets coming to the right local address, no matter where they + come from, will always be accepted. + + \param peer the address to which following Write calls will send datagrams +*/ + +/*! + \fn size_t BDatagramSocket::MaxTransmissionSize() const + + The maximum size for datagram sockets is 32768 bytes. + + \returns 32768 +*/ + +/*! + \fn ssize_t BDatagramSocket::SendTo(const BNetworkAddress& address, + const void* buffer, size_t size) + \brief Send a single datagram to the given address + + Unlike the Write method, which always sends to the same peer, this method + can be used to send messages to different destinations. + + \param address the host to send the datagram to + \param buffer datagram contents + \param size size of the buffer + \returns the number of bytes sent, which may be less than requested, or a + negative error code. +*/ + +/*! + \fn ssize_t BDatagramSocket::ReceiveFrom(void* buffer, size_t bufferSize, + BNetworkAddress& from) + \brief receive a single datagram from a given host + + Wait for a message to come from the given host and fill the buffer with it. + If the buffer is too small, extra bytes from the datagram will be lost. + + \param buffer the buffer to store the datagram in + \param bufferSize size of the buffer + \param from the datagram sneder address +*/ + +/*! + \fn ssize_t BDatagramSocket::Read(void* buffer, size_t size) + \brief Receive a datagram from any sender + + This is similar to ReceiveFrom, but does not allow filtering which host the + datagram comes from. The first message that comes in will be accepted. + + There is no way to know who sent the message. + + If the buffer is too small, the remaining part of the datagram is lost. + + \param buffer memory to store the datagram in + \param size the size of the buffer + \return the number of bytes actually written, or a negative error code. +*/ + +/*! + \fn ssize_t BDatagramSocket::Write(const void* buffer, size_t size) + \brief Send a datagram to the default target + + If the socket is connected, send a datagram to the connected host. + If it's not, send to the peer givento the SetPeer function. + + \param buffer the datagram to send + \param size the size of the message + \return the number of bytes written, which may be less than requested, or + a negative error code. +*/ diff --git a/docs/user/net/HttpAuthentication.dox b/docs/user/net/HttpAuthentication.dox new file mode 100644 index 0000000000..9c40143409 --- /dev/null +++ b/docs/user/net/HttpAuthentication.dox @@ -0,0 +1,117 @@ +/* + * Copyright 2013 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Adrien Destugues, pulkomandy@pulkomandy.tk + * + * Corresponds to: + * headers/os/net/HttpAuthentication.h rev 39161 + * src/kits/network/libnetapi/HttpAuthentication.cpp rev 45363 + */ + +/*! + \file HttpAuthentication.h + \ingroup network + \brief Authentication token for use in HTTP protocol communications. +*/ + +/*! + \class BHttpAuthentication + \ingroup network + \brief Authentication token for the HTTP protocol. + + This class allows managing of an authenticated http session. It stores the + authentication credentials and realm and provides tools for generating the + required nonces and hashes. + + An instance of this class should be used for the whole length of an HTTP + authenticated session. Initialize it by calling Initialize() and setting the + username and password (from the constructor or the setter methods). Then, + for each page that requires authentication, generate a token using the + Authorization() method. +*/ + +/*! + \fn BHttpAuthentication::BHttpAuthentication() + \brief Default constructor. + + This will create an unconfigured authentication object with the + authentication method set to B_HTTP_AUTHENTICATION_NONE. + + You have to set the username and password, and initialize the object using + the Initialize method with proper authentication data. +*/ + +/*! + \fn BHttpAuthentication::BHttpAuthentication(const BString& username, + const BString& password) + \brief Create an authentication session with the given name and password. + + The authentication method is set to B_HTTP_AUTHENTICATION_NONE. + This object can then be used with the Initialize method to bind it to an + HTTP authenticated session. +*/ + +/*! + \fn void BHttpAuthentication::SetUserName(const BString& username) + \brief Set the user name. + + \param username the new user name. +*/ + +/*! + \fn void BHttpAuthentication::SetPassword(const BString& password) + \brief Set the password + + \param password the new password. +*/ + +/*! + \fn void BHttpAuthentication::SetMethod(BHttpAuthenticationMethod method) + \brief Set the authentication method + + \param method the new authentication method. +*/ + +/*! + \fn status_t BHttpAuthentication::Initialize(const BString& wwwAuthenticate) + \brief Initialize the object from the given authentication data + + This method will parse the given authentication challenge and initialize + the authentication type to either B_HTTP_AUTHENTICATION_BASIC or + B_HTTP_AUTHENTICATION_DIGEST. The authentication parameters (realm, nonce, + algorithm) and state (opaque, stale) are also parsed and stored. + + \param wwwAuthenticate the value of the WWW-Authenticate HTTP header field. + \return B_OK if the request was parsed, B_ERROR if there is a parsing error, + B_BAD_VALUE if the authentication string is empty. +*/ + +/*! + \fn const BString& BHttpAuthentication::UserName() const + \returns the user name. +*/ + +/*! + \fn const BString& BHttpAuthentication::Password() const + \returns the password. +*/ + +/*! + \fn BHttpAuthenticationMethod BHttpAuthentication::Method() const + \returns the authentication method +*/ + +/*! + \fn BString BHttpAuthentication::Authorization(const BUrl& url, + const BString& method) const + \brief Generate an authentication reply for the given URL and method. + + For basic authentication, the reply is constant and is a Base64 encoding of + the string made of 'username:password'. In digest mode, each request will + have a different reply, so you must call this method for each page you want + to authenticate with. + + \return the generated reply +*/ diff --git a/docs/user/net/HttpForm.dox b/docs/user/net/HttpForm.dox new file mode 100644 index 0000000000..4860824308 --- /dev/null +++ b/docs/user/net/HttpForm.dox @@ -0,0 +1,120 @@ +/* + * Copyright 2013 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Adrien Destugues, pulkomandy@pulkomandy.tk + * + * Corresponds to: + * headers/os/net/HttpForm.h rev 39161 + * src/kits/network/libnetapi/HttpForm.cpp rev 39161 + */ + +/*! + \file HttpForm.h + \ingroup network + \brief Management of HTTP form data +*/ + +/*! + \class BHttpFormData + \ingroup network + \brief Stores aform data entry sent or received during an HTTP request. + + Each element in a form is stored in an instance of this class. The values + can be either strings, arbitrary binary buffers, or a pointer to a file. + + The latter allows reading data from the file as it is being sent through + the network, removing hte need to buffer the whole file contents in memory. +*/ + +/*! + \fn BHttpFormData::BHttpFormData(const BString& name, const BString& value) + \brief Construct a BHttpForlData with a string value. +*/ + +/*! + \fn BHttpFormData::BHttpFormData(const BString& name, const BPath& value) + \brief Construct a BHttpForlData which value is a file contents +*/ + +/*! + \fn BHttpFormData::BHttpFormData(const BString& name, const void* buffer, + ssize_t size) + \brief Construct a BHttpForlData which value is a binary buffer. +*/ + +/*! + \fn bool BHttpFormData::InitCheck() const + \brief Checks the initialisation of the object + + \return false if attempting to construct a BHttpFormData with a NULL buffer +*/ + +/*! + \fn const BString& BHttpFormData::Name() const + \brief Get the form field name +*/ + +/*! + \fn const BString& String() const + \brief Get the string value of a form field. + + \returns an empty string for buffer and file based fields +*/ + +/*! + \fn const BPath& File() const + \brief Get the file path of a form field. + + \returns an empty string for buffer and string based fields +*/ + +/*! + \fn const void* Buffer() const + \brief Get a pointer to the data of a form field. + + \returns an empty string for string and file based fields +*/ + +/*! + \fn ssize_t BufferSize() const; + \brief Get the buffer size + + \return 0 for string and file based fields. +*/ + +/*! + \fn bool IsFile() const + \return true if the field data is a file +*/ + +/*! + \fn const BString& Filename() const; + \return the name of the file, for file based fields +*/ + +/*! + \fn const BString& MimeType() const + \return the data MIME type +*/ + +/*! + \fn form_content_type Type() const + \return the kind of field +*/ + +/*! + \fn status_t BHttpFormData::CopyBuffer() + \brief Make a copy of the internal buffer + + The constructor for buffer-based fields does not copy the data given to it, + it just keeps a pointer. If you want to retain ownership of the data, call + this method so the buffer copies and releases it. +*/ + +/*! + \class BHttpForm + \ingroup network + \brief Container for all the BHttpFormData instances making up an HTTP form contents. +*/ diff --git a/docs/user/net/HttpHeaders.dox b/docs/user/net/HttpHeaders.dox new file mode 100644 index 0000000000..574ba7d9db --- /dev/null +++ b/docs/user/net/HttpHeaders.dox @@ -0,0 +1,182 @@ +/* + * Copyright 2013 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Adrien Destugues, pulkomandy@pulkomandy.tk + * + * Corresponds to: + * headers/os/net/HttpHeaders.h rev 39161 + * src/kits/network/libnetapi/HttpHeaders.cpp rev 45253 + */ + +/*! + \file HttpHeaders.h + \ingroup network + \brief Management of HTTP headers +*/ + +/*! + \class BHttpHeader + \ingroup network + \brief Represent a single header field for an HTTP connection + + HTTP headers are key-value pairs, where both the key and the value are + strings. The main purpose of this class is storing the pair and encoding it + to the HTTP protocol format, where some characters have to be escaped. +*/ + +/*! + \fn BHttpHeader::BHttpHeader() + \brief Default constructor. + + The header is initialized with empty key and value. +*/ + +/*! + \fn BHttpHeader::BHttpHeader(const char* string) + \brief Construct a BHttpHeader from an already encoded string + + The given string should be in the form "key:value" with all special + characters properly escaped. There is no way to detect parsing errors when + the given string is not properly formatted. Consider using SetHeader() + instead, where this can be checked. + + \param string the http-encoded header to parse +*/ + +/*! + \fn BHttpHeader::BHttpHeader(const char* name, const char* value) + \brief Construct a BHttpHeader from an unencoded key-value pair. + + \param name the key + \param value the value +*/ + +/*! + \fn BHttpHeader::BHttpHeader(const BHttpHeader& copy) + \brief Copy constructor. +*/ + +/*! + \fn void BHttpHeader::SetName(const char* name) + \brief Sets the key for this header. + + The key is trimmed (BString::Trim()) to remove any whitespace. + + \param name the new key +*/ + +/*! + \fn void BHttpHeader::SetValue(const char* value) + \brief Sets the value for this header. + + The value is trimmed (BString::Trim()) to remove any whitespace. + + \param value the new value +*/ + +/*! + \fn bool BHttpHeader::SetHeader(const char* string) + \brief Parse the given string and configure this object + + Extracts and decode the name and value from the given string. + + \param string the header data to parse + \return wether parsing succeeded +*/ + +/*! + \fn const char* BHttpHeader::Name() const + \return the key for this header +*/ + +/*! + \fn const char* BHttpHeader::Value() const + \return the value for this header +*/ + +/*! + \fn const char* BHttpHeader::Header() const + \return the encoded header +*/ + +/*! + \fn bool BHttpHeader::NameIs(const char* name) const + \brief Compare this header name with the given one + + Both names are trimmed from whitespace, and the comparison is not case + sensitive (as per the HTTP specification). +*/ + +/*! + \class BHttpHeaders + \ingroup network + \brief Container for a set of HTTP headers. + + This class allows management of the set of headers for a single HTTP + transaction. They are stored in a list and can be iterated on. +*/ + +/*! + \fn BHttpHeaders::BHttpHeaders() + \brief Construct an empty header list. +*/ + +/*! + \fn BHttpHeaders::BHttpHeaders(const BHttpHeaders& copy) + \brief Copy constructor + + A deep copy is performed, so modifying the headers in the copy does not + change the original. +*/ + +/*! + \fn const char* BHttpHeaders::HeaderValue(const char* name) const + \return the value mapped to the given key, or NULL if not found. +*/ + +/*! + \fn BHttpHeader& BHttpHeaders::HeaderAt(int32 index) const + \brief Find header by position + + \param index must be in bounds, else this method will crash. + \see CountHeaders() +*/ + +/*! + \fn int32 BHttpHeaders::CountHeaders() const + \return the number of entries in this set +*/ + +/*! + \fn int32 BHttpHeaders::HasHeader(const char* name) const + \brief Find an header by key + \return The index of the header for use with HeaderAt(), or B_ERROR if not + found. +*/ + +/*! + \fn bool BHttpHeaders::AddHeader(const char* line) + \brief Add a new header to the list, from an HTTP header line. + + Duplicates headers are allowed. + + \return false when out of memory. +*/ + +/*! + \fn bool BHttpHeaders::AddHeader(const char* name, const char* value) + \brief Add a new header from the given key:value pair +*/ + +/*! + \fn bool BHttpHeaders::AddHeader(const char* name, int32 value) + \brief Convenience method to add a header with a numeric value. +*/ + +/*! + \fn void BHttpHeaders::Clear() + \brief Remove all HTTP headers from the list +*/ +