Jump to content

Technical Reference:Operator Library

From BCI2000 Wiki

The Operator Library is a shared library that encapsulates the Operator Module's core functionality into an easy-to-use interface that allows to embed Operator functionality into one's own application. This way, it is easy write your own Operator module, or to control BCI2000 from your own application, using any programming language that allows using a shared library (DLL).

System State

BCI2000 system state may be queried using BCI_GetStateOfOperation(), and modified using the BCI_SetConfig(), BCI_StartRun(), and BCI_StopRun() functions.

System state is one of the following:

BCI_StateUnavailable

The system is not available for changes to system state.

BCI_StateStartup

The Operator module is waiting for core modules to connect.

BCI_StateInitialization

Core modules are connected, the system is waiting to be parameterized via SetConfig().

BCI_StateResting

The system has been parameterized and is waiting for a StartRun() command.

BCI_StateSuspended

The system has been suspended via StopRun(), or from one of the modules setting the "Running" state variable to 0.

BCI_StateParamsModified

The system has been suspended, and parameters have been modified from one or more of the core modules.

BCI_StateRunning

The system is running.

BCI_StateTermination

The system is waiting for termination.

BCI_StateBusy

The system is currently busy, and not in one of the above states. It is not available for changes to system state.

System state may be manipulated calling one of the following functions:

int BCI_GetStateOfOperation()

Determines the externally visible state of the state machine, i.e. the state of operation of the BCI2000 system.

int BCI_SetConfig()

Applies current parameter settings to the BCI2000 system.

returns
1 if successful, 0 otherwise.

int BCI_StartRun()

Starts a new run.

returns
1 if successful, 0 otherwise.

int BCI_StopRun()

Stops the current run.

returns
1 if successful, 0 otherwise.

Parameterization

Parameterization functions allow the population and modification of the Operator Library's internal parameter list, state list, and visproperty list. When calling SetConfig(), parameter values are applied to the BCI2000 system. Setting a state via BCI_SetStateValue() may result in a change to BCI2000 system state.

int BCI_PutParameter( const char* parameterLine )

Parses a BCI2000 parameter definition line, and adds the resulting parameter object to the internal parameter list, or changes the value of a parameter if it exists.

arguments
Pointer to a null-terminated parameter line string.
returns
1 if successful, 0 otherwise.

const char* BCI_GetParameter( long index )

Returns the parameter with the given index from the operator's internal parameter list.

arguments
Parameter index.
returns
Pointer to a null-terminated string containing a parameter line, or NULL. The output buffer is allocated by the library, and should be released by the caller using BCI_ReleaseObject().

int BCI_PutState( const char* stateLine )

Parses a BCI2000 state definition line, and adds the resulting state to the operator library's state list.

arguments
Pointer to a null-terminated state line string.
returns
1 if successful, 0 otherwise.

const char* BCI_GetState( long index )

Returns the state with the given index from the DLL's internal state list.

arguments
State index.
returns
Pointer to a null-terminated string containing a state line, or NULL. The output buffer is allocated by the library, and should be released by the caller using BCI_ReleaseObject().

int BCI_SetStateValue( const char* stateName, long value )

Sets the value of a state to a given value.

arguments
Pointer to a null-terminated state name string; new state value.
returns
1 if successful, 0 otherwise.

int BCI_PutVisProperty( const char* visID, int cfgID, const char* value )

Sets the a property to the given value, or adds the property to the property list if it is not present.

arguments
Pointer to a null-terminated vis ID string, numeric config ID, and a pointer to a null-terminated value string.
returns
1 if successful, 0 otherwise.

const char* BCI_GetVisProperty( const char* visID, int cfgID )

Returns the property with the given index from the DLL's internal property list. When a visID is given, results are restricted to properties with the respective visID.

arguments
Pointer to a null-terminated vis ID string, numeric config ID.
returns
Pointer to a null-terminated string containing a property line, or NULL. The output buffer is allocated by the library, and should be released by the caller using BCI_ReleaseObject().

Callbacks

