Jump to content

Technical Reference:BCI2000Remote Library: Difference between revisions

From BCI2000 Wiki
← Older edit
Mellinger (talk | contribs)
5,520 edits
Mellinger (talk | contribs)
5,520 edits
 
(7 intermediate revisions by 2 users not shown)
Line 2: Line 2:


==Functions specific to the Library==
==Functions specific to the Library==
===int BCI2000Release( void* )===
purpose:  Releases a string buffer, or other object allocated by the library.
arguments: String pointer, or handle to object allocated by one of the library functions.
returns:  1 if successful, 0 otherwise.


===void* BCI2000Remote_New( void )===
===void* BCI2000Remote_New( void )===
Line 44: Line 38:
==BCI2000Remote Member Functions==
==BCI2000Remote Member Functions==
The following functions are property accessors, and member functions of BCI2000Remote
The following functions are property accessors, and member functions of BCI2000Remote
objects. For documentation, see "Programming Reference:BCI2000Remote Class" on
objects. For documentation, see [[Programming Reference:BCI2000Remote Class]] on
the BCI2000 wiki.
the BCI2000 wiki.
In the C-style interface, each function takes a handle to an existing BCI2000Remote
In the C-style interface, each function takes a handle to an existing BCI2000Remote
object as its first argument. Use BCI2000Remote_New() to create such objects.
object as its first argument. Use BCI2000Remote_New() to create such objects.
When a function returns a C string, the caller is responsible for releasing that string
When a function returns a C string, the string exists in a per-thread buffer, and may not be
once it is done with it. This is done by calling BCI2000Release() on the string.
released by the caller. For backward compatibility, calling BCI2000Release() on the string is allowed but will have no effect.
Functions that return a C string may return NULL to indicate failure.
Functions that return a C string may return NULL to indicate failure.


Line 76: Line 70:


===const char* BCI2000Remote_GetResult( void* )===
===const char* BCI2000Remote_GetResult( void* )===
Returns the string result of the previous command.


===const char* BCI2000Remote_GetSubjectID( void* )===
===const char* BCI2000Remote_GetSubjectID( void* )===
Line 89: Line 84:
===int BCI2000Remote_Disconnect( void* )===
===int BCI2000Remote_Disconnect( void* )===


===int BCI2000Remote_Execute( void*, const char* )===
===int BCI2000Remote_Execute( void*, const char*, int* )===
NB: This function returns the last command's execution status, which
NB: This function returns the last command's execution status, which
is a true integer, with a value of 0 indicating success in most cases.
is a true integer, with a value of 0 indicating success in most cases.
All other int-returning functions return a boolean integer which is
All other int-returning functions return a boolean integer which is
1 on success, and 0 on failure.
1 on success, and 0 on failure.
The last argument (which may be a null pointer) holds a pointer to an integer
that receives the parsed string result of the command, which is typically 1
for success, and 0 for failure.
To obtain the actual string result of an executed command, call <tt>BCI2000Remote_GetResult()</tt>
immediately after calling the <tt>BCI2000RemoteExecute()</tt> command.


===int BCI2000Remote_StartupModules( void*, const char* )===
===int BCI2000Remote_StartupModules( void*, const char* )===
Line 99: Line 101:
with command line arguments in the form
with command line arguments in the form
  const char* list = "module1 -arg1 -arg2\0module2 -arg1\0module3 -arg1\0\0";
  const char* list = "module1 -arg1 -arg2\0module2 -arg1\0module3 -arg1\0\0";
