Ports

Detailed Description

Component input and output ports.

A port is a point of connection between components:

A port is a shared object: get a new reference with bt_port_get_ref() and put an existing reference with bt_port_put_ref().

The common C type of a port is bt_port.

There are two types of ports:

Input port

Input connection point from which messages are received.

Filter and sink components have input ports.

An input port's specific type is bt_port_input and its type enumerator is BT_PORT_TYPE_INPUT.

Upcast the bt_port_input type to the bt_port type with bt_port_input_as_port_const().

Get a new input port reference with bt_port_input_get_ref() and put an existing one with bt_port_input_put_ref().

Output port

Output connection point to which messages are sent.

Source and filter components have output ports.

An output port's specific type is bt_port_output and its type enumerator is BT_PORT_TYPE_OUTPUT.

Upcast the bt_port_output type to the bt_port type with bt_port_output_as_port_const().

Get a new output port reference with bt_port_output_get_ref() and put an existing one with bt_port_output_put_ref().

Get a port's type enumerator with bt_port_get_type(). You can also use the bt_port_is_input() and bt_port_is_output() helper functions.

A component can add a port with:

• bt_self_component_source_add_output_port()
• bt_self_component_filter_add_input_port()
• bt_self_component_filter_add_output_port()
• bt_self_component_sink_add_input_port()

Borrow a port's connection, if any, with bt_port_borrow_connection_const().

Borrow the component to which a port belongs with bt_port_borrow_component_const().

Properties

A port has the following common properties:

Name

Name of the port.

For a given component:

• Each input port has a unique name.
• Each output port has a unique name.

A port's name is set when the component adds it; you cannot change it afterwards.

Get a port's name with bt_port_get_name().

Is connected?

Whether or not the port is currently connected to another port.

Get whether or not a port is connected with bt_port_is_connected().

When a port is unconnected, bt_port_borrow_connection_const() returns NULL.

Types
typedef struct bt_port	bt_port
	Port.
typedef struct bt_port_input	bt_port_input
	Input port.
typedef struct bt_port_output	bt_port_output
	Output port.

Type query
enum	bt_port_type {   BT_PORT_TYPE_INPUT,   BT_PORT_TYPE_OUTPUT }
	Port type enumerators. More...
typedef enum bt_port_type	bt_port_type
	Port type enumerators.
bt_port_type	bt_port_get_type (const bt_port *port)
	Returns the type enumerator of the port port. More...
static bt_bool	bt_port_is_input (const bt_port *port)
	Returns whether or not the port port is an input port. More...
static bt_bool	bt_port_is_output (const bt_port *port)
	Returns whether or not the port port is an output port. More...

Connection access
const bt_connection *	bt_port_borrow_connection_const (const bt_port *port)
	Borrows the connection of the port port. More...

Component access
const bt_component *	bt_port_borrow_component_const (const bt_port *port)
	Borrows the component to which the port port belongs. More...

Properties
const char *	bt_port_get_name (const bt_port *port)
	Returns the name of the port port. More...
bt_bool	bt_port_is_connected (const bt_port *port)
	Returns whether or not the port port is connected. More...

Reference count (common)
void	bt_port_get_ref (const bt_port *port)
	Increments the reference count of the port port. More...
void	bt_port_put_ref (const bt_port *port)
	Decrements the reference count of the port port. More...
#define	BT_PORT_PUT_REF_AND_RESET(_port)
	Decrements the reference count of the port _port, and then sets _port to NULL. More...
#define	BT_PORT_MOVE_REF(_dst, _src)
	Decrements the reference count of the port _dst, sets _dst to _src, and then sets _src to NULL. More...

Input port
static const bt_port *	bt_port_input_as_port_const (const bt_port_input *port)
	Upcasts the input port port to the common bt_port type. More...
void	bt_port_input_get_ref (const bt_port_input *port)
	Increments the reference count of the input port port. More...
void	bt_port_input_put_ref (const bt_port_input *port)
	Decrements the reference count of the input port port. More...
