EPANET头文件解读系列3——TOOLKIT.H

/*
*******************************************************************

TOOLKIT.H - Prototypes for EPANET Functions Exported to DLL Toolkit           
VERSION:    2.00
DATE:       5/8/00
            10/25/00
            3/1/01
            8/15/07    (2.00.11)
            2/14/08    (2.00.12)
AUTHOR:     L. Rossman
            US EPA - NRMRL

*******************************************************************
*/

//comment by ccr 2013.09:该头文件的主要作用是定义了epanet2.dll中可以使用的函数的原型定义，类似于接口声明。

// --- Define DLLEXPORT
//comment by ccr 2013.09:定义了DLLEXPORT宏的原因是EPANET的代码是C语言写成的，为了能在C++代码中得以重用，需要extern "C"标记用C写成的函数,具体可以参考博文：http://www.cnblogs.com/KingOfFreedom/articles/3309469.html

#ifdef DLL
  #ifdef __cplusplus
  #define DLLEXPORT extern "C" __declspec(dllexport) __stdcall
  #else
  #define DLLEXPORT __declspec(dllexport) __stdcall
  #endif
#else
  #ifdef __cplusplus
  #define DLLEXPORT extern "C"
  #else
  #define DLLEXPORT
  #endif
#endif

// --- Define the EPANET toolkit constants
#define EN_ELEVATION    0    /* Node parameters */         //节点相关的参数
#define EN_BASEDEMAND   1                                 
#define EN_PATTERN      2
#define EN_EMITTER      3
#define EN_INITQUAL     4
#define EN_SOURCEQUAL   5
#define EN_SOURCEPAT    6
#define EN_SOURCETYPE   7
#define EN_TANKLEVEL    8
#define EN_DEMAND       9
#define EN_HEAD         10
#define EN_PRESSURE     11
#define EN_QUALITY      12
#define EN_SOURCEMASS   13
#define EN_INITVOLUME   14
#define EN_MIXMODEL     15
#define EN_MIXZONEVOL   16

#define EN_TANKDIAM     17
#define EN_MINVOLUME    18
#define EN_VOLCURVE     19
#define EN_MINLEVEL     20
#define EN_MAXLEVEL     21
#define EN_MIXFRACTION  22
#define EN_TANK_KBULK   23

#define EN_DIAMETER     0    /* Link parameters */           //管段相关的参数
#define EN_LENGTH       1
#define EN_ROUGHNESS    2
#define EN_MINORLOSS    3
#define EN_INITSTATUS   4
#define EN_INITSETTING  5
#define EN_KBULK        6
#define EN_KWALL        7
#define EN_FLOW         8
#define EN_VELOCITY     9
#define EN_HEADLOSS     10
#define EN_STATUS       11
#define EN_SETTING      12
#define EN_ENERGY       13

#define EN_DURATION     0    /* Time parameters */           //运行时间相关的参数
#define EN_HYDSTEP      1
#define EN_QUALSTEP     2
#define EN_PATTERNSTEP  3
#define EN_PATTERNSTART 4
#define EN_REPORTSTEP   5
#define EN_REPORTSTART  6
#define EN_RULESTEP     7
#define EN_STATISTIC    8
#define EN_PERIODS      9

#define EN_NODECOUNT    0   /* Component counts */           //拓扑组件中的各类对象的个数
#define EN_TANKCOUNT    1
#define EN_LINKCOUNT    2
#define EN_PATCOUNT     3
#define EN_CURVECOUNT   4
#define EN_CONTROLCOUNT 5

#define EN_JUNCTION     0    /* Node types */                //节点的种类
#define EN_RESERVOIR    1
#define EN_TANK         2

#define EN_CVPIPE       0    /* Link types. */               //管段的种类,大部分是各类阀门，注意模型中阀门因为其具有阻力较大而被抽象成管段
#define EN_PIPE         1    /* See LinkType in TYPES.H */
#define EN_PUMP         2
#define EN_PRV          3
#define EN_PSV          4
#define EN_PBV          5
#define EN_FCV          6
#define EN_TCV          7
#define EN_GPV          8

#define EN_NONE         0    /* Quality analysis types. */     //水质分析类型
#define EN_CHEM         1    /* See QualType in TYPES.H */
#define EN_AGE          2
#define EN_TRACE        3

#define EN_CONCEN       0    /* Source quality types.      */ 
#define EN_MASS         1    /* See SourceType in TYPES.H. */
#define EN_SETPOINT     2
#define EN_FLOWPACED    3

#define EN_CFS          0    /* Flow units types.   */         //流量的单位
#define EN_GPM          1    /* See FlowUnitsType   */
#define EN_MGD          2    /* in TYPES.H.         */
#define EN_IMGD         3
#define EN_AFD          4
#define EN_LPS          5
#define EN_LPM          6
#define EN_MLD          7
#define EN_CMH          8
#define EN_CMD          9

