pqdh.h

PQDIF软件包(SDK,Software Development Kit),它能转换、生成并且显示PQDIF文件.对于开发电力系统的数据输出非常有用。

/*---------------------------------------------------------------------------
//
//  PQDH.h - Power Quality Data Manager Device Data Handler Interfaces.
//
//
//  Copyright (C) 1992-1993, Electrotek Concepts, Inc. All Rights Reserved.
//
//
//  This module defines the interfaces that client applications use
//  to communicate with Power Quality Data Manager Device Data Handlers.
//  These handlers that translate device specific data into a form that can
//  be stored in a data base.
//
//  This interface presents client applications with a high-level, device
//  independent view of power quality data. Each Device Data Handler (DDH)
//  hides the details of a particular class of data collection device.
//  DDHs are implemented as DLLs.
//
//  Communication between client applications and DDHs is facilitated
//  by the PQDH DLL. PQDH takes care of the dynamic linking between a client
//  application and a specific DDH. It acts as a call-level interface router.
//  Client applications call DDH functions indirectly via PQDH. Likewise,
//  DDHs call the client's call-back functions indirectly via PQDH. PQDH in
//  effect keeps track of which application is connected to which DDH.
//
//  PQDH provides additional services to client applications and DDHs. First
//  it implements default versions of all client call-back and DDH functions.
//  Clients and handlers need only implement those functions that are
//  appropriate and PQDH supplies the rest. PQDH also provides services to
//  allow clients to determine what DDHs are available and open DDHs for
//  processing.
//
//  Implementing the client side and handler side interfaces involves exporting
//  the appropriate functions and linking with the PQDH import library.
//  Client call-back functions are installed at run-time by the client
//  as follows:
//
//      Call PQDHOpen to begin a session.
//
//      Call PQDHSetCallBack to install the call-back functions.
//
//      Perform the desired operations via calls to PQDHGetFormats,
//      PQDHGetSites, PQDHGetEventChars, ...
//
//      Call PQDHClose to end the session.
//
//  All DDHs must implement a capability reporting function, "PQDHGestalt".
//  This function is queried by an application to determine what it can expect
//  of the DDH. This allows the developer of the DDH to implement only those
//  capabilities that are  appropriate. Further, this mechanism allows clients
//  to evolve without breaking existing handlers. For example, later versions
//  of a client might include the ability to ask a DDH to fetch raw
//  waveform data for a specific event from off-line storage. By querying each
//  DDH, the client could determine which handler support the capability and
//  take the appropriate action.
//
//  PQDH hides the connection between a specific device's data and
//  its handler. When PQDH is initialized it scans its local directory
//  for handler DLLs. The handlers are in turn queried for the types
//  of data formats that they support. This information is used by
//  PQDH to associate a data source with a particular handler in a fashion
//  that is transparent to the client.
//
//  A given handler can support one or more data formats. A handler
//  provides the client with information about the data formats it supports
//  as follows:
//
//      ENTER PQDHGetFormats (called by the client).
//
//          FOR each data format supported by the handler do
//
//              Call the PQDHAddFormat call-back-function to
//              register the format with the client.
//
//          END FOR
//
//      EXIT
//
//  PQDH supports the concept of a data store. Each data format references
//  a data store class. A data store contains data for one or more sites.
//  The implementation of a data store is left to the handler. For example,
//  a data store could be implemented with a single file, a directory of
//  files, a communications link to a remote device, etc.
//  
//  A client calls PQDHOpenDataStore to access device data for processing.
//  PQDHOpenDataStore takes a single text argument that specifies
//  the handler name, the data store format, and the "path"
//  to the specific data store to open. The handler name and data store
//  format information are as supplied by PQDHAddFormat. If a null string
//  is specified, PQDH conducts a dialog that allows the user to
//  choose the desired data store format. The appropriate handler is
//  then called to open a data store of that format. If the path
//  information is not specified, the handler conducts a dialog to
//  allow the user to select a data store.
//
//  Once a data store is opened, a client can load site data and
//  characteristic data via PQDHGetSites and PQDHGetEvents
//  respectively. In response to a PQDHGetSites request from a client,
//  the handler calls the client's PQDHBeginSite and PQDHEndSite functions
//  for each site in the data source.   
//
//  To load characteristic data, the client calls PQDHGetEvents
//  for a specific site and date/time range. The handler is responsible for
//  characterizing the data for each event in the specified range. The handler
//  passes the characterized event data to the client via call-back-functions.
//
//  The sequence of a data characterization operation is as follows:
//
//      ENTER PQDHGetEvents (called by client.)
//
//          Call the PQDHEventRequired call-back-function to see which
//          event characteristic records are required by the client.
//
//          Call PQDHBeginSite to begin processing for the specified site.
//          IF successful then ...
//
//              FOR each event in the specified range do
//
//                  Call the PQDHBeginEvent call-back-function to signal the
//                  start of a transcript that defines a new event to add
//                  to the data base.
//                  IF successful then ...
//
//                      Characterize the event. Generate the appropriate data
//                      and pack it into the records required.
//
//                      Call the PQDHAddEventChar call-back-function to attach
//                      each of the characterized event records to the event
//                      transcript.
//
//                      Call the PQDHEndEvent call-back-function to signal that
//                      processing for this event is complete.
//
//                  END IF
//
//              END FOR
//
//              Call PQDHEndSite to end processing for the specified site.
//
//          END IF
//
//      EXIT
//
//  Optionally, the client application can choose to not specify a
//  particular site to process. In this case PQDH displays a dialog
//  that allows the user to choose which sites to process. PQDH then
//  calls the handler's PQDHGetEvents function in turn for each site.
//
//  The client provides a call-back-function that is used by a handler to report
//  progress to the user. This function should also handle normal Windows
//  background processing and provide a means to allow a user to cancel an
//  operation in progress. The handler should call this function at a frequency
//  sufficient to ensure that the program remains responsive to the user.
//
//  Errors are transmitted between the client and the handler via PQDHSetError,
//  PQDHGetErrorType, and PQDHGetErrorDesc. A single error state is
//  maintained by PQDH. Whenever the client initiates an operation by calling
//  one of PQDH's main functions, the error status is cleared. In general,
//  Handler functions, client call-back-functions, and PQDH support functions
//  should report errors by calling PQDHSetError. PQDHSetError records a
//  general error classification code (e.g., no error pending, operation
//  canceled, operation failed) and a printable description of the error.
//
*/

