composite_protocol.h File Reference

A composite protocol is a container object, that provides a single protocol object for handling a stack of multiple sub-protocols at once. More...

#include "protocol.h"

Go to the source code of this file.

Macros
BRP_MONITOR_XXX
Specifies the mode of monitoring
#define	BRP_MONITOR_DISABLED   0
	avoid that BRP traffic could leak More...
#define	BRP_MONITOR_ENABLED   1
	(required when sensitive data is transferred) More...
#define	BRP_MONITOR_PLAINTEXT   2
	encrypted sessions will show only encryted data More...

Functions
BRP_LIB brp_protocol	brp_create_composite (void)
	Creates an empty composite protocol. More...
BRP_LIB brp_protocol	brp_create (void)
	This is equivalent to the following call: More...
BRP_LIB brp_errcode	brp_add_layer (brp_protocol composite_protocol, brp_layer_id layer_id)
	Adds a protocol layer without assigning a protocol to it. More...
BRP_LIB brp_errcode	brp_set_layer (brp_protocol composite_protocol, brp_layer_id layer_id, brp_protocol layer_protocol)
	Adds/replaces a protocol layer to a composite protocol. More...
BRP_LIB brp_protocol	brp_get_layer (brp_protocol composite_protocol, brp_layer_id layer_id)
	Retrieves a protocol layer from a composite protocol. More...
BRP_LIB brp_protocol	brp_detach_layer (brp_protocol composite_protocol, brp_layer_id layer_id)
	Removes a protocol from a composite protocol stack without destroying. More...
BRP_LIB brp_errcode	brp_set_io (brp_protocol protocol, brp_protocol io_protocol)
	Assigns an I/O protocol to a composite protocol (protocol stack). More...
BRP_LIB brp_errcode	brp_set_crypto (brp_protocol composite_protocol, brp_protocol crypto_protocol)
	Assigns a crypto protocol to a composite protocol (protocol stack). More...
BRP_LIB brp_errcode	brp_suppress_monitoring (brp_protocol protocol)
	Disables the monitoring feature of this library. More...
BRP_LIB brp_errcode	brp_set_monitor (brp_protocol protocol, int mode)
	When communicating encrypted (see brp_set_crypto()) the monitoring feature of this library logs the plaintext data. More...

Detailed Description

A composite protocol is a container object, that provides a single protocol object for handling a stack of multiple sub-protocols at once.

This means all sub-protocols are opened/closed when the composite is opened/closed. Furthermore they are destroyed when the composite is destroyed.

ATTENTION: This means that a protocol added to a container must not be destroyed manually (except it is unlinked by brp_detach_layer()!

A composite is organized in layers, which are identified by unique integers (see BRP_LAYERID_..., like BRP_LAYERID_IO). The order of the layer is fix and is usually defined by the order of calling brp_add_layer() (or brp_set_layer(), which does an implicit brp_add_layer() if a layer is unknown yet). Via brp_set_layer() you can assign a protocol to a layer. When running a command / sending a frame, it will be internally routed from the topmost protocol to the bottom protocol.

The I/O layer may be a composite protocol on its own. In this case it is not part of the containing composite protocol stack. This means:

• Closing the containing composite does not close the contained composite
• Destroying the containing composite does not destroy (or close) the contained composite.
• Opening the containing composite when the contained composite is closed results in a BRP_ERR_CLOSED

Definition in file composite_protocol.h.