BPrivate::Network::BHttpFields Class Reference

Represents the field section of a HTTP header. More...

Classes
class	Field
	Represents a HTTP header field. More...
class	FieldName
	Representation of a HTTP header name. More...
class	InvalidInput
	Error that represents when a string input contains characters that are incompatible with the HTTP specification. More...

Public Types
using	ConstIterator = std::list< Field >::const_iterator
	Define a constant iterator to iterate through the list of header fields.

Public Member Functions
Constructors & Destructor
	BHttpFields ()
	Construct an empty list of HTTP header fields.
	BHttpFields (std::initializer_list< Field > fields)
	Initialize the object with a list of fields.
	BHttpFields (const BHttpFields &other)
	Copy constructor.
	BHttpFields (BHttpFields &&other)
	Move constructor.
	~BHttpFields () noexcept
	Destructor.
Assignment operators
BHttpFields &	operator= (const BHttpFields &)
	Copy assignment operator.
BHttpFields &	operator= (BHttpFields &&) noexcept
	Move assignment operator.
List Access
const Field &	operator[] (size_t index) const
	Get the item at an index.
Modifying the list
void	AddField (const std::string_view &name, const std::string_view &value)
	Append a field with name and a value to the list of headers.
void	AddField (BString &field)
	Append a field from the raw field line.
void	AddFields (std::initializer_list< Field > fields)
	Add a list of fields.
void	RemoveField (const std::string_view &name) noexcept
	Remove all fields with the name.
void	RemoveField (ConstIterator it) noexcept
	Remove the specific field at the location of an iterator.
void	MakeEmpty () noexcept
	Clear all fields from this header.
Querying
ConstIterator	FindField (const std::string_view &name) const noexcept
	Find a field with name.
size_t	CountFields () const noexcept
	Get the number of fields.
size_t	CountFields (const std::string_view &name) const noexcept
	Cound the number of fields that have this name.
Range-based iteration.
Allows the usage of this object in a for loop.
ConstIterator	begin () const noexcept
	Return an iterator to the first field.
ConstIterator	end () const noexcept
	Return an iterator to the end of the fields.

Detailed Description

Represents the field section of a HTTP header.

The HTTP protocol (RFC 7230) specifies that each HTTP request and response has a header. Part of that header is a list of fields, which are name and value pairs. The high level protocol defines what valid field names and field values look like. When adding or modifying field data, the members of this class enforce those constraints.

When you are processing a HTTP response, this object gives you the methods to query the headers in that response. When you are creating a HTTP request, this object gives you methods to add and modify header fields on your request. When retrieving data from the header fields, this data is often returned as an std::string_view. Please note that this object will only point to valid data for the lifetime of this object, which in case of a HTTP response, will be bound to the lifetime of the object that contains the HTTP response.

When adding headers, the fields are stored in the order in which they were added. You can use AddField() to add more than one field with the same key.

The HTTP protocol does not prohibit multiple fields with the same name, but it does note that semantically this is only allowed for a limited set of explicitly named headers, like the 'Set-Cookie' field (see RFC 7230 section 3.2.2). Because most header fields will only exist once, the interface of this class is optimized for each header field existing only once. The onus is on the user to take additional steps when dealing with header fields that they know can occur more than once.

Since

Haiku R1

Member Typedef Documentation

ConstIterator

BPrivate::Network::BHttpFields::ConstIterator

Define a constant iterator to iterate through the list of header fields.

This iterator has the same semantics as other constant iterators in the C++ standard library.

Since

Haiku R1

Constructor & Destructor Documentation

BHttpFields() [1/4]

BPrivate::Network::BHttpFields::BHttpFields

(

)

Construct an empty list of HTTP header fields.

Exceptions

std::bad_alloc

Error in case memory cannot be allocated.

Since

Haiku R1

BHttpFields() [2/4]

BPrivate::Network::BHttpFields::BHttpFields

(

std::initializer_list< Field >

fields

)

Initialize the object with a list of fields.

This enables you to initialize the fields with a list of BHttpFields::Field objects. Any empty fields will be skipped. Like AddField(), this constructor keeps the fields in the original order.

The example below will create an object with four fields, even though five fields have been passed in the initializer. The two Accept-Encoding will be added in this order, even though the HTTP specification does not explicitly allow this.

const BHttpFields defaultFields = {
    {"Host"sv, "haiku-os.org"sv},
    {"Accept-Encoding"sv, "gzip"sv}
    {"Accept"sv, "*\/*"sv},
    {},
    {"Accept-Encoding"sv, "bzip2"sv}
};

Exceptions

std::bad_alloc	Error in case memory cannot be allocated.
BHttpFields::InvalidInput	This error indicates that some of the names or values in the list do not adhere to the HTTP specification.

Since

Haiku R1

BHttpFields() [3/4]

BPrivate::Network::BHttpFields::BHttpFields

(

const BHttpFields &

other

)

Copy constructor.

Exceptions

std::bad_alloc

Error in case memory cannot be allocated.

Since

Haiku R1