#define	BT_PORT_INPUT_PUT_REF_AND_RESET(_port)
	Decrements the reference count of the input port _port, and then sets _port to NULL. More...
#define	BT_PORT_INPUT_MOVE_REF(_dst, _src)
	Decrements the reference count of the input port _dst, sets _dst to _src, and then sets _src to NULL. More...

Output port
static const bt_port *	bt_port_output_as_port_const (const bt_port_output *port)
	Upcasts the output port port to the common bt_port type. More...
void	bt_port_output_get_ref (const bt_port_output *port)
	Increments the reference count of the output port port. More...
void	bt_port_output_put_ref (const bt_port_output *port)
	Decrements the reference count of the output port port. More...
#define	BT_PORT_OUTPUT_PUT_REF_AND_RESET(_port)
	Decrements the reference count of the output port _port, and then sets _port to NULL. More...
#define	BT_PORT_OUTPUT_MOVE_REF(_dst, _src)
	Decrements the reference count of the output port _dst, sets _dst to _src, and then sets _src to NULL. More...

Enumeration Type Documentation

bt_port_type

enum bt_port_type

Port type enumerators.

Enumerator
BT_PORT_TYPE_INPUT	Input port.
BT_PORT_TYPE_OUTPUT	Output port.

Macro Definition Documentation

BT_PORT_PUT_REF_AND_RESET

#define BT_PORT_PUT_REF_AND_RESET

(

_port

)

Decrements the reference count of the port _port, and then sets _port to NULL.

Parameters

_port

Port of which to decrement the reference count. Can contain NULL.

Precondition

_port is an assignable expression.

BT_PORT_MOVE_REF

#define BT_PORT_MOVE_REF	(		_dst,
			_src
	)

Decrements the reference count of the port _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves a port reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst	Destination expression. Can contain NULL.
_src	Source expression. Can contain NULL.

Precondition

_dst is an assignable expression.

_src is an assignable expression.

BT_PORT_INPUT_PUT_REF_AND_RESET

#define BT_PORT_INPUT_PUT_REF_AND_RESET

(

_port

)

Decrements the reference count of the input port _port, and then sets _port to NULL.

Parameters

_port

Input port of which to decrement the reference count. Can contain NULL.

Precondition

_port is an assignable expression.

BT_PORT_INPUT_MOVE_REF

#define BT_PORT_INPUT_MOVE_REF	(		_dst,
			_src
	)

Decrements the reference count of the input port _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves an input port reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst	Destination expression. Can contain NULL.
_src	Source expression. Can contain NULL.

Precondition

_dst is an assignable expression.

_src is an assignable expression.

BT_PORT_OUTPUT_PUT_REF_AND_RESET

#define BT_PORT_OUTPUT_PUT_REF_AND_RESET

(

_port

)

Decrements the reference count of the output port _port, and then sets _port to NULL.

Parameters

_port

Output port of which to decrement the reference count. Can contain NULL.

Precondition

_port is an assignable expression.

BT_PORT_OUTPUT_MOVE_REF

#define BT_PORT_OUTPUT_MOVE_REF	(		_dst,
			_src
	)

Decrements the reference count of the output port _dst, sets _dst to _src, and then sets _src to NULL.

This macro effectively moves an output port reference from the expression _src to the expression _dst, putting the existing _dst reference.

Parameters

_dst	Destination expression. Can contain NULL.
_src	Source expression. Can contain NULL.

Precondition

_dst is an assignable expression.

_src is an assignable expression.

Function Documentation

bt_port_get_type()

bt_port_type bt_port_get_type

(

const bt_port *

port

)

Returns the type enumerator of the port port.

Parameters

[in]

port

Port of which to get the type enumerator

Returns

Type enumerator of port.

Precondition

port is not NULL.

See also

bt_port_is_input() — Returns whether or not a port is an input port.

bt_port_is_output() — Returns whether or not a port is an output port.

bt_port_is_input()

static bt_bool bt_port_is_input ( const bt_port *  port )

inlinestatic

Returns whether or not the port port is an input port.

Parameters

[in]

port

Port to check.

Returns

