Technical Reference:Operator Library: Difference between revisions

Revision as of 15:43, 13 January 2011

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()

purpose: Applies current parameter settings to the BCI2000 system. returns: 1 if successful, 0 otherwise.

int BCI_StartRun()

purpose: Starts a new run. returns: 1 if successful, 0 otherwise.

int BCI_StopRun()

purpose: Stops the current run. returns: 1 if successful, 0 otherwise.

Parameterization

/* function: BCI_PutParameter purpose: 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.

/

DLLEXPORT int STDCALL BCI_PutParameter( const char* parameterLine );

/* function: BCI_GetParameter purpose: 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().

/

DLLEXPORT const char* STDCALL BCI_GetParameter( long index );

/* function: BCI_PutState purpose: 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.

/

DLLEXPORT int STDCALL BCI_PutState( const char* stateLine );

/* function: BCI_GetState purpose: 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().

/

DLLEXPORT const char* STDCALL BCI_GetState( long index );

/* function: BCI_SetStateValue purpose: 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.

/

DLLEXPORT int STDCALL BCI_SetStateValue( const char* stateName, long value );

/* function: BCI_PutVisProperty purpose: Sets the a property to the given value, or adds the property to

          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.

/

DLLEXPORT int STDCALL BCI_PutVisProperty( const char* visID, int cfgID, const char* value );

/* function: BCI_GetVisProperty purpose: 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().

/

DLLEXPORT const char* STDCALL BCI_GetVisProperty( const char* visID, int cfgID );

Callbacks

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* );