VSCP Helper Libraries

Trace: helper_lib_api_communication


|

Meta

VSCP Helper library API - Communication

This part describes the main functionality and communication methods available in the library.

vscphlp_setResponseTimeout

int vscphlp_setResponseTimeout( long handle, unsigned long timeout )

This is the timeout in seconds used when checking for replies after commands has been sent to the server. It can be changed anytime during a communication session. Default value is 3000 milliseconds.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

timeout

Timeout given in milliseconds. Can be set also before the session is open.

Return value

VSCP_ERROR_SUCCESS is returned on success. VSCP_ERROR_INVALID_HANDLE is returned if an invalid handle is given.

vscphlp_setAfterCommandSleep

int vscphlp_setAfterCommandSleep( long handle, unsigned short millisecondSleep )

This is the sleep time in milliseconds used to wait for the server to reply to a command. If there is not valid response received the thread will sleep for the amount of time set here + 200 milliseconds and then check the queue again for a valid response then sleep again and so on until the time set for the response timeout has elapsed, a valid response or an error response has been received. Default value is 0 milliseconds.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

secondsTimeout

Timeout given in seconds. Can be set also before the session is open.

Return value

VSCP_ERROR_SUCCESS is returned on success. VSCP_ERROR_INVALID_HANDLE is returned if an invalid handle is given.

vscphlp_isConnected

int vscphlp_isConnected( long handle )

Check if the session is active or not.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

Return value

VSCP_ERROR_SUCCESS if the session is active and VSCP_ERROR_ERROR if it is inactive. VSCP_ERROR_INVALID_HANDLE is returned if an invalid handle is given.

Example
    if ( VSCP_ERROR_SUCCESS == vscphlp_isConnected( handle1 ) ) {
        // Do your stuff here 
    }

vscphlp_doCommand

int vscphlp_doCommand( long handle, const char * cmd )

Send a command over the communication link. The command should have “\r\n” to it's end. The response from the server will be checked for +OK.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

cmd

This is the command that should be sent to the server. It should be terminated with “\r\n”.

Return value

VSCP_ERROR_SUCCESS if the VSCP daemon respond with +OK after it has received the command and VSCP_ERROR_ERROR if not (-OK) or no response before the timeout expires. VSCP_ERROR_CONNECTION is returned if the communication channel is not open. VSCP_ERROR_INVALID_HANDLE is returned if an invalid handle is given.

    if ( VSCP_ERROR_SUCCESS == vscphlp_doCommand( handle1, "NOOP\r\n" ) ) {
        printf("Command sent successfully!\n");   
    ]

vscphlp_checkReply

int vscphlp_checkReply( long handle, int bClear )

Check reply data.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

bClear

If TRUE (not zero) the input buffer will be cleared before starting to wait for a +OK/-OK in the incoming data.

Return value

VSCP_ERROR_SUCCESS if the VSCP daemon respond with “+OK” after it has received the command and VSCP_ERROR_ERROR if not or no response before the timeout expires.

Example
    if ( VSCP_ERROR_SUCCESS == vscphlp_checkReply( handle1, TRUE ) ) {
        printf("+OK was received from VSCP daemon.\n");   
    }

vscphlp_clearLocalInputQueue

int vscphlp_clearLocalInputQueue( long handle )

Clear the local communication input queue. This is the same things that is done when setting bClear for vscphlp_checkReply

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

Return value

VSCP_ERROR_SUCCESS if the VSCP daemon cleared the queue and VSCP_ERROR_ERROR if not or no response is received before the timeout expires. VSCP_ERROR_INVALID_HANDLE is returned if an invalid handle is given.

Example
    if ( VSCP_ERROR_SUCCESS == vscphlp_clearLocalInputQueue( handle1 ) ) {
        printf("Our local input queue cleared.\n");   
    }

vscphlp_open

long vscphlp_open( long handle,
                        const char *Host, 
                        const char *pUsername, 
                        const char *pPassword )