===int BCI2000Remote_StartupModules2( void*, const char**, int )===
As an alternative to <tt>StartupModules()</tt>, provide an array of <tt>const char*</tt> in the second argument,
and the number of entries in the array in the third:
const char* list[] = { "module1 -arg1 -arg2", "module2 -arg1", "module3 -arg1" };
int result = BCI2000Remote_StartupModules2(handle, list, 3);
===int BCI2000Remote_LoadParametersLocal( void*, const char* )===
===int BCI2000Remote_LoadParametersLocal( void*, const char* )===
===int BCI2000Remote_LoadParametersRemote( void*, const char* )===
===int BCI2000Remote_LoadParametersRemote( void*, const char* )===
Line 114: Line 123:
===int BCI2000Remote_SetStateVariable( void*, const char*, double )===
===int BCI2000Remote_SetStateVariable( void*, const char*, double )===
===int BCI2000Remote_GetStateVariable( void*, const char*, double* )===
===int BCI2000Remote_GetStateVariable( void*, const char*, double* )===
===int BCI2000Remote_AddEventVariable( void*, const char* name, unsigned int bitWidth, double initialValue )===
===int BCI2000Remote_SetEventVariable( void*, const char*, double )===
===int BCI2000Remote_PulseEventVariable( void*, const char*, double )===
===int BCI2000Remote_GetEventVariable( void*, const char*, double* )===


===int BCI2000Remote_SetScript( void*, const char*, const char* )===
===int BCI2000Remote_SetScript( void*, const char*, const char* )===
Line 119: Line 132:


==See also==
==See also==
[[Programming Reference:BCI2000Remote Class]], [[Contributions:BCI2000Command]], [[Contributions:BCI2000PresentationLink]], [[Contributions:BCI2000Automation]]
[[Programming Reference:BCI2000Remote Class]], [[Contributions:BCI2000Command]], [[Contributions:BCI2000PresentationLink]], <!--[[Contributions:BCI2000Automation]],-->
[[Contributions:Applications]]
[[Contributions:Applications]]


[[Category:External Interfaces]][[Category:User Application]]
[[Category:External Interfaces]][[Category:User Application]]

Latest revision as of 15:53, 28 April 2026

The BCI2000Remote Library provides a C interface to the BCI2000Remote C++ class. It may be used to control the BCI2000 Operator module from external applications. The BCI2000Remote library can be used from any programming language that allows using a shared library (DLL). Although the BCI2000Remote library is written in C++, its DLL interface is plain C, and can be used with compiled languages such as C, C++, C#, Pascal, but also with interpreted languages that can call functions in a DLL, such as Python, Matlab, VisualBasic, etc. Interfacing with Java requires a JNI (Java Native Interface) wrapper, which is currently not provided by BCI2000.

Functions specific to the Library

void* BCI2000Remote_New( void )

purpose: Creates a new BCI2000Remote object.

arguments: None.

returns: A handle to the newly created object.

int BCI2000Remote_Delete( void* )

purpose: Deletes a BCI2000Remote object.

arguments: Handle to an existing BCI2000Remote object.

returns: 1 if successful, 0 otherwise.

void WatchCallback( void*, const char* )

purpose: Prototype for a callback function that is called when a watch is triggered.

arguments: Pointer to user data as specified when BCI2000Remote_NewWatch() was called; values of expressions that triggered the watch.

void* BCI2000Remote_NewWatch( void* bci2000RemoteObject, const char* expression, WatchCallback, void* )

purpose: Creates a new BCI2000Remote watch object.

arguments: Handle to an existing BCI2000Remote object; Expression to watch; Pointer to callback function; Pointer to user data for callback function.

returns: Handle to newly created watch, or NULL if not successful.

int BCI2000Remote_DeleteWatch( void* )

purpose: Deletes a BCI2000Remote watch object.

arguments: Handle to an existing BCI2000Remote watch object.

returns: 1 if successful, 0 otherwise.

BCI2000Remote Member Functions

The following functions are property accessors, and member functions of BCI2000Remote objects. For documentation, see Programming Reference:BCI2000Remote Class on the BCI2000 wiki. In the C-style interface, each function takes a handle to an existing BCI2000Remote object as its first argument. Use BCI2000Remote_New() to create such objects. When a function returns a C string, the string exists in a per-thread buffer, and may not be released by the caller. For backward compatibility, calling BCI2000Release() on the string is allowed but will have no effect. Functions that return a C string may return NULL to indicate failure.

