Programming Reference:EnvironmentExtension Class

Location

BCI2000/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_STREAM_DEFINITIONS
 "MyState 1 0",
... // any number of stream state definition lines may follow here
END_STREAM_DEFINITIONS

BEGIN_EVENT_DEFINITIONS
 "MyEvent 16 0",
... // any number of event definition lines may follow here
END_EVENT_DEFINITIONS

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

AutoConfig

Called during the system initialization phase. In this event handler, the extension component is supposed to automatically configure itself according to sensible defaults, or hardware properties. Using the Parameter() function (see below), the event handler can write to all parameters defined during the Publish event. Only parameters set to "auto" will be modified, though. This way, the user can decide whether a certain parameter should be auto-configured or not.

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.

For EnvironmentExtension components that use command line parameters for enabling, the constructor should contain one PublishEnabler() call for each enabler parameter. For example, the Keylogger extension allows to log from keyboard, mouse, or both:

Keylogger::Keylogger()
{
  PublishEnabler("LogKeyboard");
  PublishEnabler("LogMouse");
}

These calls help the BCI2000Launcher program to identify extensions present in BCI2000 modules, and they tell it how to enable features provided by extensions.