Opens a session to the TCP/IP interface of the VSCP daemon.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pHost

String pointing to hostname of host to connect to. This can be a name that needs to be resolved e.g. “”www.grodansparadis.com” or a dotted IP-address e.g. “192.168.1.1”. The general format for the hostname is

[PROTO://]HOST:PORT[:CERT][:CA_CERT] 

where PROTO could be tcp:// or ssl://. If HOST is not an IP address, the system will resolve it - beware that standard blocking resolver will be used. It is a good practice to pre-resolve hosts beforehand and use only IP addresses to avoid blocking an IO thread.

For SSL connections, specify CERT if server is requiring client auth. Specify CA_CERT to authenticate server certificate. All certificates must be in PEM format.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pUserName

Username to use as credentials for login to the remote VSCP daemon.

pPassword

Password to use as credentials for login to the remote VSCP daemon.

Return value

VSCP_ERROR_SUCCESS is returned on success. VSCP_ERROR_INVALID_HANDLE will be returned if the interface is not initialized, VSCP_ERROR_MEMORY will there is problem to allocate needed structures, VSCP_ERROR_TIMEOUT is returned if connection or responses is not received in time, VSCP_ERROR_USER for problems with username, VSCP_ERROR_PASSWORD for problems with password and for all other error VSCP_ERROR_ERROR will be returned.

Example
    // Open Channel 1
    rv=vscphlp_open( handle1, 
                        "127.0.0.1:9598",
                        "admin",
                        "secret" ); 
    if ( VSCP_ERROR_SUCCESS == rv ) {
        printf("Command success: vscphlp_open on channel 1\n");
    }
    else {
        printf("\aCommand error: vscphlp_open on channel 1  Error code=%d\n", rv);
    }

vscphlp_openInterface

int vscphlp_openInterface( long handle,
                                   const char *pInterface, 
                                   unsigned long flags )
handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pInterface

Pointer to a string with the name of interface to open. The format of this string is

host;username;password
flags

Flags to use for the interface. Currently not used.

Return value

Possible retun values are the same as for vscphlp_doCmdOpen

Example
    // Open Channel 1
    rv=vscphlp_open( handle1, "192.168.1.9:9598;admin;secret" ); 
    if ( VSCP_ERROR_SUCCESS == rv ) {
        printf("Command success: vscphlp_open on channel 1\n");
    }
    else {
        printf("\aCommand error: vscphlp_open on channel 1  Error code=%d\n", rv);
    }

vscphlp_close

int vscphlp_close( long handle )

Close the interface.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

return

VSCP_ERROR_SUCCESS is returned on sucess. VSCP_ERROR_INVALID_HANDLE will be returned if the interface is not initialized.

Example
    if ( VSCP_ERROR_SUCCESS == vscphlp_close( handle1 ) ) {
        // prinf("Closed successfully.\n");
    }

vscphlp_noop

int vscphlp_noop( long handle )

This is a command that can be used for test purposes. It does not do anything else then to send a command over the interfaces and check the result.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    // NOOP on handle1
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_noop( handle1 ) ) ) {
        printf( "Command success: vscphlp_noop on channel 1\n" );
    }
    else {
        printf("\aCommand error: vscphlp_noop on channel 1  Error code=%d\n", rv);
    }

vscphlp_clearDaemonEventQueue

int vscphlp_clearDaemonEventQueue ( long handle )

Clear the receiving side (to us) event queue on the VSCP daemon.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

Return value

VSCP_ERROR_SUCCESS if the VSCP daemon cleared the queue and VSCP_ERROR_ERROR. if not or no response is received before the timeout expires. VSCP_ERROR_CONNECTION is returned if the communication channel is not open. VSCP_ERROR_INVALID_HANDLE is returned if an invalid handle is given.