BT_TRUE if port is an input port.

Precondition

port is not NULL.

See also

bt_port_get_type() — Returns the type enumerator of a port.

bt_port_is_output()

static bt_bool bt_port_is_output ( const bt_port *  port )

inlinestatic

Returns whether or not the port port is an output port.

Parameters

[in]

port

Port to check.

Returns

BT_TRUE if port is an output port.

Precondition

port is not NULL.

See also

bt_port_get_type() — Returns the type enumerator of a port.

bt_port_borrow_connection_const()

const bt_connection* bt_port_borrow_connection_const

(

const bt_port *

port

)

Borrows the connection of the port port.

This function returns NULL if port is unconnected (bt_port_is_connected() returns BT_FALSE).

Parameters

[in]

port

Port of which to borrow the connection.

Returns

Borrowed reference of the connection of port.

Precondition

port is not NULL.

bt_port_borrow_component_const()

const bt_component* bt_port_borrow_component_const

(

const bt_port *

port

)

Borrows the component to which the port port belongs.

Parameters

[in]

port

Port of which to borrow the component which owns it.

Returns

Borrowed reference of the component which owns port.

Precondition

port is not NULL.

bt_port_get_name()

const char* bt_port_get_name

(

const bt_port *

port

)

Returns the name of the port port.

See the name property.

Parameters

[in]

port

Port of which to get the name.

Returns

Name of port, or NULL if none.

The returned pointer remains valid as long as port exists.

Precondition

port is not NULL.

bt_port_is_connected()

bt_bool bt_port_is_connected

(

const bt_port *

port

)

Returns whether or not the port port is connected.

See the is connected? property.

Parameters

[in]

port

Port of which to get whether or not it's connected.

Returns

BT_TRUE if port is connected.

Precondition

port is not NULL.

bt_port_get_ref()

void bt_port_get_ref

(

const bt_port *

port

)

Increments the reference count of the port port.

Parameters

[in]

port

Port of which to increment the reference count. Can be NULL.

See also

bt_port_put_ref() — Decrements the reference count of a port.

bt_port_put_ref()

void bt_port_put_ref

(

const bt_port *

port

)

Decrements the reference count of the port port.

Parameters

[in]

port

Port of which to decrement the reference count. Can be NULL.

See also

bt_port_get_ref() — Increments the reference count of a port.

bt_port_input_as_port_const()

static const bt_port* bt_port_input_as_port_const ( const bt_port_input *  port )

inlinestatic

Upcasts the input port port to the common bt_port type.

Parameters

[in]

port

Input port to upcast. Can be NULL.

Returns

port as a common port.

bt_port_input_get_ref()

void bt_port_input_get_ref

(

const bt_port_input *

port

)

Increments the reference count of the input port port.

Parameters

[in]

port

Input port of which to increment the reference count. Can be NULL.

See also

bt_port_input_put_ref() — Decrements the reference count of an input port.

bt_port_input_put_ref()

void bt_port_input_put_ref

(

const bt_port_input *

port

)

Decrements the reference count of the input port port.

Parameters

[in]

port

Input port of which to decrement the reference count. Can be NULL.

See also

bt_port_input_get_ref() — Increments the reference count of an input port.

bt_port_output_as_port_const()

static const bt_port* bt_port_output_as_port_const ( const bt_port_output *  port )

inlinestatic

Upcasts the output port port to the common bt_port type.

Parameters

[in]

port

Output port to upcast. Can be NULL.

Returns

port as a common port.

bt_port_output_get_ref()

void bt_port_output_get_ref

(

const bt_port_output *

port

)

Increments the reference count of the output port port.

Parameters

[in]

port

Output port of which to increment the reference count. Can be NULL.

See also

bt_port_output_put_ref() — Decrements the reference count of a output port.

bt_port_output_put_ref()

void bt_port_output_put_ref

(

const bt_port_output *

port

)

Decrements the reference count of the output port port.

Parameters

[in]

port

Output port of which to decrement the reference count. Can be NULL.

See also

bt_port_output_get_ref() — Increments the reference count of a output port.