acq2xx.h

Go to the documentation of this file.

/* ------------------------------------------------------------------------- */
/* file acq2xx.h                                                             */
/* ------------------------------------------------------------------------- */
/*   Copyright (C) 2006 Peter Milne, D-TACQ Solutions Ltd
 *                      <Peter dot Milne at D hyphen TACQ dot com>

    This program is free software; you can redistribute it and/or modify
    it under the terms of Version 2 of the GNU General Public License
    as published by the Free Software Foundation;

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.                */
/* ------------------------------------------------------------------------- */

/** @file acq2xx.h ACQ2xx web service definition. */

/** @mainpage ACQ2XX Webservice Interface.
 *  @version $Revision: 1.22 $
 *  @author peter.milne@d-tacq.com
 
 *  - Aim:
 *   - Provide a SOAP format webservice as a universal remote 
 *       control interface.
 *  - Goals
 *   - cross platform C++ RPC, with both low level and functional control, 
 *        using supplied client-side library (tested Linux and Windows).
 *   - cross platform Webservice, based on WSDL service definition, clients 
 *        can be generated using WS tools
 *  - Service provided on three levels
 *   -  Low Level Interface
 *    - acq2sh - remote shell interface
 *    - acqcmd - emulates traditional acqcmd interface
 *    - getVersion - compare client, server interface versions
 *   - Transactional Interface
 *    - acq2script - allows multiple transactions Objects to be processed in 
 *      a single request with full status checking. 
 *      Stops on first error by default.
 *   - Functional Interface
 *    - high level system control transactions Classes available to 
 *      complete most common setups, providing a client-side API.
 *    - dedicated methods for the most commonly repeated functional controls.
 *
 * - Implementation
 *  - server side implementation is based on gsoap:
 *     http://www.cs.fsu.edu/~engelen/soap.html
 *  - interface is defined in this file @ref acq2xx.h
 *  - RPC functions, and high Transaction objects.
 *  - a client side gsoap implementation is provided as
 *   - standalone low level client app
 *   - function application to demonstrate use of the API 
 *  - Webservices based on generated WSDL - possibility to autogenerate
 *    applications in common webservice frameworks, eg .NET, Java, PERL.
 * - Operation
 *  - webservice operates as a dedicated multi-threaded service running on:
 *   - http://ACQ2XX_CARD:6666
 *    - service is enabled by /ffs/dropbear/etc/auxd/auxd.3.conf
 *  - wsdl available at
 *   - http://ACQ2XX_CARD/acq2xx.wsdl
 *    - this wsdl is normalized to declare the service location to be at the 
 *      ip address of eth0. It doesn't use hostname as not all systems use DNS
 *      for the "acq2xx" clients
 *
 * - Client Side Libraries
 *   - Linux:
 *    - libstdsoap2.so
 *    - object modules comprising api
 *   - Windows:
 *    - DLL to follow, use object modules at present.
 * - Client Side applications:
 *  - acq2xx_client - see acq2xx_client.cpp
 *
 * - Performance.
 *    SOAP is a human readable, XML protocol. So you would expect it to be slow.
 *    However, D-TACQ testing shows that this interface is capable of a respectable 25 transactions per second. 
 *    This performance is adequate for the normal shot-based use case for ACQ196/ACQ216.
 *    The advantage of the WS/SOAP approach is portability and extensibility, coupled with an easy to
 *    user object oriented program model on the client.
 * - Extensions
 *  - VB.NET client application - planned.
 *  - Windows DLL - planned.
 *  - access from Java JAX-WS (less urgent, dt100rc works).
 *  - Use SSL for secure access - possible.
 */

//gsoap acq2xx service name: acq2xx
//gsoap acq2xx service encoding: literal
//gsoap acq2xx service namespace: http://www.d-tacq.com
//gsoap acq2xx service location: http://ACQ2XX_IP_ADDRESS:6666
//gsoap acq2xx schema elementForm: qualified
//gsoap acq2xx schema attributeForm: qualified


/* acq2xx local shell script takes default wsdl and normalizes it to reference
 * local ip address 


#define ACQ2XX_H_VERSION "$Revision: 1.22 $"

/** Low Level functions */

int acq2xx__getVersion(char *client_version, char*& server_version);
/**< version check - allows client, server to compare ACQ2XX_H_VERSION */

int acq2xx__acqcmd(char* command, char*& response);
/**< remote "acqcmd" */
int acq2xx__acq2sh(char* command, char*& response);
/**< remote shell command. */




/** Class definitions for Transactional/Functional API */

/** generic top level Object.*/
class acq2xx__Object {
public:
        char *name;
        acq2xx__Object();
        acq2xx__Object(const char* name);
        virtual ~acq2xx__Object();
        virtual void print();
        const char* getName();
};


struct soap;    /** opaque context */

/** generic command/response remote transaction with status. */
class acq2xx__Transaction : public acq2xx__Object {
public:

        int abort_on_error;
        int status;
        int complete;

        acq2xx__Transaction();
        acq2xx__Transaction(const char *name);
        virtual ~acq2xx__Transaction();
        virtual void print();
        void exec(struct soap *soap);
        
        virtual const char* getCommand();
        virtual const char* getResult();
protected:
        virtual int run(struct soap *soap);
};

/** container. */
class acq2xx__TransactionList: public acq2xx__Transaction
{ 
public:
        acq2xx__Transaction **__ptr; // array of pointers to objects
        int __size;
        acq2xx__TransactionList();
        acq2xx__TransactionList(int size);
        virtual ~acq2xx__TransactionList();
        virtual acq2xx__Transaction*& operator[](int i);
        virtual void print();

        int getSize();
protected:
        virtual int run(struct soap *soap);
};

