Directives

Generic message

An in-depth look at the :mod:`cpp-netlib`

.. toctree::

:maxdepth: 2

message.rst

uri.rst

protocol.rst

:Description: Complete user documentation, with examples, for the :mod:`cpp-netlib`.

tutorials.rst

in_depth.rst

techniques.rst

The message template

One of the core components in the library is the concept and the implementation

of a common message type. In most (not all) network protocols, the concept of a

message is central to the definition of the protocol. In HTTP, SMTP, XMPP, and

even other protocols like SNMP and ICMP, there is a common notion of a "packet"

or a message. In cpp-netlib we chose to implement the concept of a message that

has the following common parts:

* **Source** - every message has a source identifier which varies from

protocol to protocol.

* **Destination** - every message has a destination identifier which varies

from protocol to protocol.

* **Headers** - each message is assumed to contain headers, which may be empty

in cases where the protocol does not support it, but is nonetheless

supported by cpp-netlib messages.

* **Body** - the content area of a message which varies from protocol to

protocol (also sometimes referred to as payload).

This division is purely logical -- in the underlying implementation, the message

type can choose to have different means of storing the data, dependinn on the

type used to tag the message. This section covers the `Message Concept`_ as well

as the `Basic Message`_ implementation.

Message Concept

The Message Concept specifies what the valid operations on a message are as well

as what messages look like semantically. The following table summarize the

operations and syntactic as well as semantic properties of messages.

**Legend**

:M: The message type.

:m,n: An instance of **M**.

:S: A string type.

:s,k,v: An instance of **S**.

| Construct | Result | Description |

| M() | Instance of M | Default constructible. |

| M(m) | Instance of M | Copy constructible. |

| m = n; | Reference to m | Assignable. |

| swap(m, n); | ``void`` | Swappable. |

| source(m); | unspecified | Retrieve the source of m. |

| destination(m); | unspecified | Retrieve the destination of m. |

| headers(m); | ``Range<Pair<S,S>>`` | Get the range of headers of m. |

| body(m); | unspecified | Retrieve the body of m. |

| m << source(s); | ``M &`` | Set the source of m. |

| m << destination(s); | ``M &`` | Set the destination of m. |

| m << header(k, v); | ``M &`` | Add a header to m. |

| m << remove_header(k); | ``M &`` | Remove a header from m. |

| m << body(s); | ``M &`` | Set the body of m. |

Types that model the Message Concept are meant to encapsulate data that has a

source, a destination, one or more named headers, and a body/payload. Because

the accessors and the directives are not required to be part of the message type

that models the Message Concept, a message can be implemented as a POD type and

have all manipulations performed in the directive implementations, as well as

value transformations done in the accessors.

Basic Message

The default implementation of a simple type that models the Message Concept is

available in cpp-netlib. This default implementation is named ``basic_message``

which supports a ``Tag`` template parameter. The definition of ``basic_message``

looks like this:

::

The ``basic_message`` template requires that the following tag-dispatched

metafunctions are defined for the type ``Tag``:

::

All the operations defined by the message concept are implemented by this basic

message type. Other message implementations can either use this common message

type or specialize it according to whether they want to use different containers

or whether it's going to be just a POD type.

Static and dynamic polymorphism