Example
    // Clear event queue on VSCP daemon on handle1
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_clearDaemonEventQueue( handle1 ) ) ) {
        printf( "Command success: vscphlp_clearDaemonEventQueueon channel 1\n" );
    }
    else {
        printf("\aCommand error: vscphlp_clearDaemonEventQueueon channel 1  Error code=%d\n", rv);
    }

vscphlp_sendEvent

int vscphlp_sendEvent( long handle, const vscpEvent *pEvent )

Send a VSCP event. If the event is successfully sent or not it's the calling programs responsibility to deallocate the event. It's easy to forget to free the data part of an event created on the stack.

Note that there is no need to calculate a crc for the data it is only used as placeholder for more insecure transfer mechanisms. Also head, obid and timestamp can be set to zero in most cases.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pEvent

The level I or level II event to send. The structure vscpEvent is defined in vscp.h as

  typedef struct  {	
  uint16_t crc;           // crc checksum - currently only used for UDP and RF
  uint8_t  *pdata;        // Pointer to data. Max 487 (512- 25) bytes
  // Following two are for daemon internal use
  uint32_t obid;          // Used by driver for channel info etc.
  uint32_t timestamp;     // Relative time stamp for package in microseconds
  // CRC should be calculated from
  // here to end + datablock
  uint16_t head;          // Bit 16   GUID is IP v.6 address.
                          // bit 765  priority, Priority 0-7 where 0 is highest.
                          // bit 4 = hard coded, true for a hard coded device.
                          // bit 3 = Don't calculate CRC, false for CRC usage.
                          // bit 2 = Reserved.
                          // bit 1 = Reserved.
                          // bit 0 = Reserved.
  uint16_t vscp_class;    // VSCP class
  uint16_t vscp_type;     // VSCP type
  uint8_t  GUID[ 16 ];    // Node globally unique id LSB(0) -> MSB(15
  uint16_t sizeData;      // Number of valid data bytes		
} vscpEvent;
Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    // Send event on channel 1
    vscpEvent e;
    e.vscp_class = 10;  // CLASS1.MEASUREMENT
    e.vscp_type = 6;    // Temperature
    e.head = 0;
    e.sizeData = 3;
    e.pdata = new unsigned char[3];
    e.pdata[0] = 138;  // Six degrees Celsius from sensor 2
    e.pdata[1] = 0;
    e.pdata[2] = 6;
    memset(e.GUID, 0, sizeof(e.GUID) ); // Setting GUID to all zero tell interface to use it's own GUID
 
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_sendEvent( handle1, &e ) ) ) {
        printf( "Command success: vscphlp_sendEvent on channel 1\n" );
    }
    else {
        printf("\aCommand error: vscphlp_sendEvent on channel 1  Error code=%d\n", rv);
    }
 
    // The event must be deallocated
    //delete pEvent->pdata;
    //delete pEvent;
    vscphlp_deleteVSCPevent( pEvent );  // This helper is the same as the above two commented lines
 

vscphlp_sendEventEx

int vscphlp_sendEventEx( long handle, const vscpEventEx *pEvent )

Send a VSCP event. If the event is not successfully sent it's the calling programs responsibility to deallocate the event.

Note that there is no need to calculate a crc for the data it is only used as placeholder for more insecure transfer mechanisms. Also head, obid and timestamp can be set to zero in most cases.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pEvent

