Programming Reference:EnvironmentExtension Class

From BCI2000 Wiki
Jump to: navigation, search

Location

BCI200/src/shared/accessors

Synopsis

The EnvironmentExtension class defines an interface for BCI2000 components ("extensions") that are not filters. Such extensions do not process signals but still have access to BCI2000 parameters and state variables, and are notified of system events such as Preflight, Initialize, and StartRun.

Components that don't need to handle system events may inherit from the Environment class directly rather than indirectly via EnvironmentExtension.

Events

Publish

This event handler is called during the BCI2000 publishing phase. Its purpose is to request parameters and states from the system. To simplify requesting parameters and states, and to provide markers that allow to find and extract parameter and states requests, a number of BEGIN/END macros is defined that allow writing

BEGIN_PARAMETER_DEFINITIONS
 "section int param1= 0 % % % // comment",
 ... // any number of parameter definition lines may follow here
END_PARAMETER_DEFINITIONS

BEGIN_STATE_DEFINITIONS
 "",
... // any number of state definition lines may follow here
END_STATE_DEFINITIONS

There, BEGIN/END macros enclose lists of comma-separated C strings representing parameter or state definition lines, respectively.

Preflight

Called during the system initialization phase. In this event handler, the extension component is supposed to test parameter values for consistency, and to report errors by writing into the bcierr stream. When no error is reported, it is assumed that the component's operation is safe.

Initialize

Called during the system initialization phase. In the Initialize() event handler, a component should initialize itself from parameter values. Ideally, the component's state should not depend on the component's past history prior to the last call to Initialize().

PostInitialize

Called after the system initialization phase has been completed for all GenericFilter components.

StartRun

Called when a new run begins. Extension components' StartRun handler is called prior to calling GenericFilter component's StartRun handlers.

PostStartRun

Called after StartRun has been called for all GenericFilter components.

StopRun

Called at the end of a run, before StopRun is called for any GenericFilter component.

PostStopRun

Called after StopRun has been called for all GenericFilter components.

Process

Called while the system is running, once for each data block, prior to GenericFilter components.

PostProcess

Called while the system is running, once for each data block, after all GenericFilter components have completed processing.

Resting

Called while the system is suspended. Typically, Resting is called repeatedly inside source modules; in the remaining modules, Resting is called once when the system enters suspended state. Except that it is called at least once in suspended state, you should not make any assumption how often Resting is called.


Methods

ParamRef Parameter(string Name)

The Parameter() method returns a reference to a parameter that may be used for reading and writing parameters. When there is no parameter with the specified name available in the system, or when it has not been accessed from the component's Preflight() handler, an error message is displayed. For details, see Accessing Environment Objects.

ParamRef OptionalParameter(string Name, value Default)

The OptionalParameter() method is identical to the Parameter() method except that it does not generate an error message for an unavailable parameter; rather, a reference to a temporary parameter object is returned, initialized to a default value. The default value may be specified as a number or a string, and itself defaults to "0".

StateRef State(string Name)

The State() method returns a reference to a state variable that may be used for reading and writing states. When there is no state variable with the specified name available in the system, an error message is displayed. For details, see Accessing Environment Objects.

StateRef OptionalState(string Name)

The OptionalState() method is identical to the State() method except that it does not generate an error message for an unavailable state; rather, a reference to a temporary state object is returned, initialized to a default value. The default value may be specified as a number or a string, and itself defaults to "0".

Instantiation

EnvironmentExtension components may be used freely as members or ancestors of any other class in a BCI2000 module. When writing an extension component that is independent of existing classes, it may be instantiated from its own source code file by putting a

Extension( ClassName );

statement at the top of that file.

See also

Programming Reference:GenericFilter Class, Technical Reference:States of Operation, Technical Reference:Parameter Definition, Technical Reference:State Definition, Programming Reference:Error Handling#Accessing Environment Objects