int acq2xx__acq2script(
        acq2xx__Transaction *in, 
        struct acq2xx__acq2scriptResponse { 
                acq2xx__Transaction *out;
        } &result);
/**< run a script comprising a single Transaction Object, where
 *  the Transaction Object may itself be a list on transactions.
 *   Output includes status for each transaction executed
 */


/** remote shell transaction */
class acq2xx__ShellTransaction : public acq2xx__Transaction
{

public:
        char* command;
        char* result;
public: 
        acq2xx__ShellTransaction(char *command);
        acq2xx__ShellTransaction();
        virtual ~acq2xx__ShellTransaction();
        virtual const char* getCommand();
        virtual const char* getResult();
        virtual void print();

protected:
        void initCommand(char command_buffer[]);
        virtual int run(struct soap *soap);
};

/** add acqcmd transaction **/


/** process states. */
enum STATE { 
        ST_STOP, 
        ST_ARM, 
        ST_RUN, 
        ST_TRIGGER, 
        ST_POSTPROCESS, 
        ST_CAPDONE 
};

/** reports  capture state main parameters. */
struct acq2xx__AcqStatus {
        enum STATE state;
        char* state_string;
        int numsamples;
        int prelen;
        int postlen;
        int elapsed;
        int nchan;
};






int acq2xx__getAcqStatus(struct acq2xx__AcqStatus& status);
/**< output capture state main parameters. */

int acq2xx__setArm(int block = false, struct acq2xx__AcqStatus& status);
/**< starts a capture. */

int acq2xx__waitStop(int timeout_sec, struct acq2xx__AcqStatus& status);
/**< wait until stopped, up until timeout (min=1s, max=10s). 
 *  Detect timeout by status.state != ST_STOP
 */

/** input signal edge control. */
enum acq2xx__EDGE { 
        EDGE_FALLING, EDGE_RISING 
};
/** input signal line select. */
enum acq2xx__DIx { 
        DI_NONE, 
        DI0, DI1, DI2, DI3, DI4, DI5 
};
/** output signal line select. */
enum acq2xx__DOx { 
        DO_NONE, 
        DO0, DO1, DO2, DO3, DO4, DO5 
};
/** capture modes. */
enum acq2xx__MODE { 
        MODE_SOFT_TRANSIENT, 
        MODE_TRIGGERED_CONTINUOUS, 
        MODE_GATED_TRANSIENT,
        MODE_SOFT_CONTINUOUS
};


/** aggregate holds full signal definition. */
struct acq2xx__Signal {
        enum acq2xx__DIx dix;
        enum acq2xx__EDGE edge;
};


/** sets capture mode, prelen, postlen */
class acq2xx__ModeSetTransaction : public acq2xx__ShellTransaction {    
public:
        enum acq2xx__MODE mode;
        int prelen;
        int postlen;
protected:
        virtual int run(struct soap* soap);
public:
        acq2xx__ModeSetTransaction(
                enum acq2xx__MODE mode,
                int prelen,
                int postlen             
        );
        acq2xx__ModeSetTransaction();
        virtual void print();
};


class acq2xx__ClockSetTransaction : public acq2xx__ShellTransaction {
public:
        acq2xx__ClockSetTransaction(char *command);
};

/** configures internal clock. */
class acq2xx__InternalClockSetTransaction : public acq2xx__ClockSetTransaction{
        int hz;
        int div;
        enum acq2xx__DOx dox;
protected:
        virtual int run(struct soap* soap);

public:
        acq2xx__InternalClockSetTransaction(
                int hz,
                int div = 1,
                enum acq2xx__DOx dox = DO_NONE);
};

/** configures external clock signal. */
class acq2xx__ExternalClockSetTransaction : public acq2xx__ClockSetTransaction {
        enum acq2xx__DIx dix;
        int div;
        enum acq2xx__DOx dox;
protected:
        virtual int run(struct soap* soap);

public:
        acq2xx__ExternalClockSetTransaction(
                enum acq2xx__DIx dix,
                int div = 1,
                enum acq2xx__DOx dox = DO_NONE);
};

/** generic signal setting transaction. */
class acq2xx__SignalSetTransaction : public acq2xx__ShellTransaction {

        char *signal;
        enum acq2xx__DIx dix;
        enum acq2xx__EDGE edge;

protected:
        virtual int run(struct soap* soap);
        
public:
        acq2xx__SignalSetTransaction(
                char *signal,
                enum acq2xx__DIx dix,
                enum acq2xx__EDGE edge = EDGE_FALLING);
};

/** sets main parameters to define a shot. */
class acq2xx__AcqControlTransaction : public acq2xx__TransactionList {

public:
        acq2xx__AcqControlTransaction(
                acq2xx__ModeSetTransaction* modeSet,
                acq2xx__ClockSetTransaction* clockSet,
                acq2xx__SignalSetTransaction* trigger,
                acq2xx__SignalSetTransaction* event0
                );
        acq2xx__AcqControlTransaction();
};


class acq2xx__GetAvailableChannelsTransaction : public acq2xx__ShellTransaction {
public:
        int AI, AO;
        acq2xx__GetAvailableChannelsTransaction();
        
protected:
        virtual int run(struct soap* soap);
};


/** returns current calibration settings */
class acq2xx__GetVRangeTransaction : public acq2xx__ShellTransaction {
public:
        /** single channel calibration range */
        struct VRange { float min; float max; };
        acq2xx__GetAvailableChannelsTransaction* channels;


private:
        struct VRangeData{
                struct VRange *__ptr;
                int __size;
        } ranges;
public:
        
        acq2xx__GetVRangeTransaction();

        const struct VRange& getVRange(int channel) const;

protected:
        virtual int run(struct soap* soap);
};

---