The level I or level II event to send. The structure vscpEventEx is defined in vscp.h as

  typedef struct {	
  uint16_t crc;                   // crc checksum
 
  // Following two are for daemon internal use
  uint32_t obid;                  // Used by driver for channel info etc.
  uint32_t timestamp;             // Relative time stamp for package in microseconds.
  // CRC should be calculated from
  // here to end + datablock
  uint8_t head;                   // bit 7,6,5 prioriy => Priority 0-7 where 0 is highest.
                                  // bit 4 = hardcoded, true for a hardcoded device.
                                  // bit 3 = Dont calculate CRC, Set to zero to use CRC.
                                  // bit 2 = Set means this is CAN message.
                                  // bit 1 = If bit 2 is set; Extended CAN message if set
                                  // bit 0 = If bit 2 is set: Remote frame if set
  uint16_t vscp_class;            // VSCP class
  uint16_t vscp_type;             // VSCP type
  uint8_t  GUID[ 16 ];            // Node globally unique id MSB(15) -> LSB(0)
  uint16_t sizeData;              // Number of valid data bytes		
 
  uint8_t  data[VSCP_MAX_DATA];   // Pointer to data. Max 487 (512- 25) bytes
 
} vscpEventEx;
Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    vscpEventEx ex;
    ex.vscp_class = 10; // CLASS1.MEASUREMENT
    ex.vscp_type = 6;   // Temperature
    ex.head = 0;
    ex.sizeData = 3;
    ex.data[0] = 138;   // 6 degrees Celsius from sensor 2
    ex.data[1] = 0;
    ex.data[2] = 6;
    memset(ex.GUID, 0, sizeof(e.GUID) ); // Setting GUID to all zero tell interface to use it's own GUID
 
    // Send event again
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_sendEventEx( handle1, &ex ) ) ) {
        printf( "Command success: vscphlp_sendEventEx on channel 1\n" );
    }
    else {
        printf("\aCommand error: vscphlp_sendEventEx on channel 1  Error code=%d\n", rv);
    }

vscphlp_receiveEvent

int vscphlp_receiveEvent( long handle, vscpEvent *pEvent )

Receive one VSCP event from the remote VSCP daemon.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pEvent

Pointer to vscpEvent structure that will receive the event if the call is successful. The structure vscpEvent is define in vscp.h and is defined as

  typedef struct  {	
  uint16_t crc;           // crc checksum - currently only used for UDP and RF
  uint8_t  *pdata;        // Pointer to data. Max 487 (512- 25) bytes
  // Following two are for daemon internal use
  uint32_t obid;          // Used by driver for channel info etc.
  uint32_t timestamp;     // Relative time stamp for package in microseconds
  // CRC should be calculated from
  // here to end + datablock
  uint16_t head;          // Bit 16   GUID is IP v.6 address.
                          // bit 765  priority, Priority 0-7 where 0 is highest.
                          // bit 4 = hard coded, true for a hard coded device.
                          // bit 3 = Don't calculate CRC, false for CRC usage.
                          // bit 2 = Reserved.
                          // bit 1 = Reserved.
                          // bit 0 = Reserved.
  uint16_t vscp_class;    // VSCP class
  uint16_t vscp_type;     // VSCP type
  uint8_t  GUID[ 16 ];    // Node globally unique id LSB(0) -> MSB(15
  uint16_t sizeData;      // Number of valid data bytes		
} vscpEvent;
Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    // Read event
    vscpEvent *pEvent = new vscpEvent;
    pEvent->pdata = NULL;   // A must for a successful delete
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_receiveEvent( handle2, pEvent ) ) ) {
        printf( "Command success: vscphlp_receiveEvent on handle2\n" );
        printf( "VSCP class=%d VSCP type=%d sizeData=%d\n", 
                    pEvent->vscp_class,
                    pEvent->vscp_type,
                    pEvent->sizeData );
        printf("Data = ");
        for ( int i=0; i<pEvent->sizeData; i++ ) {
            printf("%d ", pEvent->pdata[i] );
        }
        printf("\n");
    }
    else {
        printf("\aCommand error: vscphlp_receiveEvent on channel 2  Error code=%d\n", rv);
    }
 
    // Do something with the received event
 
    //delete pEvent->pdata;
    //delete pEvent;
    vscphlp_deleteVSCPevent( pEvent );  // This helper is the same as the above two commented lines

vscphlp_receiveEventEx

int vscphlp_receiveEventEx( long handle, vscpEventEx *pEvent )