Whenever the Operator Library gets data, or its state is modified, a callback event is triggered, and a callback function is called, provided it has been registered with BCI_SetCallback() or BCI_SetExternalCallback(). The difference between the two registration functions is that the first registers a callback function to be called within an internal thread of the Operator Library, while the second registers a callback function to be executed in an "external" thread. For this to work, the desired "external" thread needs to call BCI_CheckPendingCallback() often, e.g. from a GUI message handling loop.

Callback events are listed with their event names, and their handler's arguments. The refdata pointer is an arbitrary value that may be registered together with the callback function.

BCI_OnSystemStateChange( void* refdata )

Occurs on any change to BCI2000 system state.

BCI_OnCoreInput( void* refdata )

Occurs on input from any of the BCI2000 core modules.

BCI_OnConnect( void* refdata )

Occurs when core modules have connected to the Operator Library.

BCI_OnSetConfig( void* refdata )

Triggered when SetConfig() is called.

BCI_OnStart( void* refdata )

Triggered when StartRun() is called.

BCI_OnSuspend( void* refdata )

Triggered when BCI2000 goes into suspended state.

BCI_OnResume( void* refdata )

Triggered when BCI2000 enters the running state again.

BCI_OnShutdown( void* refdata )

Triggered when BCI_Shutdown() is called.

BCI_OnLogMessage( void* refdata, const char* msg )

Triggered for each log message arriving from one of the modules, including the Operator module.

BCI_OnWarningMessage( void* refdata, const char* msg )

Triggered for warning messages. Note that also a BCI_OnLogMessage event is triggered for warning messages.

BCI_OnErrorMessage( void* refdata, const char* msg )

Triggered for error messages. Note that also a BCI_OnLogMessage event is triggered for error messages.

BCI_OnDebugMessage( void* refdata, const char* msg )

Triggered for each Programming_Reference:Debug_Output debug message arriving at the Operator module.

BCI_OnParameter( void* refdata, const char* parameterline )

Triggered whenever a parameter message arrives at the Operator module.

BCI_OnState( void* refdata, const char* stateline )

Triggered whenever a state message arrives at the Operator module.

BCI_OnVisPropertyMessage( void* refdata, const char* name, int cfgID, const char* value )

Triggered whenever a visproperty message arrives at the Operator module.

BCI_OnVisProperty( void* refdata, const char* name, int cfgID, const char* value )

Triggered when a visualization property is modified from a script.

BCI_OnInitializeVis( void* refdata, const char* visID, const char* kind )

Triggered when the first data message for a visualization window arrives. The kind argument contains a string describing the kind of visualization required for; it is one of "Graph", "Memo", or "Bitmap".

BCI_OnVisMemo( void* refdata, const char* visID, const char* msg )

Triggered for each memo data message to a visualization window. The visID argument specifies the window's visualization ID, the msg argument specifies the memo data.

BCI_OnVisSignal( void* refdata, const char* visID, int channels, int elements, float* data )

Triggered for each signal data message to a visualization window. Data are given such that the pair of indices (ch,el) corresponds to the single index ch*elements+el. Note that this is different from the layout of bitmap data.

BCI_OnVisBitmap( void* refdata, const char* visID, int width, int height, unsigned short* data )

Triggered for each bitmap data message to a visualization window. Data are given in 15-bit RGB format, with one extra bit allowing for negative values to enable processing of difference images. For data, the pair of indices (x,y) corresponds to the single index y*width+x. Note that this is different from the layout of signal messages.

BCI_OnUnknownCommand( void* refdata, const char* command )

Triggered when the Operator scripting engine meets an unknown command. The event handler can extend the set of known commands by executing commands that are unknown to the scripting engine.

BCI_OnScriptError( void* refdata, const char* msg )

Triggered when script execution results in an error condition. Note that unknown commands are reported through the BCI_OnUnknownCommand event handler.

int BCI_SetCallback( long, BCI_Function, void* )

Register a callback function. To clear a callback function, specify NULL as a function pointer.

arguments
Event ID, callback function pointer, data pointer. The callback function pointer must be cast to the BCI_Function function pointer type. The data pointer may be any data that should be available to the callback function.
returns
1 if successful, 0 otherwise.

