Classes | Public Types | List of all members
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. More...
 

Public Member Functions

Constructors & Destructor
 BHttpFields ()
 Construct an empty list of HTTP header fields. More...
 
 BHttpFields (std::initializer_list< Field > fields)
 Initialize the object with a list of fields. More...
 
 BHttpFields (const BHttpFields &other)
 Copy constructor. More...
 
 BHttpFields (BHttpFields &&other)
 Move constructor. More...
 
 ~BHttpFields () noexcept
 Destructor. More...
 
Assignment operators
BHttpFieldsoperator= (const BHttpFields &)
 Copy assignment operator. More...
 
BHttpFieldsoperator= (BHttpFields &&) noexcept
 Move assignment operator. More...
 
List Access
const Fieldoperator[] (size_t index) const
 Get the item at an index. More...
 
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. More...
 
void AddField (BString &field)
 Append a field from the raw field line. More...
 
void AddFields (std::initializer_list< Field > fields)
 Add a list of fields. More...
 
void RemoveField (const std::string_view &name) noexcept
 Remove all fields with the name. More...
 
void RemoveField (ConstIterator it) noexcept
 Remove the specific field at the location of an iterator. More...
 
void MakeEmpty () noexcept
 Clear all fields from this header. More...
 
Querying
ConstIterator FindField (const std::string_view &name) const noexcept
 Find a field with name. More...
 
size_t CountFields () const noexcept
 Get the number of fields. More...
 
size_t CountFields (const std::string_view &name) const noexcept
 Cound the number of fields that have this name. More...
 
Range-based iteration.

Allows the usage of this object in a for loop.

ConstIterator begin () const noexcept
 Return an iterator to the first field. More...
 
ConstIterator end () const noexcept
 Return an iterator to the end of the fields. More...
 

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

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_allocError 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_allocError in case memory cannot be allocated.
BHttpFields::InvalidInputThis 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_allocError 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_allocError 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
fieldThe raw header field to move into the list of headers.
Exceptions
std::bad_allocError in case memory cannot be allocated.
BHttpFields::InvalidInputThis 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
nameThe name of the header field.
valueThe value of the header field.
Exceptions
std::bad_allocError in case memory cannot be allocated.
BHttpFields::InvalidInputThis 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_allocError in case memory cannot be allocated.
BHttpFields::InvalidInputThis 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
nameThe 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
nameThe 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_allocError 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
indexThe zero-based index of the item in the list of fields.
Returns
A const reference to the the field.
Exceptions
BRuntimeErrorError 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
nameThe 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
itA valid iterator to the item that must be removed.
Since
Haiku R1
BPrivate::Network::BHttpFields::BHttpFields
BHttpFields()
Construct an empty list of HTTP header fields.