Receive a VSCP event. The difference to doCmdReceiveEvent is that the vscpEventEx structure have the data in the structure and vscpEvent that have a pointer to the data in the structure.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pEvent

Pointer to VSCP data structure that will receive the event.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    // Read event  -  Use vscpEventEx
    vscpEventEx ex2;
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_receiveEventEx( handle2, &ex2 ) ) ) {
        printf( "Command success: vscphlp_receiveEventEx on handle2\n" );
        printf( "VSCP class=%d VSCP type=%d sizeData=%d\n", 
                    ex2.vscp_class,
                    ex2.vscp_type,
                    ex2.sizeData );
        printf("Data = ");
        for ( int i=0; i<ex2.sizeData; i++ ) {
            printf("%d ", ex2.data[i] );
        }
        printf("\n");
    }
    else {
        printf("\aCommand error: vscphlp_receiveEventEx on channel 2  Error code=%d\n", rv);
    }

vscphlp_isDataAvailable

int vscphlp_isDataAvailable( long handle, unsigned int pCount )

Check the number of events (if any) that are available in the remote input queue.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

count

Pointer to variable that gets the number of events waiting in the queue on a successful call.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    // Check queue for events
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_isDataAvailable( handle2, &count ) ) ) {
        printf( "Command success: vscphlp_isDataAvailable on handle2\n" );
        printf( "count = %d\n", count );
        if ( 3 == count ) printf("Which is correct.\n");
    }
    else {
        printf("\aCommand error: vscphlp_isDataAvailable on channel 2  Error code=%d\n", rv);
    }

vscphlp_enterReceiveLoop

int vscphlp_enterReceiveLoop( long handle )

Enter the receive loop. After this command only vscphlp_quitReceiveLoop and vscphlp_Close is available. The intent of the command is for threaded communication where one thread is sending events and one is receiving events and can use blocking calls to do so.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    // Enter receiveloop
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_enterReceiveLoop( handle2 ) ) ) {
        printf( "Command success: vscphlp_enterReceiveLoop on channel 2\n" );
    }
    else {
        printf("\aCommand error: vscphlp_enterReceiveLoop on channel 2  Error code=%d\n", rv);
    }

vscphlp_quitReceiveLoop

int vscphlp_quitReceiveLoop( long handle )

Quit the receive loop.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    // Quit receiveloop
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_quitReceiveLoop( handle2 ) ) ) {
        printf( "Command success: vscphlp_quitReceiveLoop on channel 2\n" );
    }
    else {
        printf("Command error: vscphlp_quitReceiveLoop on channel 2  Error code=%d\n", rv);
    }

vscphlp_blockingReceiveEvent

int vscphlp_blockingReceiveEvent( long handle, vscpEvent *Event )

Blocking receive event.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pEvent

Pointer to event that will get event data after a sucessfull call. See vscphlp_receiveEvent for a description.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    pEvent = new vscpEvent;
    pEvent->pdata = NULL;   // A must for a successful delete
    if ( VSCP_ERROR_SUCCESS == vscphlp_blockingReceiveEvent( handle2, pEvent ) ) {
        printf( "Command success: vscphlp_blockingReceiveEvent on channel 2\n" );
        printf(" Event: class=%d Type=%d sizeData=%d\n", 
                        pEvent->vscp_class,
                        pEvent->vscp_type,
                        pEvent->sizeData );
        if ( pEvent->sizeData && ( NULL != pEvent->pdata ) ) {
            printf("Data = ");
            for ( int i=0; i<ex2.sizeData; i++ ) {
                 printf("%d ", ex2.data[i] );
            }
            printf("\n");
        }
    }
    vscphlp_deleteVSCPevent( pEvent );

vscphlp_blockingReceiveEventEx

int vscphlp_blockingReceiveEventEx( long handle, vscpEventEx *Eventex )

Blocking receive event.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pEvent