BHttpFields() [4/4]

BPrivate::Network::BHttpFields::BHttpFields

(

BHttpFields &&

other

)

Move constructor.

The name and value from the other fields object will be moved to this object. The other object will be empty, meaning it no longer has any fields.

Exceptions

std::bad_alloc

Error in case memory cannot be allocated.

Since

Haiku R1

~BHttpFields()

BPrivate::Network::BHttpFields::~BHttpFields ( )

noexcept

Destructor.

Since

Haiku R1

Member Function Documentation

AddField() [1/2]

void BPrivate::Network::BHttpFields::AddField

(

BString &

field

)

Append a field from the raw field line.

The raw header field is checked to determine whether it corresponds to the the HTTP specification. Note that the raw field should not include any newline characters at the end of the string.

If succesful, the string is moved into the fields object, and the original input value will be empty.

Parameters

field

The raw header field to move into the list of headers.

Exceptions

std::bad_alloc	Error in case memory cannot be allocated.
BHttpFields::InvalidInput	This error indicates that the name or the value is empty or contains invalid characters.

Since

Haiku R1

AddField() [2/2]

void BPrivate::Network::BHttpFields::AddField	(	const std::string_view &	name,
		const std::string_view &	value
	)

Append a field with name and a value to the list of headers.

The parameters are checked whether they only contain characters that are allowed by the HTTP specification.

Parameters

name	The name of the header field.
value	The value of the header field.

Exceptions

std::bad_alloc	Error in case memory cannot be allocated.
BHttpFields::InvalidInput	This error indicates that the name or the value contains invalid characters.

Since

Haiku R1

AddFields()

void BPrivate::Network::BHttpFields::AddFields

(

std::initializer_list< Field >

fields

)

Add a list of fields.

This enables you to add a list of BHttpFields::Field objects. Like AddField(), the fields are added in the the original order.

Exceptions

std::bad_alloc	Error in case memory cannot be allocated.
BHttpFields::InvalidInput	This error indicates that some of the names or values in the list do not adhere to the HTTP specification.

Since

Haiku R1

begin()

ConstIterator BPrivate::Network::BHttpFields::begin ( ) const

noexcept

Return an iterator to the first field.

Since

Haiku R1

CountFields() [1/2]

size_t BPrivate::Network::BHttpFields::CountFields ( ) const

noexcept

Get the number of fields.

Returns

The number of fields in this container. If multiple fields have the same name, they will be counted individually.

Since

Haiku R1

CountFields() [2/2]

size_t BPrivate::Network::BHttpFields::CountFields ( const std::string_view &  name ) const

noexcept

Cound the number of fields that have this name.

Parameters

name	The name of the field you are looking for. Name matching will be done case insensitively.

Returns

The number of field with the name.

Since

Haiku R1

end()

ConstIterator BPrivate::Network::BHttpFields::end ( ) const

noexcept

Return an iterator to the end of the fields.

Since

Haiku R1

FindField()

ConstIterator BPrivate::Network::BHttpFields::FindField ( const std::string_view &  name ) const

noexcept

Find a field with name.

In case there are more than one fields with the same name, you cannot use this method to find all instances, and you should iterate through the fields instead.

Parameters

name	The name of the field to be found.

Returns

Returns a valid iterator to the first field with name in this container, or BHttpFields::end() in case the name is not found.

Since

Haiku R1

MakeEmpty()

void BPrivate::Network::BHttpFields::MakeEmpty ( )

noexcept

Clear all fields from this header.

Removes all fields from the container.

Since

Haiku R1

operator=() [1/2]

BHttpFields & BPrivate::Network::BHttpFields::operator= ( BHttpFields &&  other )

noexcept

Move assignment operator.

The name and value from the other fields object will be moved to this object. The other object will be empty, meaning it no longer has any fields.

Since

Haiku R1

operator=() [2/2]

BHttpFields & BPrivate::Network::BHttpFields::operator=

(

const BHttpFields &

other

)

Copy assignment operator.

Make a new fields object with a copy of the fields of the other header.

Exceptions

std::bad_alloc

Error in case memory cannot be allocated.

Since

Haiku R1

operator[]()

const Field & BPrivate::Network::BHttpFields::operator[]

(

size_t

index

)

const

Get the item at an index.

Parameters

index

The zero-based index of the item in the list of fields.

Returns

A const reference to the the field.

Exceptions

BRuntimeError

Error in case the index is out of bounds.

Since

Haiku R1

RemoveField() [1/2]

void BPrivate::Network::BHttpFields::RemoveField ( const std::string_view &  name )

noexcept

Remove all fields with the name.

If there are no fields with this name, this method does nothing. Like all operations that involve a field name, the name matching is case insensitive.

Parameters

name	The name of the field to remove.

Since

Haiku R1

RemoveField() [2/2]

void BPrivate::Network::BHttpFields::RemoveField ( ConstIterator  it )

noexcept

Remove the specific field at the location of an iterator.

Parameters

it	A valid iterator to the item that must be removed.

Since

Haiku R1