Programming Reference:EnvironmentExtension Class
- 1 Location
- 2 Synopsis
- 3 Events
- 4 Methods
- 5 Instantiation
- 6 See also
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.
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
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.
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().
Called after StartRun has been called for all GenericFilter components.
Called after StopRun has been called for all GenericFilter components.
Called while the system is running, once for each data block, prior to GenericFilter components.
Called while the system is running, once for each data block, after all GenericFilter components have completed processing.
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.
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".
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.
Programming Reference:GenericFilter Class, Technical Reference:States of Operation, Technical Reference:Parameter Definition, Technical Reference:State Definition, Programming Reference:Error Handling#Accessing Environment Objects