Document some classes for the Network Kit.
This commit is contained in:
Adrien Destugues
@@ -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 \
|
||||
|
||||
+5
-1
@@ -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
|
||||
\defgroup keyboard Keyboard
|
||||
|
||||
@@ -0,0 +1,196 @@
|
||||
/*
|
||||
* Copyright 2013 Haiku, Inc. All rights reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* Adrien Destugues, [email protected]
|
||||
*
|
||||
* 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.
|
||||
*/
|
||||
@@ -0,0 +1,169 @@
|
||||
/*
|
||||
* Copyright 2013 Haiku, Inc. All rights reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* Adrien Destugues, [email protected]
|
||||
*
|
||||
* 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.
|
||||
*/
|
||||
@@ -0,0 +1,117 @@
|
||||
/*
|
||||
* Copyright 2013 Haiku, Inc. All rights reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* Adrien Destugues, [email protected]
|
||||
*
|
||||
* 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
|
||||
*/
|
||||
@@ -0,0 +1,120 @@
|
||||
/*
|
||||
* Copyright 2013 Haiku, Inc. All rights reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* Adrien Destugues, [email protected]
|
||||
*
|
||||
* 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.
|
||||
*/
|
||||
@@ -0,0 +1,182 @@
|
||||
/*
|
||||
* Copyright 2013 Haiku, Inc. All rights reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* Adrien Destugues, [email protected]
|
||||
*
|
||||
* 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
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user