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.

The specific type of an input port 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.

The specific type of an output port 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 the type enumerator of a port 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:

Borrow the connection of a port, 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.

The name of a port is set when the component adds it; you cannot change it afterwards.

Get the name of a port 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.

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.

static bt_bool	bt_port_is_input (const bt_port *port)
	Returns whether or not the port port is an input port.

static bt_bool	bt_port_is_output (const bt_port *port)
	Returns whether or not the port port is an output port.

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.

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

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

Properties
const char *	bt_port_get_name (const bt_port *port)
	Returns the name of the port port.

bt_bool	bt_port_is_connected (const bt_port *port)
	Returns whether or not the port port is connected.

Reference count (common)
void	bt_port_get_ref (const bt_port *port)
	Increments the reference count of the port port.

void	bt_port_put_ref (const bt_port *port)
	Decrements the reference count of the port port.

#define	BT_PORT_PUT_REF_AND_RESET(_port)
	Decrements the reference count of the port _port, and then sets _port to `NULL`.

#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`.

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.

void	bt_port_input_get_ref (const bt_port_input *port)
	Increments the reference count of the input port port.

void	bt_port_input_put_ref (const bt_port_input *port)
	Decrements the reference count of the input port port.

#define	BT_PORT_INPUT_PUT_REF_AND_RESET(_port)
	Decrements the reference count of the input port _port, and then sets _port to `NULL`.

#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`.

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.

void	bt_port_output_get_ref (const bt_port_output *port)
	Increments the reference count of the output port port.

void	bt_port_output_put_ref (const bt_port_output *port)
	Decrements the reference count of the output port port.

#define	BT_PORT_OUTPUT_PUT_REF_AND_RESET(_port)
	Decrements the reference count of the output port _port, and then sets _port to `NULL`.

#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`.

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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 )

extern

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.

Detailed Description

Properties

Type query

Types

Connection access

Component access

Properties

Reference count (common)

Input port

Output port

Enumeration Type Documentation

◆ bt_port_type

Macro Definition Documentation

◆ BT_PORT_PUT_REF_AND_RESET

◆ BT_PORT_MOVE_REF

◆ BT_PORT_INPUT_PUT_REF_AND_RESET

◆ BT_PORT_INPUT_MOVE_REF

◆ BT_PORT_OUTPUT_PUT_REF_AND_RESET

◆ BT_PORT_OUTPUT_MOVE_REF

Function Documentation

◆ bt_port_get_type()

◆ bt_port_is_input()

◆ bt_port_is_output()

◆ bt_port_borrow_connection_const()

◆ bt_port_borrow_component_const()

◆ bt_port_get_name()

◆ bt_port_is_connected()

◆ bt_port_get_ref()

◆ bt_port_put_ref()

◆ bt_port_input_as_port_const()

◆ bt_port_input_get_ref()

◆ bt_port_input_put_ref()

◆ bt_port_output_as_port_const()

◆ bt_port_output_get_ref()

◆ bt_port_output_put_ref()