Main Page | Namespace List | Class Hierarchy | Data Structures | File List | Data Fields | Globals | Related Pages

acq2xx.h

Go to the documentation of this file.
00001 /* ------------------------------------------------------------------------- */
00002 /* file acq2xx.h                                                             */
00003 /* ------------------------------------------------------------------------- */
00004 /*   Copyright (C) 2006 Peter Milne, D-TACQ Solutions Ltd
00005  *                      <Peter dot Milne at D hyphen TACQ dot com>
00006 
00007     This program is free software; you can redistribute it and/or modify
00008     it under the terms of Version 2 of the GNU General Public License
00009     as published by the Free Software Foundation;
00010 
00011     This program is distributed in the hope that it will be useful,
00012     but WITHOUT ANY WARRANTY; without even the implied warranty of
00013     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014     GNU General Public License for more details.
00015 
00016     You should have received a copy of the GNU General Public License
00017     along with this program; if not, write to the Free Software
00018     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.                */
00019 /* ------------------------------------------------------------------------- */
00020 
00021 /** @file acq2xx.h ACQ2xx web service definition. */
00022 
00023 /** @mainpage ACQ2XX Webservice Interface.
00024  *  @version $Revision: 1.22 $
00025  *  @author peter.milne@d-tacq.com
00026  
00027  *  - Aim:
00028  *   - Provide a SOAP format webservice as a universal remote 
00029  *       control interface.
00030  *  - Goals
00031  *   - cross platform C++ RPC, with both low level and functional control, 
00032  *        using supplied client-side library (tested Linux and Windows).
00033  *   - cross platform Webservice, based on WSDL service definition, clients 
00034  *        can be generated using WS tools
00035  *  - Service provided on three levels
00036  *   -  Low Level Interface
00037  *    - acq2sh - remote shell interface
00038  *    - acqcmd - emulates traditional acqcmd interface
00039  *    - getVersion - compare client, server interface versions
00040  *   - Transactional Interface
00041  *    - acq2script - allows multiple transactions Objects to be processed in 
00042  *      a single request with full status checking. 
00043  *      Stops on first error by default.
00044  *   - Functional Interface
00045  *    - high level system control transactions Classes available to 
00046  *      complete most common setups, providing a client-side API.
00047  *    - dedicated methods for the most commonly repeated functional controls.
00048  *
00049  * - Implementation
00050  *  - server side implementation is based on gsoap:
00051  *     http://www.cs.fsu.edu/~engelen/soap.html
00052  *  - interface is defined in this file @ref acq2xx.h
00053  *  - RPC functions, and high Transaction objects.
00054  *  - a client side gsoap implementation is provided as
00055  *   - standalone low level client app
00056  *   - function application to demonstrate use of the API 
00057  *  - Webservices based on generated WSDL - possibility to autogenerate
00058  *    applications in common webservice frameworks, eg .NET, Java, PERL.
00059  * - Operation
00060  *  - webservice operates as a dedicated multi-threaded service running on:
00061  *   - http://ACQ2XX_CARD:6666
00062  *    - service is enabled by /ffs/dropbear/etc/auxd/auxd.3.conf
00063  *  - wsdl available at
00064  *   - http://ACQ2XX_CARD/acq2xx.wsdl
00065  *    - this wsdl is normalized to declare the service location to be at the 
00066  *      ip address of eth0. It doesn't use hostname as not all systems use DNS
00067  *      for the "acq2xx" clients
00068  *
00069  * - Client Side Libraries
00070  *   - Linux:
00071  *    - libstdsoap2.so
00072  *    - object modules comprising api
00073  *   - Windows:
00074  *    - DLL to follow, use object modules at present.
00075  * - Client Side applications:
00076  *  - acq2xx_client - see acq2xx_client.cpp
00077  *
00078  * - Performance.
00079  *    SOAP is a human readable, XML protocol. So you would expect it to be slow.
00080  *    However, D-TACQ testing shows that this interface is capable of a respectable 25 transactions per second. 
00081  *    This performance is adequate for the normal shot-based use case for ACQ196/ACQ216.
00082  *    The advantage of the WS/SOAP approach is portability and extensibility, coupled with an easy to
00083  *    user object oriented program model on the client.
00084  * - Extensions
00085  *  - VB.NET client application - planned.
00086  *  - Windows DLL - planned.
00087  *  - access from Java JAX-WS (less urgent, dt100rc works).
00088  *  - Use SSL for secure access - possible.
00089  */
00090 
00091 //gsoap acq2xx service name: acq2xx
00092 //gsoap acq2xx service encoding: literal
00093 //gsoap acq2xx service namespace: http://www.d-tacq.com
00094 //gsoap acq2xx service location: http://ACQ2XX_IP_ADDRESS:6666
00095 //gsoap acq2xx schema elementForm: qualified
00096 //gsoap acq2xx schema attributeForm: qualified
00097 
00098 
00099 /* acq2xx local shell script takes default wsdl and normalizes it to reference
00100  * local ip address 
00101 
00102 
00103 #define ACQ2XX_H_VERSION "$Revision: 1.22 $"
00104 
00105 /** Low Level functions */
00106 
00107 int acq2xx__getVersion(char *client_version, char*& server_version);
00108 /**< version check - allows client, server to compare ACQ2XX_H_VERSION */
00109 
00110 int acq2xx__acqcmd(char* command, char*& response);
00111 /**< remote "acqcmd" */
00112 int acq2xx__acq2sh(char* command, char*& response);
00113 /**< remote shell command. */
00114 
00115 
00116 
00117 
00118 /** Class definitions for Transactional/Functional API */
00119 
00120 /** generic top level Object.*/
00121 class acq2xx__Object {
00122 public:
00123         char *name;
00124         acq2xx__Object();
00125         acq2xx__Object(const char* name);
00126         virtual ~acq2xx__Object();
00127         virtual void print();
00128         const char* getName();
00129 };
00130 
00131 
00132 struct soap;    /** opaque context */
00133 
00134 /** generic command/response remote transaction with status. */
00135 class acq2xx__Transaction : public acq2xx__Object {
00136 public:
00137 
00138         int abort_on_error;
00139         int status;
00140         int complete;
00141 
00142         acq2xx__Transaction();
00143         acq2xx__Transaction(const char *name);
00144         virtual ~acq2xx__Transaction();
00145         virtual void print();
00146         void exec(struct soap *soap);
00147         
00148         virtual const char* getCommand();
00149         virtual const char* getResult();
00150 protected:
00151         virtual int run(struct soap *soap);
00152 };
00153 
00154 /** container. */
00155 class acq2xx__TransactionList: public acq2xx__Transaction
00156 { 
00157 public:
00158         acq2xx__Transaction **__ptr; // array of pointers to objects
00159         int __size;
00160         acq2xx__TransactionList();
00161         acq2xx__TransactionList(int size);
00162         virtual ~acq2xx__TransactionList();
00163         virtual acq2xx__Transaction*& operator[](int i);
00164         virtual void print();
00165 
00166         int getSize();
00167 protected:
00168         virtual int run(struct soap *soap);
00169 };
00170 
00171 int acq2xx__acq2script(
00172         acq2xx__Transaction *in, 
00173         struct acq2xx__acq2scriptResponse { 
00174                 acq2xx__Transaction *out;
00175         } &result);
00176 /**< run a script comprising a single Transaction Object, where
00177  *  the Transaction Object may itself be a list on transactions.
00178  *   Output includes status for each transaction executed
00179  */
00180 
00181 
00182 /** remote shell transaction */
00183 class acq2xx__ShellTransaction : public acq2xx__Transaction
00184 {
00185 
00186 public:
00187         char* command;
00188         char* result;
00189 public: 
00190         acq2xx__ShellTransaction(char *command);
00191         acq2xx__ShellTransaction();
00192         virtual ~acq2xx__ShellTransaction();
00193         virtual const char* getCommand();
00194         virtual const char* getResult();
00195         virtual void print();
00196 
00197 protected:
00198         void initCommand(char command_buffer[]);
00199         virtual int run(struct soap *soap);
00200 };
00201 
00202 /** add acqcmd transaction **/
00203 
00204 
00205 /** process states. */
00206 enum STATE { 
00207         ST_STOP, 
00208         ST_ARM, 
00209         ST_RUN, 
00210         ST_TRIGGER, 
00211         ST_POSTPROCESS, 
00212         ST_CAPDONE 
00213 };
00214 
00215 /** reports  capture state main parameters. */
00216 struct acq2xx__AcqStatus {
00217         enum STATE state;
00218         char* state_string;
00219         int numsamples;
00220         int prelen;
00221         int postlen;
00222         int elapsed;
00223         int nchan;
00224 };
00225 
00226 
00227 
00228 
00229 
00230 
00231 int acq2xx__getAcqStatus(struct acq2xx__AcqStatus& status);
00232 /**< output capture state main parameters. */
00233 
00234 int acq2xx__setArm(int block = false, struct acq2xx__AcqStatus& status);
00235 /**< starts a capture. */
00236 
00237 int acq2xx__waitStop(int timeout_sec, struct acq2xx__AcqStatus& status);
00238 /**< wait until stopped, up until timeout (min=1s, max=10s). 
00239  *  Detect timeout by status.state != ST_STOP
00240  */
00241 
00242 /** input signal edge control. */
00243 enum acq2xx__EDGE { 
00244         EDGE_FALLING, EDGE_RISING 
00245 };
00246 /** input signal line select. */
00247 enum acq2xx__DIx { 
00248         DI_NONE, 
00249         DI0, DI1, DI2, DI3, DI4, DI5 
00250 };
00251 /** output signal line select. */
00252 enum acq2xx__DOx { 
00253         DO_NONE, 
00254         DO0, DO1, DO2, DO3, DO4, DO5 
00255 };
00256 /** capture modes. */
00257 enum acq2xx__MODE { 
00258         MODE_SOFT_TRANSIENT, 
00259         MODE_TRIGGERED_CONTINUOUS, 
00260         MODE_GATED_TRANSIENT,
00261         MODE_SOFT_CONTINUOUS
00262 };
00263 
00264 
00265 /** aggregate holds full signal definition. */
00266 struct acq2xx__Signal {
00267         enum acq2xx__DIx dix;
00268         enum acq2xx__EDGE edge;
00269 };
00270 
00271 
00272 /** sets capture mode, prelen, postlen */
00273 class acq2xx__ModeSetTransaction : public acq2xx__ShellTransaction {    
00274 public:
00275         enum acq2xx__MODE mode;
00276         int prelen;
00277         int postlen;
00278 protected:
00279         virtual int run(struct soap* soap);
00280 public:
00281         acq2xx__ModeSetTransaction(
00282                 enum acq2xx__MODE mode,
00283                 int prelen,
00284                 int postlen             
00285         );
00286         acq2xx__ModeSetTransaction();
00287         virtual void print();
00288 };
00289 
00290 
00291 class acq2xx__ClockSetTransaction : public acq2xx__ShellTransaction {
00292 public:
00293         acq2xx__ClockSetTransaction(char *command);
00294 };
00295 
00296 /** configures internal clock. */
00297 class acq2xx__InternalClockSetTransaction : public acq2xx__ClockSetTransaction{
00298         int hz;
00299         int div;
00300         enum acq2xx__DOx dox;
00301 protected:
00302         virtual int run(struct soap* soap);
00303 
00304 public:
00305         acq2xx__InternalClockSetTransaction(
00306                 int hz,
00307                 int div = 1,
00308                 enum acq2xx__DOx dox = DO_NONE);
00309 };
00310 
00311 /** configures external clock signal. */
00312 class acq2xx__ExternalClockSetTransaction : public acq2xx__ClockSetTransaction {
00313         enum acq2xx__DIx dix;
00314         int div;
00315         enum acq2xx__DOx dox;
00316 protected:
00317         virtual int run(struct soap* soap);
00318 
00319 public:
00320         acq2xx__ExternalClockSetTransaction(
00321                 enum acq2xx__DIx dix,
00322                 int div = 1,
00323                 enum acq2xx__DOx dox = DO_NONE);
00324 };
00325 
00326 /** generic signal setting transaction. */
00327 class acq2xx__SignalSetTransaction : public acq2xx__ShellTransaction {
00328 
00329         char *signal;
00330         enum acq2xx__DIx dix;
00331         enum acq2xx__EDGE edge;
00332 
00333 protected:
00334         virtual int run(struct soap* soap);
00335         
00336 public:
00337         acq2xx__SignalSetTransaction(
00338                 char *signal,
00339                 enum acq2xx__DIx dix,
00340                 enum acq2xx__EDGE edge = EDGE_FALLING);
00341 };
00342 
00343 /** sets main parameters to define a shot. */
00344 class acq2xx__AcqControlTransaction : public acq2xx__TransactionList {
00345 
00346 public:
00347         acq2xx__AcqControlTransaction(
00348                 acq2xx__ModeSetTransaction* modeSet,
00349                 acq2xx__ClockSetTransaction* clockSet,
00350                 acq2xx__SignalSetTransaction* trigger,
00351                 acq2xx__SignalSetTransaction* event0
00352                 );
00353         acq2xx__AcqControlTransaction();
00354 };
00355 
00356 
00357 class acq2xx__GetAvailableChannelsTransaction : public acq2xx__ShellTransaction {
00358 public:
00359         int AI, AO;
00360         acq2xx__GetAvailableChannelsTransaction();
00361         
00362 protected:
00363         virtual int run(struct soap* soap);
00364 };
00365 
00366 
00367 /** returns current calibration settings */
00368 class acq2xx__GetVRangeTransaction : public acq2xx__ShellTransaction {
00369 public:
00370         /** single channel calibration range */
00371         struct VRange { float min; float max; };
00372         acq2xx__GetAvailableChannelsTransaction* channels;
00373 
00374 
00375 private:
00376         struct VRangeData{
00377                 struct VRange *__ptr;
00378                 int __size;
00379         } ranges;
00380 public:
00381         
00382         acq2xx__GetVRangeTransaction();
00383 
00384         const struct VRange& getVRange(int channel) const;
00385 
00386 protected:
00387         virtual int run(struct soap* soap);
00388 };

Generated on Mon Aug 21 12:39:57 2006 for ACQ2XXWebServices by  doxygen 1.4.4