double BCI2000Remote_GetTimeout( void* )

void BCI2000Remote_SetTimeout( void*, double timeout )

const char* BCI2000Remote_GetOperatorPath( void* )

void BCI2000Remote_SetOperatorPath( void*, const char* )

int BCI2000Remote_GetWindowVisible( void* )

void BCI2000Remote_SetWindowVisible( void*, int visible )

enum
{
  BCI2000Remote_Invisible = 0,
  BCI2000Remote_Visible = 1,
  BCI2000Remote_NoChange = 2,
};

const char* BCI2000Remote_GetWindowTitle( void* )

void BCI2000Remote_SetWindowTitle( void*, const char* )

const char* BCI2000Remote_GetTelnetAddress( void* )

void BCI2000Remote_SetTelnetAddress( void*, const char* )

int BCI2000Remote_GetConnected( void* )

const char* BCI2000Remote_GetResult( void* )

Returns the string result of the previous command.

const char* BCI2000Remote_GetSubjectID( void* )

void BCI2000Remote_SetSubjectID( void*, const char* )

const char* BCI2000Remote_GetSessionID( void* )

void BCI2000Remote_SetSessionID( void*, const char* )

const char* BCI2000Remote_GetDataDirectory( void* )

void BCI2000Remote_SetDataDirectory( void*, const char* )

int BCI2000Remote_Connect( void* )

int BCI2000Remote_Disconnect( void* )

int BCI2000Remote_Execute( void*, const char*, int* )

NB: This function returns the last command's execution status, which is a true integer, with a value of 0 indicating success in most cases. All other int-returning functions return a boolean integer which is 1 on success, and 0 on failure.

The last argument (which may be a null pointer) holds a pointer to an integer that receives the parsed string result of the command, which is typically 1 for success, and 0 for failure.

To obtain the actual string result of an executed command, call BCI2000Remote_GetResult() immediately after calling the BCI2000RemoteExecute() command.

int BCI2000Remote_StartupModules( void*, const char* )

Provide a zero-delimited list of C strings, containing module names with command line arguments in the form 

const char* list = "module1 -arg1 -arg2\0module2 -arg1\0module3 -arg1\0\0";

int BCI2000Remote_StartupModules2( void*, const char**, int )

As an alternative to StartupModules(), provide an array of const char* in the second argument, and the number of entries in the array in the third: 

const char* list[] = { "module1 -arg1 -arg2", "module2 -arg1", "module3 -arg1" };
int result = BCI2000Remote_StartupModules2(handle, list, 3);

int BCI2000Remote_LoadParametersLocal( void*, const char* )

int BCI2000Remote_LoadParametersRemote( void*, const char* )

int BCI2000Remote_SetConfig( void* )

int BCI2000Remote_Start( void* )

int BCI2000Remote_Stop( void* )

int BCI2000Remote_Quit( void* )

const char* BCI2000Remote_GetSystemState( void* )

int BCI2000Remote_GetControlSignal( void*, int, int, double* )

int BCI2000Remote_SetParameter( void*, const char* name, const char* value )

const char* BCI2000Remote_GetParameter( void*, const char* name )

int BCI2000Remote_AddStateVariable( void*, const char* name, unsigned int bitWidth, double initialValue )

int BCI2000Remote_SetStateVariable( void*, const char*, double )

int BCI2000Remote_GetStateVariable( void*, const char*, double* )

int BCI2000Remote_AddEventVariable( void*, const char* name, unsigned int bitWidth, double initialValue )

int BCI2000Remote_SetEventVariable( void*, const char*, double )

int BCI2000Remote_PulseEventVariable( void*, const char*, double )

int BCI2000Remote_GetEventVariable( void*, const char*, double* )

int BCI2000Remote_SetScript( void*, const char*, const char* )

const char* BCI2000Remote_GetScript( const char* )

See also

Programming Reference:BCI2000Remote Class, Contributions:BCI2000Command, Contributions:BCI2000PresentationLink, Contributions:Applications

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