brp_set_layer()

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.

Attention: when adding a protocol to a composite protocol, the composite protocol takes ownership of layer_protocol. Thus layer_protocol must not be freed manually except it is removed from the composite again by brp_detach_layer().

If the layer specified by ID is already in use, the previous protocol for this layer will be destroyed and the new layer_protocol will inserted exactly at the same layer as the destroyed protocol (=replace it).

If the layer ID is not part of the composite protocol yet, it will be added implicitly at the top of the protocol stack (see brp_add_layer()).

If the composite protocol is already opened, the layer protocol will be opened implicitely before being added. In contrary it is invalid to set an already opened layer protocol!

If this call fails, ownership of layer_protocol stays with the caller (it is NOT inserted and NOT destroyed — in contrast to brp_set_io() / brp_set_crypto(), which destroy their protocol argument on failure).

Attention

: If the layer_protocol is a composite on its own, the composite_protocol will not take over ownership. This means you have to destroy layer_protocol on your own after composite_protocol was destroyed. Furthermore layer_protocol will not be automaticially opened/closed in this case.

Parameters

composite_protocol	composite where layer shall be added
layer_id	identification of layer (see BRP_LAYERID_*, i.e. BRP_LAYERID_BRP)
layer_protocol	new layer protocol. Must not be NULL!