NetCom Client API Overview

NetCom is not a program; it is an application programming interface (API) that you can use to create your own custom programs to monitor and control Cheetah. This requires that you have some programming knowledge in a language that is supported by NetCom: C++, .NET (e.g. C#, VB.NET, etc,) any .NET aware application such as LabView and MATLAB. MATLAB is actually a special case whose operation differs from the other implementations of NetCom (see MATLAB NetCom Interface).

Documentation Links:

Provided NetCom Implementations and Examples
C++ Project Setup
.NET Project Setup
MATLAB Project Setup
MATLAB NetCom Interface
MNetCom Namespace API Documentation*
MNetComClient API Documentation*

*All API documentation is shown using the C# programming language. All function signatures and object definitions are identical and can be directly translated to other .NET languages as well as C++. For C++ applications all Delegate objects can be treated as normal C/C++ callback functions. See MFC examples for details. All documentation for the MATLAB NetCom functions are available by typing "help <funcition_name>" (e.g. >help NlxConnectToServer) at the MATLAB command prompt.

Provided NetCom Implementations and Examples

Included in the NetCom Development Package are implementations of NetCom for use with multiple languages and environments as well as example applications that serve as an introduction to using the NetCom Client API. The following table lists the supported languages as well as available example applications:

Language
 32 bit Library
 64 bit Library
 Supported Operating System
 Supported Development Environment
 Examples Provided (NetComExamples directory)(6)
C++ (7)
 NetComClient3.lib(1)
 NetComClientx3_64.lib(2)
 Windows XP, Vista, 7
 Visual Studio 2003 through 2012 including Express versions
 C++\SendNetComCommand
MFC\NetComExampleCommands(3)
MFC\NetComExampleStreams(3)
.NET 2.0+(4)
 MNetComClient3.dll(1)
 MNetComClientx3_64.dll(2)
 Windows XP, Vista, 7
 Visual Studio 2005 through 2012 including Express versions
 C#\NetComExampleCommands
C#\NetComExampleStreams
VB.NET\NetComExampleCommands
VB.NET\NetComExampleStreams
MATLAB
 MATLAB_M-files(5)
 MATLAB_M-files(5)
 Windows XP, Vista, 7
 MATLAB v7.6 (R2008a)
 MATLAB\MATLABNetComClientExample.m

NOTES:

(1) Requires NetComClient.dll to be in the same directory as the executable file of your program.

(2) Requires NetComClientx64.dll to be in the same directory as the executable file of your program.

(3) Requires MFC and will not work in Express versions of Visual Studio

(4) .NET 4.0 applications require special setup in order to use NetCom. See .NET Project Setup

(5) All required files for both 32 and 64 bit versions of MATLAB are contained in the MATLAB_M-files directory.

(6) All examples except MATLAB contain Visual Studio 2008 project files.

(7) Works only with wide character or Unicode projects.

C++ Project Setup

C++ projects must be linked against the appropriate 32 or 64 bit version of the NetComClient library. All header files in the Include directory must be accessible by the compiler. All projects must also be compiled with either wide character or Unicode support enabled.

.NET Project Setup

.NET projects must include the appropriate 32 or 64 bit version of the MNetComClient DLL as a reference in the project. Projects must be set specifically to either x86 or x64 platform and will not work with the Any CPU platform. .NET 4.0 projects must manually edit the app.config project file and include the following:

<startup useLegacyV2RuntimeActivationPolicy="true">
<supportedRuntime version="v4.0"/>
</startup>

MATLAB Project Setup

All of the files in the MATLAB_M-files directory must be accessible from the MATLAB path. Each M-file located in this directory implements a NetCom API function. Type "help <M-file name>" at the MATLAB command prompt for documentation.

MATLAB NetCom Interface

Over the years, there have been request for MATLAB integration, and last year we released the MATLAB interface to NetCom. It is called an interface to NetCom because MATLAB doesn't interact with NetCom the same way that the other languages (C++ and .NET) do.

The example script, MATLABNetComClientExamples.m, located in the NetComExamples/Matlb directory of the NetCom Development Package, will give you a good overview of what commands are utilized in a MATLAB script that interfaces with NetCom. There is also a step by step tutorial showing how to create a basic online placefield display using MATLAB included in the development package.

For the most part, the MATLAB interface to NetCom is very similar to the other NetCom libraries. All of the connection, control and query functions are identical. The major difference comes when retrieving data from Cheetah. Both the C++ and .NET versions of NetCom use push style data streaming. This means that when new data is available, NetCom calls a function in your application where you receive that new data, essentially pushing new data into your application. Since MATLAB isn't designed to receive streaming data from multiple sources, we had to make an interface for MATLAB that uses pull style data streaming. The NetCom interface will buffer all of the incoming data and hold it until your MATLAB script asks to receive new data, thereby pulling it into your script.

The catch is that since these buffers are of finite size, you need to pull data out of them periodically, or older data will be overwritten with new data. Because of this, all of the NlxGetNew*Data functions (e.g. NlxGetNewCSCData) also return the number of dropped records since the last call to the function. This will let you know how much data you didn't receive.

Another major difference introduced in the MATLAB interface to NetCom is how the recorded data is retrieved. Normally, NetCom returns a single array of recorded objects. Each record has fields containing the data from that record. In order to make the data retrieved from NetCom easier to work with in MATLAB, the interface returns each of those fields into separate MATLAB vectors. For instance, in C++ you would access the timestap for the 25th record returned using the following code:

returnedRecords[24].qwTimeStamp

In MATLAB, you would do the following:

returnedTimestamps(25)

More information on how the data fields are returned for each data type can be found with the help of the corresponding NlxGetNew*Data function.

While we always suggest running NetCom applications on a PC other than the one running Cheetah, this is even more important when MATLAB is used. Since MATLAB is a very resource intensive application, it can cause your computer to slow down if both it and Cheetah are running at the same time. If you do need to run both applications on the same PC, please test your system to see if it can handle both applications before recording critical data.


MNetCom - Type Definitions

 MNetCom Namespace for NetComClient v3.0
class MNetComClient

enum NLX_MessageType
Describes the type of message being sent to Cheetah. This enumeration is normally used with the LogMessageCheetah command.
NLXB_FATAL | The message pertains to a fatal error in the application. Normally used when the client application performs an unrecoverable operation.
NLXB_ERROR | The message is a normal application error. This message type should be used on all recoverable errors.
NLXB_WARNING | The message does not cause an error, but some abnormal condition exists, or an error may occur because of the current program state.
NLXB_NOTICE | Message is for general information or program execution state. Normally used for debugging and status messages.
NLXB_DATA | Message is intended as a data marker. Sending the message as an event is a better option.

struct MCRRec
Managed code (.NET) version of the Neuralynx continuously sampled record (CRRec).
UInt64 | qwTimeStamp | Cheetah timestamp for this record.
UInt32 | dwChannelNumber | The channel number for this record. This is NOT the A/D channel number.
UInt32 | dwSampleFreq | The sampling frequency for this channel.
UInt32 | dwNumValidSamples | Number of values in snSamples containing valid data.
Int16[ ] | snSamples | Data points for this record. Cheetah currently supports 512 data points per record. For the MCRRec, the snSamples array is a [512] array.

struct MEventRec
Managed code (.NET) version of the Neuralynx event record (EventRec).
Int16 | nstx | This value should always be decimal 800.
Int16 | npkt_id | ID for the originating system of this packet.
Int16 | npkt_data_size | This value should always be two (2).
UInt64 | qwTimeStamp | Cheetah timestamp for this record.
Int16 | nevent_id | ID value for this event.
Int16 | nttl | Decimal TTL value read from the TTL input port.
Int16 | ncrc | Record CRC check from Cheetah. Not used in consumer applications.
Int16 | ndummy1 | Reserved
Int16 | ndummy2 | Reserved
Int32[] | dnExtra | Extra bit values for this event. This array has a fixed length of eight (8).
String | EventString | Event string associated with this event record.

struct MSERec
Managed code (.NET) version of the Neuralynx single electrode record (SERec).
UInt64 | qwTimeStamp | Cheetah timestamp for this record.
UInt32 | dwScNumber | The spike acquisition entity number for this record. This is NOT the A/D channel number.
UInt32 | dwCellNumber | The classified cell number for this record. If no cells have been classified, this number will be zero.
UInt32[] | dnParams | Array of selected feature data for this spike channel. Cheetah currently allows eight (8) selected features, so this array is fixed at length eight.
Int32[ , ] | snData | Data points for this record. Cheetah currently supports 32 data points per spike record. The array is organized as [DATAPOINTS, CHANNEL]. For the MSERec, the snData array is a [32, 1] array.

struct MSTRec
Managed code (.NET) version of the Neuralynx stereotrode record (STRec).
UInt64 | qwTimeStamp | Cheetah timestamp for this record.
UInt32 | dwScNumber | The spike acquisition entity number for this record. This is NOT the A/D channel number.
UInt32 | dwCellNumber | The classified cell number for this record. If no cells have been classified, this number will be zero.
UInt32[] | dnParams | Array of selected feature data for this spike channel. Cheetah currently allows eight (8) selected features, so this array is fixed at length eight.
Int32[ , ] | snData | Data points for this record. Cheetah currently supports 32 data points per spike record. The array is organized as [DATAPOINTS, CHANNEL]. For the MSTRec, the snData array is a [32, 2] array.

struct MTTRec
Managed code (.NET) version of the Neuralynx tetrode record (TTRec).
UInt64 | qwTimeStamp | Cheetah timestamp for this record.
UInt32 | dwScNumber | The spike acquisition entity number for this record. This is NOT the A/D channel number.
UInt32 | dwCellNumber | The classified cell number for this record. If no cells have been classified, this number will be zero.
UInt32[] | dnParams | Array of selected feature data for this spike channel. Cheetah currently allows eight (8) selected features, so this array is fixed at length eight.
Int32[ , ] | snData | Data points for this record. Cheetah currently supports 32 data points per spike record. The array is organized as [DATAPOINTS, CHANNEL]. For the MTTRec, the snData array is a [32, 4] array.

struct MVideoRec
Managed code (.NET) version of the Neuralynx video tracker record (VideoRec).
UInt16 | swstx | This value should always be decimal 800.
UInt16 | swid | ID for the originating system of this record.
UInt16 | swdata_size | This value should always be decimal 800.
UInt64 | qwTimeStamp | Cheetah timestamp for this record.
UInt32[] | dwPoints | Pints with the color bit field values for this record. This is a 400 element array.
Int16 | sncrc | Record CRC check from Cheetah. Not used in consumer applications.
Int32 | dnextracted_x | Extracted X location of the target being tracked.
Int32 | dnextracted_y | Extracted Y location of the target being tracked.
Int32 | dnextracted_angle | Reserved
Int32[] | dntargets | Colored targets. This is a 50 element array.

delegate void MNC_CSCCallback (Object* myClassPtr, MCRRec records, int numRecords, String* objectName)
Callback delegate function for continuously sampled records. This function will be called as each continuously sampled record is received from Cheetah.
Arguments
Object | myClassPtr | Pointer to an object that is passed to the callback function.
MCRRec | records | The record received by the callback function.
int | numRecords | Reserved
String | objectName | The user defined name of the object that generated this record.

delegate void MNC_EVCallback (Object* myClassPtr, MEventRec records, int numRecords, String* objectName)
Callback delegate function for event records. This function will be called as each event record is received from Cheetah.
Arguments
Object* | myClassPtr | Pointer to an object that is passed to the callback function.
MEventRec | records | The record received by the callback function.
int | numRecords | Reserved
String | objectName | The user defined name of the object that generated this record.

delegate void MNC_SECallback (Object* myClassPtr, MSERec records, int numRecords, String* objectName)
Callback delegate function for single electrode records. This function will be called as each single electrode record is received from Cheetah.
Arguments
Object | myClassPtr | Pointer to an object that is passed to the callback function.
MSERec | records | The record received by the callback function.
int | numRecords | Reserved
String | objectName | The user defined name of the object that generated this record.

delegate void MNC_STCallback (Object* myClassPtr, MSTRec records, int numRecords, String* objectName)
Callback delegate function for stereotrode records. This function will be called as each stereotrode record is received from Cheetah.
Arguments
Object | myClassPtr | Pointer to an object that is passed to the callback function.
MSTRec | records | The record received by the callback function.
int | numRecords | Reserved
String | objectName | The user defined name of the object that generated this record.

delegate void MNC_TTCallback (Object* myClassPtr, MTTRec records, int numRecords, String* objectName)
Callback delegate function for tetrode records. This function will be called as each tetrode record is received from Cheetah.
Arguments
Object | myClassPtr | Pointer to an object that is passed to the callback function.
MTTRec | records | The record received by the callback function.
int | numRecords | Reserved
String | objectName | The user defined name of the object that generated this record.

delegate void MNC_VTCallback (Object* myClassPtr, MVideoRec records, int numRecords, String* objectName)
Callback delegate function for video tracker records. This function will be called as each video tracker record is received from Cheetah.
Arguments
Object* | myClassPtr | Pointer to an object that is passed to the callback function.
MVideoRec | records | The record received by the callback function.
int | numRecords | Reserved
String | objectName | The user defined name of the object that generated this record.


MNetComClient

 MNetCom Namespace for NetComClient v3.0
MNetComClient Class
MNetComClient Members
MNC_SECallback | mSECallback | Reserved, should not be used.
MNC_STCallback | mSTCallback | Reserved, should not be used.
MNC_TTCallback | mTTCallback | Reserved, should not be used.
MNC_CSCallback | mCSCallback | Reserved, should not be used.
MNC_EVCallback | mEVCallback | Reserved, should not be used.
MNC_VTCallback | mVTCallback | Reserved, should not be used.
Object | mSECallbackObject | Reserved, should not be used.
Object | mSTCallbackObject | Reserved, should not be used.
Object | mTTCallbackObject | Reserved, should not be used.
Object | mCSCallbackObject | Reserved, should not be used.
Object | mEVCallbackObject | Reserved, should not be used.
Object | mVTCallbackObject | Reserved, should not be used.

MNetComClient ()
Constructor for the MNetComClient class. Creates a new instance of this class, and initializes variables. No actions are performed after this class is created. It is recommended that each application only have a single instance of a MNetComClient.

~MNetComClient ()
Destructor for the MNetComClient class. Deletes the instance of this class. This should not be used in .NET applications.

bool AreWeConnected()
Gets the current connection state of the client.
Returns
bool True if the client is currently connected to a NetCom server. False if the client is not connected to a NetCom server.

bool CloseStream(String objectName)
Closes a record stream between this client and a NetCom server. Closing a stream will cause Cheetah to cease sending records for the specified object. The callback function will continue to be called until all records for this object, received before calling CloseStream, have been processed.
Arguments
String objectName The name of the object whose stream should be closed. This name is specified in the Cheetah setup files. A listing of defined object names can be obtained from the GetCheetahObjectsAndTypes function.
Returns
bool Returns True if the the specified object name and type were found in Cheetah's object list, and a stream was successfully closed. Returns false on any of the following conditions:
  1. The object name specified was not found in Cheetah's object list.
  2. A stream for this object name and type has not yet been opened.
  3. A network or other error prevented the stream from opening.
If this function is called while not connected to a NetCom server, it will return False. If OpenStream is called successfully multiple times using the same arguments, it must be closed the same number of times to halt record callbacks. Calling DisconnectFromServer automatically closes all opened streams.

bool ConnectToServer(String serverName, bool attemptRouterConnection = True)
Connects this client to a NetCom server application.
Arguments
String | serverName | Either the network name (i.e. "CheetahPC") or a string representing the IP address (i.e. "192.168.1.100" ) of the PC running a NetCom server.
bool | attemptRouterConnection | An optional argument that tells the NetComClient to attempt to connect to the Router application prior to attempting a direct connection to Cheetah. Cheetah only supports a single NetComClient connection, so using the Router is advisable if multiple applications need data from Cheetah. This argument defaults to True if not specified. For most applications this value should always be True.
Returns
bool Returns True if the connection to serverName was successful. Returns false on a failed connection attempt. If this function is called while currently connected to a NetCom server, it will return False and not close the current connection.

bool DisconnectFromServer()
Disconnects this client to a NetCom server application.
Returns
bool Returns True if the disconnection from the currently connected server was successful. Returns false on a failed disconnection attempt. On a failed disconnect, the state of the NetCom client is undetermined. It is advisable that a new MNetComClient object be created. If this function is called while not connected to a NetCom server, it will return False.

bool GetDASObjectsAndTypes(ArrayList& cheetahObjectList, ArrayList& cheetahTypesList)
Retrieves all objects defined in Cheetah's object list, along with their corresponding types.
Arguments
ArrayList cheetahObjectList This ArrayList will be filled with String objects for each object in Cheetah's object list. This argument will be modified during this function's execution, and its contents should not be considered valid if this function call fails.
ArrayList cheetahTypesList This ArrayList will be filled with String objects for each object's type in Cheetah's object list. The type specified will have a one-to-one mapping with the cheetahObjectList (i.e. cheetahObjectList.Item(1) will be of type cheetahTypesList.Item(1) ). This argument will be modified during this function's execution, and its contents should not be considered valid if this function call fails.

The following is a listing of the type strings corresponding to each data type:

NetCom Type String | MNetCom Data Type
SEScAcqEnt | MSERec
STScAcqEnt | MSTRec
TTScAcqEnt | MTTRec
CscAcqEnt | MCRRec
EventAcqEnt | MEventRec
VTAcqEnt | MVideoRec
Returns
bool Returns True if this client successfully received all of Cheetah's object list. Returns false on a failed attempt to receive Cheetah's object list. If this function is called while not connected to a NetCom server, it will return False and the object and types lists will need to be refreshed after a connection is established.

String GetClientVersionString()
Retrieves the version of the client being used.
Returns
String The version of the NetCom client being used.

String GetServerApplicationName()
Retrieves the name of the application that this client is connected to.
Returns
String The name of application that this client is connected to. If the client is not connected, the return value is "Not Connected"

String GetServerIPAddress()
Retrieves the IP address of the PC running the NetCom server that this client is connected to.
Returns
String The IP of the PC running the NetCom server that this client is connected to. If the client is not connected, the return value is "0.0.0.0"

String GetServerPCName()
Retrieves the name of the PC running the NetCom server that this client is connected to.
Returns
String The name of the PC running the NetCom server that this client is connected to. If the client is not connected, the return value is "Not Connected"

bool OpenStream(String objectName)
Opens a record stream between this client and a NetCom server. Opening a stream will cause the defined callback function corresponding to the object type of objectName to be called after receiving a record for the specified object name.
Arguments
String objectName The name of the object to stream data from. This name is specified in the Cheetah setup files. A listing of defined object names can be obtained from the GetCheetahObjectsAndTypes function.
Returns
bool Returns True if the the specified object name and type were found in Cheetah's object list, and a stream was successfully opened. Returns false on any of the following conditions:
  1. The object name specified was not found in Cheetah's object list.
  2. A network or other error prevented the stream from opening.
If this function is called while not connected to a NetCom server, it will return False and the stream will need to be reopened after a connection is established. If this function is called successfully multiple times using the same arguments, it must be closed the same number of times to halt record callbacks. Calling DisconnectFromServer automatically closes all opened streams.

bool SendCommand(String command, String& reply)
Sends a generic command to Cheetah for processing. This is a synchronous command that will wait until the NetCom server sends a response before returning. For a complete list of Cheetah commands, see the Commands section of the Cheetah Reference Guide (available under the Help menu in Cheetah).
Arguments
String | command | The formatted command string that Cheetah is to process. Command strings are identical to configuration file commands.
String | reply | The reply received from the NetCom server will be stored in this argument. This argument will be modified during this function's execution, and its contents should not be considered valid if this function call fails.
Returns
bool Returns True if this successfully sends a command and receives a response to/from a NetCom server. Returns false on a failed attempt to send a command, or receive a response from a NetCom server. If this function is called while not connected to a NetCom server, it will return False and the command will be discarded.

bool SetApplicationName(String myApplicationName)
Sets a name to identify your application to the NetCom server. The server application will use this name to show information about the connection to your application.
Arguments
String myApplicationName This name is used to identify all traffic on this connection NetCom server logs. This name is also displayed in the Router's connection list or in Cheetah's NetCom connection display.
Returns
bool Returns True if the application name was set in the server's connection list. Returns false on a failed attempt to update the server's connection list. If this function is called while not connected to a NetCom server, it will return False and the application name will need to be reset after a connection is established.

void SetCallbackFunctionCSC(MNC_CSCCallback myFunctionPtr, Object myClassPtr)
Sets the callback function for continuously sampled records.
Arguments
MNC_CSCCallback | myFunctionPtr | A delegate to the function that will be called when any MCRRec record is received by this client. This function will be called as long as any continuously sampled object has an open stream. This function ceases to be called when all continuously sampled streams have been closed.
Object | myClassPtr | The object that will be referenced within the call back function.

void SetCallbackFunctionEV(MNC_EVCallback myFunctionPtr, Object myClassPtr)
Sets the callback function for event records.
Arguments
MNC_EVCallback | myFunctionPtr | A delegate to the function that will be called when any MEventRec record is received by this client. This function will be called as long as any event object has an open stream. This function ceases to be called when all event streams have been closed.
Object | myClassPtr | The object that will be referenced within the call back function.

void SetCallbackFunctionSE(MNC_SECallback myFunctionPtr, Object myClassPtr)
Sets the callback function for single electrode records.
Arguments
MNC_SECallback | myFunctionPtr | A delegate to the function that will be called when any MSERec record is received by this client. This function will be called as long as any single electrode object has an open stream. This function ceases to be called when all single electrode streams have been closed.
Object | myClassPtr | The object that will be referenced within the call back function.

void SetCallbackFunctionST(MNC_STCallback myFunctionPtr, Object myClassPtr)
Sets the callback function for stereotrode records.
Arguments
MNC_STCallback | myFunctionPtr | A delegate to the function that will be called when any MSTRec record is received by this client. This function will be called as long as any stereotrode object has an open stream. This function ceases to be called when all stereotrode streams have been closed.
Object | myClassPtr | The object that will be referenced within the call back function.

void SetCallbackFunctionTT(MNC_TTCallback myFunctionPtr, Object myClassPtr)
Sets the callback function for tetrode records.
Arguments
MNC_TTCallback | myFunctionPtr | A delegate to the function that will be called when any MTTRec record is received by this client. This function will be called as long as any tetrode object has an open stream. This function ceases to be called when all tetrode streams have been closed.
Object | myClassPtr | The object that will be referenced within the call back function.

void SetCallbackFunctionVT(MNC_VTCallback myFunctionPtr, Object myClassPtr)
Sets the callback function for video tracker records.
Arguments
MNC_VTCallback | myFunctionPtr | A delegate to the function that will be called when any MVideoRec record is received by this client. This function will be called as long as any video tracker object has an open stream. This function ceases to be called when all video tracker streams have been closed.
Object | myClassPtr | The object that will be referenced within the call back function.

bool SetLogFileName(String fileName)
Sets the logfile name for this client. If this command is not called, no logfile will be created.
Arguments
String fileName The completely qualified file name for the logfile. All NetCom communications will be logged to fileName.
Returns
bool Returns True if this successfully sets the logfile name and opens the logfile. Returns false if the logfile could not be opened. This function can be called while not connected to a NetCom server.

static MNetComClient GetMNC()
This function should not be called from .NET applications, it returns an unmanaged instance of a MNetComClient object. .NET applications should use the instance of MNetComClient declared in the application.
Returns
MNetComClient The unmanaged instance of a MNetComClient object.