Pointer to event that will get event data after a sucessfull call. See vscphlp_receiveEvent for a description.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    vscpEventEx ex;
 
    if ( VSCP_ERROR_SUCCESS == vscphlp_blockingReceiveEventEx( handle2, &ex ) ) {
        printf( "Command success: vscphlp_blockingReceiveEventEx on channel 2\n" );
        printf(" Event: class=%d Type=%d sizeData=%d\n", 
                        ex.vscp_class,
                        ex.vscp_type,
                        ex.sizeData );
        if ( ex.sizeData ) {
            printf("Data = ");
            for ( int i=0; i<ex.sizeData; i++ ) {
                 printf("%d ", ex.data[i] );
            }
            printf("\n");
        }
    }
    vscphlp_deleteVSCPevent( pEvent );

vscphlp_setFilter

int vscphlp_setFilter( long handle, const vscpEventFilter *pFilter )

Set VSCP filter/mask.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pFilter

Pointer to a VSCP filter structure that should be applied to the input stream. The VSCP filter structure is defined in vscp.h and has the following format

typedef struct  {
  uint8_t filter_priority;        // Priority 
  uint8_t mask_priority;
 
  uint16_t filter_class;          // VSCP class
  uint16_t mask_class;
 
  uint16_t filter_type;           // VSCP type
  uint16_t mask_type;
 
  uint8_t filter_GUID[ 16 ];      // Node address MSB -> LSB, LSB is node nickname id
  uint8_t mask_GUID[ 16 ];        //		when interfacing the VSCP daemon.
 
} vscpEventFilter;
Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example - Set filter
    // Set VSCP filter
    vscpEventFilter filter;
    filter.filter_class = 22;   // We are interested in events with VSCP class=22 only
    filter.mask_class = 0xffff;
    filter.mask_type = 0;               // Any type
    filter.mask_priority = 0;           // Any priority
    memset( filter.mask_GUID, 0, 16 );  // Any GUID
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_setFilter( handle2, &filter ) ) ) {
        printf( "Command success: vscphlp_setFilter on channel 2\n" );
    }
    else {
        printf("\aCommand error: vscphlp_setFilter on channel 2  Error code=%d\n", rv);
    }
Example - Clear filter
    // Clear the filter
    memset( &filter, 0, sizeof( vscpEventFilter ) );
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_setFilter( handle2, &filter ) ) ) {
        printf( "Command success: vscphlp_setFilter on channel 2\n" );
    }
    else {
        printf("\aCommand error: vscphlp_setFilter on channel 2  Error code=%d\n", rv);
    }

vscphlp_getStatistics

int vscphlp_getStatistics( long handle, canalStatistics *pStatistics )

Get VSCP statistics.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pStatistics

A pointer to a VSCP statistics structure as defined in vscp.h. The format is

typedef struct structVSCPStatistics {
  unsigned long cntReceiveFrames;             // # of receive frames
  unsigned long cntTransmitFrames;            // # of transmitted frames
  unsigned long cntReceiveData;               // # of received data bytes
  unsigned long cntTransmitData;              // # of transmitted data bytes	
  unsigned long cntOverruns;                  // # of overruns
  unsigned long x;                            // Currently undefined value 
  unsigned long y;                            // Currently undefined value 
  unsigned long z;                            // Currently undefined value 
} VSCPStatistics;
Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    // Get statistics
    VSCPStatistics stat;
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_getStatistics( handle2, &stat ) ) ) {
        printf( "Command success: vscphlp_getStatistics on channel 2\n" );
    }
    else {
        printf("\aCommand error: vscphlp_getStatistics on channel 2  Error code=%d\n", rv);
    }

vscphlp_getStatus

const char * vscphlp_getStatus( long handle, char *pVendor, int size )

Fetch the status structure from the VSCP dameon.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

stat

