Control interface

Control interface
Prev	Application interface	Next

The control (and monitoring) interface is based on a simple protocol using message passing, in which all message transactions are initiated by any process that is not the input stage process. The interface is based on a message-oriented socket, either a Unix domain socket or a UDP/IP socket, the choice of which is made at compile time.^[9] Generally, the Unix domain socket is rarely used, low level development and testing being the cases in which it is most likely of use. A message transaction is initiated with a WCBE_REQUESTmessage received on the input stage process' control socket, ctlsock, followed by a return WCBE_RESPONSE message to the originating socket. WCBE_REQUEST messages are tagged so that a WCBE_RESPONSE message can be properly associated with the initial WCBE_REQUEST message by the originating process.^[10] WCBE_REQUEST messages are classified as either WCBE_COMMAND or WCBE_QUERY messages, whose meanings are hopefully clear to the reader.

Message types

There follows a list of the message types that are used by the control interface. The message names are the enumeration symbols used in the source code. In the description of each message type, if a mention is made of the fields in the message, these only refer to the fields specific to the message in question, and do not refer to fields common to all message types. WCBE_COMMAND WCBE_RESPONSE messages generally return the same message content that was sent in the WCBE_REQUEST message. WCBE_QUERY WCBE_REQUEST messages generally leave the message type-specific field(s) empty.

WCBE_CONFIG_CREATE_MSG

Create configuration. Two message fields: name, a configuration identifier; and desc, the XML configuration document (that is, the entire document as a string, not a file name). Only exists as a WCBE_COMMAND message.

WCBE_CONFIG_ACTIVATE_MSG

Activate configuration. One message field: name, the configuration name. WCBE_COMMAND only.

WCBE_CONFIG_DESTROY_MSG

Destroy configuration. One message field: name, configuration name. WCBE_COMMAND only.

WCBE_CONFIG_LIST_MSG

Configuration list. One message field: list, a NULL-terminated list of existing configuration names and pending configuration actions (each configuration name being a NULL-terminated string). The name of a configuration is surrounded by square brackets (“[name]”) when the configuration is active but marked for destruction, angle brackets (“<name>” when active but not marked for destruction, parentheses (“(name)”) when inactive, asterisks (“*name*”) when pending creation, hash marks (“#name#”) when pending activation, and the at sign (“@name@”) when pending destruction. Pending configuration actions occur when the wcbe application has been started, but its pipeline is not running due to lack of a lag frame source setting, or the pipeline flow being turned off. WCBE_QUERY only; WCBE_REQUEST list field is ignored by input stage.

WCBE_SRC_MSG

Input stage lag frame source. One message field: name, lag frame source URI.

WCBE_FRAMEDUMP_MSG

Raw lag frame dump value. One message field: format, WCBE_DUMP_NONE to inhibit frame dumping; WCBE_DUMP_ASCII to dump frames in ASCII format; WCBE_DUMP_BINARY to dump frames in binary format.

WCBE_FLOW_MSG

Pipeline flow. One message field: state, WCBE_FLOW_OFF to inhibit pipeline data flow; WCBE_FLOW_ON to allow pipeline data flow.

WCBE_LIVE_TS_MSG

“Live timestamps” value. One message field: state, TRUE to rewrite file lag frame data timestamps, FALSE otherwise.

WCBE_RATE_MSG

Frame rate (file lag frame source only). One message field: fps, frame rate in frames per second.

WCBE_NAME_MSG

Input stage instance name. One message field: name, instance name. WCBE_QUERY only.

WCBE_QUIT_MSG

Quit input stage application. One reserved, unused message field. WCBE_COMMAND only.

WCBE_PIPELINE_LIST_MSG

List of GStreamer pipeline names in a given configuration. One message field: configuration, the configuration name. WCBE_QUERY only.

WCBE_ELEMENT_LIST_MSG

List of GStreamer element names in a given pipeline. One message field: pipeline, the pipeline name in the format

[configuration name]/[pipeline name]

WCBE_QUERY only.

WCBE_PROPERTY_LIST_MSG

List of properties of a given GStreamer element. One message field: element, the element name in the format

[configuration name]/[pipeline name]/[element name]

WCBE_QUERY only.

WCBE_PROPERTY_MSG

GStreamer element property value. Message fields:

property

Property name in the format

[configuration name]/[pipeline name]/[element name]/[property name]

type

Value type (a GType name). A return value for a WCBE_QUERY message: the property value type. An input parameter for a WCBE_COMMAND message: the type of the value given in the value message field.

value

Property value. A return value for a WCBE_QUERY message. An input parameter for a WCBE_COMMAND message.

Both WCBE_QUERY and WCBE_COMMAND.

WCBE_PAD_LIST_MSG

List of pads for a given GStreamer element. One message field: element, the element name in the format

[configuration name]/[pipeline name]/[element name]

WCBE_QUERY only.

WCBE_PAD_CAPS_MSG

The negotiated capabilities of a given pad on a GStreamer element. Two message fields:

pad

The pad name in the format

[configuration name]/[pipeline name]/[element name]/[pad name]

caps

The (negotiated) pad caps.

WCBE_QUERY only.

WCBE_PAD_PEER_MSG

The peer of a given pad on a GStreamer element. Two message fields:

pad

The pad name in the format

[configuration name]/[pipeline name]/[element name]/[pad name]

peer

The pad's peer in the format

[element name]/[pad name]

where the named element is in the same pipeline as the queried pad.

WCBE_QUERY only.

^[9]I am investigating the use of an SCTP socket as well, but this work in not done.

^[10]The system is relatively robust to simultaneous access by multiple processes, assuming that each process has its own socket by which to communicate with the input stage.