#ifndef PQDH_h

    #define PQDH_h


    /* Use conventional "C" conventions to permit use by a wide
    range of compilers. */
    #ifdef __cplusplus
        extern "C" {            
    #endif



    /*----------------------------------------------------------------------
    //
    //  External Declarations.
    //
    */
    
    #include "PQDTypes.h"




    /*----------------------------------------------------------------------
    //
    //  Type and Class Declarations.
    //
    */


    /* Short hand for modifiers for all PQDH external functions. They must
    all be __export FAR PASCAL */
//    #define PQDHExtern __export FAR PASCAL
    #define PQDHExport __declspec (dllexport)
    #define PQDHExtern CALLBACK
    
    
    
    /* Error type codes. */
    typedef enum
        {

        pqdhErrNone,                /* No error. */
        pqdhErrCancel,              /* Operation canceled. */
        pqdhErrFail                 /* Operation failed. */

        } PQDHErrorType;

    
    /* Device/Handler combination codes. A unique code is defined
    for each handler version/device version. This facilitates
    maintenance that may be required. */
    typedef enum
        {

        pqdhPQNode1 = 1             /* PQNode handler, initial release. */

        } PQDHDevice;
    
    
    /* PQDHGestalt selector codes. */
    enum
        {

        pqdhGsGetFormats = 1,       /* Test for the PQDHGetFormats function. */
        pqdhGsGetSites,             /* Test for the PQDHGetSites function. */
        pqdhGsGetChars              /* Test for the PQDHGetEvents function. */

        };


    /* Maximum length of a data store specificaiton string (less
    the null termination character. */
    #define PQDHDSSpecLength 255


    /* Maximum length of a data store description string (less
    the null termination character. */
    #define PQDHDSDescLength 127
    
    
    /* Device data store reference template. The details of this record
    are private to the data handler. These records are analogous to
    stdio file handles. PQDH and its clients simply pass data store
    references between handler functions. */
    typedef void FAR * PQDHPDataStore;
    
    
    /* Characteristic record types. */
    typedef enum
        {

        pqdhCRNone,
        pqdhCRRMSVariation,
        pqdhCRWaveFault,
        pqdhCRTrend,
        pqdhCRWaveform

        } PQDHCRType;
        
    
    /* Event definition record. */
    typedef struct
        {
    
    
        /* Event date and time. */
        PQDDateTime dateTime;
        
        
        /* The device code for the device/handler combination that is
        generating the data for this event. */
        PQDHDevice device;
        
        
        /* The trigger phase, quantity, and time. The trigger
        time is an offset in seconds from "dateTime". For sampled
        events these fields should be set to pqdPhaseNone, pqdQtyNone,
        and 0.0 respectively. */
        PQDPhase triggerPhase;
        PQDQuantity triggerQuantity;
        double triggerTime;
        
        
        /* Base voltage used for determining trigger thresholds
        for this event. */
        double baseVoltage;
        
        
        /* Base MVA for this event. */
        double baseMVA;
        
        
        /* Fundamental frequency for this event. */
        double fundFreq;
        
        
        /* The cycle number for this event (-1 if unavailable.) */
        long cycleNumber;
        
       
        } PQDHEvent;
    
    
    /* Triggered RMS Variation record template. */
    typedef struct
        {
            
        
        /* Quantity and phase codes for this record. */
        PQDQuantity quantity;
        PQDPhase phase;
        
        
        /* Event duration in seconds. */
        double duration;            

        
        /* Magnitude envelope. */
        double minimum; 
        double maximum;
        double average;


        /* Maximum deviation from nominal. */       
        double maxDeviation;
        
        
        /* Area between RMS Variation curve and nominal. */     
        double area;

        
        } PQDHRMSVariation;
    
    
    /* Triggered Waveform record template. */
    typedef struct
        {
        
                
        /* Quantity and phase codes for this record. */
        PQDQuantity quantity;
        PQDPhase phase;
        
        
        /* Wave Fault classification. */
        PQDWaveFaultType wfType;


        /* Rise time in seconds. */     
        double riseTime;
        
        
        /* Duration in seconds. */
        double duration;
        
        
        /* Principal frequency of the transient in Hz. */ 
        double principalFreq;