Pointer to VSCPStatistics structure that will be filled with data after a successful call.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
VSCPStatus status;
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_getStatus( handle2, &status ) ) ) {
        printf( "Command success: vscphlp_getStatus on channel 2\n" );
    }
    else {
        printf("\aCommand error: vscphlp_getStatus on channel 2  Error code=%d\n", rv);
    }

vscphlp_getVersion

unsigned long vscphlp_getVersion( long handle, unsigned long *pVersion, int size )

Get the version of the remote VSCP daemon as a string on the form

major-ver.minor-ver.subminor-ver.
handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

handle

Buffer that will hold version after a successful call.

size

Size of buffer that will hold version string after a successful call.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    // Get server version
    unsigned char v1,v2,v3;
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_getVersion( handle2, &v1, &v2, &v3 ) ) ) {
        printf( "Command success: vscphlp_getVersion on channel 2\n" );
        printf( "Version for VSCP daemon on channel 2 is %d.%d.%d\n", v1,v2,v3 );
    }
    else {
        printf("\aCommand error: vscphlp_getVersion on channel 2  Error code=%d\n", rv);
    }

vscphlp_getDLLVersion

const char * vscphlp_getDLLVersion( long handle, unsigned long *pdllversion )

Fetch the vendor string from the driver.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pdllversion

Pointer to an unsigned long that will get driver version.

size

Size of supplied buffer.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    // Get DLL version
    unsigned long dllversion;
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_getDLLVersion( handle2, &dllversion ) ) ) {
        printf( "Command success: vscphlp_getDLLVersion on channel 2\n" );
        printf( "DL(L) version is %08X\n", dllversion );
    }
    else {
        printf("\aCommand error: vscphlp_getDLLVersion on channel 2  Error code=%d\n", rv);
    }

vscphlp_getVendorString

const char * vscphlp_getVendorString( long handle, char *pVendor, int size )

Fetch the vendor string from the driver.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pVendor

Pointer to a string that will receive vendor information.

size

Size of supplied buffer.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    // Get vendor string
    char buf[120];
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_getVendorString( handle2, buf, sizeof(buf) ) ) ) {
        printf( "Command success: vscphlp_getVendorString on channel 2\n" );
        printf( "Vendorstring = \"%s\"\n", buf );
    }
    else {
        printf("\aCommand error: vscphlp_getVendorString on channel 2  Error code=%d\n", rv);
    }

vscphlp_getDriverInfo

const char * vscphlp_getDriverInfo( long handle, char *pInfo, int size )

Get driver information.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

pInfo

A pointer to string with XML formatted information about the driver in use. This information (if available) can be used to help a user to configure the driver among other things.

size

Size of supplied buffer.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
    // Get driver info
    if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_getDriverInfo( handle2, buf, sizeof(buf) ) ) ) {
        printf( "Command success: vscphlp_getDriverInfo on channel 2\n" );
        printf( "Driver info = \"%s\"\n", buf );
    }
    else {
        printf("\aCommand error: vscphlp_getDriverInfo on channel 2  Error code=%d\n", rv);
    }

vscphlp_doCmdShutDown

int vscphlp_doCmdShutDown( long handle )

Shut down the daemon. Needless to say this is a privileged command on the server side.

handle

Handle for the communication channel obtained from a call to vscphlp_newSession.

Return value

Return VSCP_ERROR_SUCCESS on success, VSCP_ERROR_ERROR on failure. If the connection is closed VSCP_ERROR_CONNECTION is returned. VSCP_ERROR_PARAMETER is returned if called while in a receive loop.

Example
// Shut down the server
if ( VSCP_ERROR_SUCCESS == (rv = vscphlp_doCmdShutDown( handle2 ) ) ) {
    printf( "Command success: vscphlp_doCmdShutDownon channel 2\n" );
}
else {
    printf("\aCommand error: vscphlp_doCmdShutDownon channel 2  Error code=%d\n", rv);
}



Copyright © 2000-2017 Åke Hedman, Paradise of the Frog / Grodans Paradis AB