haiku/docs/user/netservices/HttpHeaders.dox

/*
 * Copyright 2013 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Adrien Destugues, pulkomandy@pulkomandy.tk
 *
 * Corresponds to:
 *		headers/private/netservices/HttpHeaders.h		hrev54923
 *		src/kits/network/libnetservices/HttpHeaders.cpp	hrev54923
 */

/*!
	\file HttpHeaders.h
	\ingroup netservices
	\brief Management of HTTP headers
*/

/*!
	\class BPrivate::Network::BHttpHeader
	\ingroup netservices
	\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 BPrivate::Network::BHttpHeaders
	\ingroup netservices
	\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
*/