int BCI_SetExternalCallback( long, BCI_Function, void* )

Register a callback function to be executed in an external thread on execution of BCI_CheckPendingCallback(). To clear a callback function, specify NULL as a function pointer.

arguments
Event ID, callback function pointer, data pointer. The callback function pointer must be cast to the BCI_Function function pointer type.
returns
1 if successful, 0 otherwise.

int BCI_CheckPendingCallback()

Call this function regularly from within an external thread you want external callbacks to run in.

arguments
None.
returns
1 if a callback was executed, 0 otherwise.

BCI_Function BCI_GetCallbackFunction( long )

Get a registered callback function pointer.

arguments
Event ID.
returns
Callback function pointer, or NULL if no callback function has been registered for the specified event.

void* BCI_GetCallbackData( long )

Get registered callback data. Callback data is the first argument to callback functions, and specified when calling SetCallback() or SetExternalCallback().

arguments
Event ID.
returns
Callback data, or NULL if no callback data has been registered for the specified event.

Miscellaneous Functions

/* function: BCI_GetInfo purpose: Reports build and source version information. arguments: None. returns: Pointer to a null-terminated string holding the information requested. 

          The output buffer is allocated by the library, and should be released
          by the caller using BCI_ReleaseObject().
  • /

DLLEXPORT const char* STDCALL BCI_GetInfo( void );

/* function: BCI_GetConnectionInfo purpose: Obtains information about a core module connection. argument: Zero-based index of core module connection. returns: Pointer to a null-terminated string containing connection information. 

          The output buffer is allocated by the library, and should be released
          by the caller using BCI_ReleaseObject().
  • /

DLLEXPORT const char* STDCALL BCI_GetConnectionInfo( int index );

/* function: BCI_GetCoreModuleStatus purpose: Obtains a core module's current status message. argument: Zero-based index of core module connection. returns: Pointer to a null-terminated string containing status information. 

          The output buffer is allocated by the library, and should be released
          by the caller using BCI_ReleaseObject().
  • /

DLLEXPORT const char* STDCALL BCI_GetCoreModuleStatus( int index );

/* function: BCI_Startup purpose: Startup of the operator controller object. arguments: A string defining core module listening addresses in the form 

            <ip1>:<port1> <ip2:port2> ... <ipN:portN>
          If NULL, a value of
            localhost:4000 localhost:4001 localhost:4002
          reflecting the standard BCI2000 configuration is used.

returns: 1 if successful, 0 otherwise.

  • /

DLLEXPORT int STDCALL BCI_Startup( const char* moduleList );

/* function: BCI_Shutdown purpose: Close all connections opened by the library, and dispose of all 

          resources allocated.

arguments: n/a returns: 1 if successful, 0 otherwise.

  • /

DLLEXPORT int STDCALL BCI_Shutdown( void );

/* function: BCI_Initialize purpose: Initialize the library. Must be called before any other library 

          function is used.

arguments: n/a returns: 1 if no error occurred, 0 otherwise.

  • /

DLLEXPORT int STDCALL BCI_Initialize( void );

/* function: BCI_Dispose purpose: Dispose of all resources allocated by the library. arguments: n/a returns: 1 if no error occurred, 0 otherwise.

  • /

DLLEXPORT int STDCALL BCI_Dispose( void );

/* function: BCI_ExecuteScript purpose: Interprets and executes the specified script. arguments: Null-terminated string specifying script commands. returns: 0 if a syntax error is present, 1 otherwise.

  • /

DLLEXPORT int STDCALL BCI_ExecuteScript( const char* script );

/* function: BCI_ReleaseObject purpose: Indicate that an object that has been allocated by the library is no longer 

          needed by the library's client.

arguments: Object to be released, or NULL. returns: 1 if successful, 0 otherwise.

  • /

DLLEXPORT int STDCALL BCI_ReleaseObject( const char* );

Retrieved from "http://www.bci2000.org/mediawiki/index.php?title=Technical_Reference:Operator_Library&oldid=5850"