#define EN_TRIALS       0   /* Misc. options */               //选项部分
#define EN_ACCURACY     1
#define EN_TOLERANCE    2
#define EN_EMITEXPON    3
#define EN_DEMANDMULT   4

#define EN_LOWLEVEL     0   /* Control types.  */             //控制类型
#define EN_HILEVEL      1   /* See ControlType */
#define EN_TIMER        2   /* in TYPES.H.     */
#define EN_TIMEOFDAY    3

#define EN_AVERAGE      1   /* Time statistic types.    */    //时间统计类型
#define EN_MINIMUM      2   /* See TstatType in TYPES.H */
#define EN_MAXIMUM      3
#define EN_RANGE        4

#define EN_MIX1         0   /* Tank mixing models */         
#define EN_MIX2         1
#define EN_FIFO         2
#define EN_LIFO         3

#define EN_NOSAVE       0   /* Save-results-to-file flag */
#define EN_SAVE         1

#define EN_INITFLOW    10   /* Re-initialize flows flag  */

// --- Declare the EPANET toolkit functions
//comment by ccr 2013.09:本部分的函数的具体说明可以参考EPANET提供的“toolkit.chm”,里面有详细的使用说明以及例子.

int  DLLEXPORT ENepanet(char *, char *, char *, void (*) (char *));  //该函数用于运行一个完整的模拟计算

int  DLLEXPORT ENopen(char *, char *, char *);
 int  DLLEXPORT ENsaveinpfile(char *);                                           //将模型中的数据保存成标准的INPUT文件格式
 int  DLLEXPORT ENclose(void);

//水力解算相关的函数
 int  DLLEXPORT ENsolveH(void);           
 int  DLLEXPORT ENsaveH(void);
 int  DLLEXPORT ENopenH(void);
 int  DLLEXPORT ENinitH(int);
 int  DLLEXPORT ENrunH(long *);
 int  DLLEXPORT ENnextH(long *);
 int  DLLEXPORT ENcloseH(void);
 int  DLLEXPORT ENsavehydfile(char *);
 int  DLLEXPORT ENusehydfile(char *);

//水质解算相关的函数
 int  DLLEXPORT ENsolveQ(void);
 int  DLLEXPORT ENopenQ(void);
 int  DLLEXPORT ENinitQ(int);
 int  DLLEXPORT ENrunQ(long *);
 int  DLLEXPORT ENnextQ(long *);
 int  DLLEXPORT ENstepQ(long *);
 int  DLLEXPORT ENcloseQ(void);

//计算结果的报告格式输出
 int  DLLEXPORT ENwriteline(char *);
 int  DLLEXPORT ENreport(void);
 int  DLLEXPORT ENresetreport(void);
 int  DLLEXPORT ENsetreport(char *);

//获取管网中的控制、模型等信息
 int  DLLEXPORT ENgetcontrol(int, int *, int *, float *,
                int *, float *);
 int  DLLEXPORT ENgetcount(int, int *);
 int  DLLEXPORT ENgetoption(int, float *);
 int  DLLEXPORT ENgettimeparam(int, long *);
 int  DLLEXPORT ENgetflowunits(int *);
 int  DLLEXPORT ENgetpatternindex(char *, int *);
 int  DLLEXPORT ENgetpatternid(int, char *);
 int  DLLEXPORT ENgetpatternlen(int, int *);
 int  DLLEXPORT ENgetpatternvalue(int, int, float *);
 int  DLLEXPORT ENgetqualtype(int *, int *);
 int  DLLEXPORT ENgeterror(int, char *, int);

//获取管网中的节点的信息
 int  DLLEXPORT ENgetnodeindex(char *, int *);
 int  DLLEXPORT ENgetnodeid(int, char *);
 int  DLLEXPORT ENgetnodetype(int, int *);
 int  DLLEXPORT ENgetnodevalue(int, int, float *);

//获取管网中的管段等信息
 int  DLLEXPORT ENgetlinkindex(char *, int *);
 int  DLLEXPORT ENgetlinkid(int, char *);
 int  DLLEXPORT ENgetlinktype(int, int *);
 int  DLLEXPORT ENgetlinknodes(int, int *, int *);
 int  DLLEXPORT ENgetlinkvalue(int, int, float *);

int  DLLEXPORT ENgetversion(int *);
 
 //设置模型解算参数
 int  DLLEXPORT ENsetcontrol(int, int, int, float, int, float);
 int  DLLEXPORT ENsetnodevalue(int, int, float);
 int  DLLEXPORT ENsetlinkvalue(int, int, float);
 int  DLLEXPORT ENaddpattern(char *);
 int  DLLEXPORT ENsetpattern(int, float *, int);
 int  DLLEXPORT ENsetpatternvalue(int, int, float);
 int  DLLEXPORT ENsettimeparam(int, long);
 int  DLLEXPORT ENsetoption(int, float);
 int  DLLEXPORT ENsetstatusreport(int);
 int  DLLEXPORT ENsetqualtype(int, char *, char *, char *);