a
This commit is contained in:
coco
@@ -0,0 +1,902 @@
|
||||
# API参考
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [DevManager.h](file://h\DevManager.h)
|
||||
- [DevManager.cpp](file://cpp\Managers\DevManager.cpp)
|
||||
- [ProManager.h](file://h\ProManager.h)
|
||||
- [ProManager.cpp](file://cpp\Managers\ProManager.cpp)
|
||||
- [SptManager.h](file://h\SptManager.h)
|
||||
- [SptManager.cpp](file://cpp\Managers\SptManager.cpp)
|
||||
- [TdManager.h](file://h\TdManager.h)
|
||||
- [TdManager.cpp](file://cpp\Managers\TdManager.cpp)
|
||||
- [IOManager.h](file://h\IOManager.h)
|
||||
- [IOManager.cpp](file://cpp\Managers\IOManager.cpp)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [DevManager API](#devmanager-api)
|
||||
3. [ProManager API](#promanager-api)
|
||||
4. [SptManager API](#sptmanager-api)
|
||||
5. [TdManager API](#tdmanager-api)
|
||||
6. [IOManager API](#iomanager-api)
|
||||
7. [API调用链与依赖关系](#api调用链与依赖关系)
|
||||
8. [线程安全性说明](#线程安全性说明)
|
||||
9. [使用示例](#使用示例)
|
||||
|
||||
## 简介
|
||||
本文档为Geomative Studio软件系统中的核心管理器类提供详细的API参考。文档涵盖DevManager、ProManager、SptManager、TdManager和IOManager五个核心管理器类的公共接口，详细说明了各方法的签名、参数、返回值、异常情况以及使用场景。同时，文档解释了API的调用顺序、线程安全性，并提供了实际代码示例，为集成开发和自动化脚本提供了必要的技术参考。
|
||||
|
||||
## DevManager API
|
||||
|
||||
DevManager类负责管理设备的生命周期，包括设备的添加、删除、查询和状态更新。该管理器维护设备在内存中的链接列表，并处理与数据库的交互。
|
||||
|
||||
### 公共方法
|
||||
|
||||
#### GetDeviceByID
|
||||
根据设备ID获取设备对象。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
CDevice* GetDeviceByID(DWORD dwDevID)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwDevID`: 设备的唯一标识符
|
||||
|
||||
**返回值**
|
||||
- 成功时返回指向CDevice对象的指针，失败时返回NULL
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常抛出，但会通过调试输出记录操作日志
|
||||
|
||||
**使用场景**
|
||||
- 当需要根据设备ID查找特定设备时使用
|
||||
|
||||
**Section sources**
|
||||
- [DevManager.h](file://h\DevManager.h#L21)
|
||||
- [DevManager.cpp](file://cpp\Managers\DevManager.cpp#L48-L68)
|
||||
|
||||
#### GetDevice
|
||||
根据设备句柄获取设备对象。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
CDevice* GetDevice(DWORD dwHandle)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwHandle`: 设备的句柄
|
||||
|
||||
**返回值**
|
||||
- 成功时返回指向CDevice对象的指针，失败时返回NULL
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常抛出
|
||||
|
||||
**使用场景**
|
||||
- 在设备操作过程中，通过句柄快速获取设备对象
|
||||
|
||||
**Section sources**
|
||||
- [DevManager.h](file://h\DevManager.h#L22)
|
||||
- [DevManager.cpp](file://cpp\Managers\DevManager.cpp#L82-L89)
|
||||
|
||||
#### AddDevice
|
||||
向系统中添加新设备。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
BOOL AddDevice(CDevice* const pDev)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `pDev`: 指向要添加的设备对象的常量指针
|
||||
|
||||
**返回值**
|
||||
- 成功时返回TRUE，失败时返回FALSE
|
||||
|
||||
**异常情况**
|
||||
- 在数据库事务处理中捕获_com_error异常，并显示错误消息
|
||||
- 操作失败时会回滚数据库事务
|
||||
|
||||
**使用场景**
|
||||
- 当检测到新设备并需要将其注册到系统中时使用
|
||||
|
||||
**Section sources**
|
||||
- [DevManager.h](file://h\DevManager.h#L30)
|
||||
- [DevManager.cpp](file://cpp\Managers\DevManager.cpp#L203-L280)
|
||||
|
||||
#### DeleteDevice
|
||||
从系统中删除设备。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
BOOL DeleteDevice(DWORD dwHandle)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwHandle`: 要删除设备的句柄
|
||||
|
||||
**返回值**
|
||||
- 成功时返回TRUE，失败时返回FALSE
|
||||
|
||||
**异常情况**
|
||||
- 捕获所有异常，操作失败时回滚数据库事务
|
||||
|
||||
**使用场景**
|
||||
- 当设备被移除或不再需要时，从系统中彻底删除设备
|
||||
|
||||
**Section sources**
|
||||
- [DevManager.h](file://h\DevManager.h#L37)
|
||||
- [DevManager.cpp](file://cpp\Managers\DevManager.cpp#L383-L432)
|
||||
|
||||
#### InitialDevLinkList
|
||||
初始化设备链接列表。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
void InitialDevLinkList()
|
||||
```
|
||||
|
||||
**参数**
|
||||
- 无
|
||||
|
||||
**返回值**
|
||||
- 无
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常处理
|
||||
|
||||
**使用场景**
|
||||
- 在系统启动或设备管理器初始化时，重新加载所有设备到内存中
|
||||
|
||||
**Section sources**
|
||||
- [DevManager.h](file://h\DevManager.h#L29)
|
||||
- [DevManager.cpp](file://cpp\Managers\DevManager.cpp#L160-L201)
|
||||
|
||||
#### UpdateDevInfo
|
||||
更新设备信息。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
void UpdateDevInfo(STSynDevParam stDevParam, BYTE bRemoteDeveTyp)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `stDevParam`: 包含设备参数的结构体
|
||||
- `bRemoteDeveTyp`: 远程设备类型
|
||||
|
||||
**返回值**
|
||||
- 无
|
||||
|
||||
**异常情况**
|
||||
- 捕获_com_error异常并显示错误信息
|
||||
|
||||
**使用场景**
|
||||
- 当从设备接收到同步参数时，更新数据库中的设备信息
|
||||
|
||||
**Section sources**
|
||||
- [DevManager.h](file://h\DevManager.h#L39)
|
||||
- [DevManager.cpp](file://cpp\Managers\DevManager.cpp#L592-L641)
|
||||
|
||||
## ProManager API
|
||||
|
||||
ProManager类负责管理项目（Project）和测区（Testing Zone）的层次结构，处理项目与设备之间的同步。
|
||||
|
||||
### 公共方法
|
||||
|
||||
#### CreateProjectInDB
|
||||
在数据库中创建新项目。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
UINT CreateProjectInDB(DWORD& dwID)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwID`: 输出参数，返回创建项目的ID
|
||||
|
||||
**返回值**
|
||||
- APP_SUCCESS: 创建成功
|
||||
- APP_CANCLE: 用户取消操作
|
||||
- APP_FAIL: 创建失败
|
||||
|
||||
**异常情况**
|
||||
- 在数据库操作中捕获_com_error异常，显示适当的错误消息并回滚事务
|
||||
|
||||
**使用场景**
|
||||
- 当用户通过UI创建新项目时，此方法处理数据库层面的创建逻辑
|
||||
|
||||
**Section sources**
|
||||
- [ProManager.h](file://h\ProManager.h#L51)
|
||||
- [ProManager.cpp](file://cpp\Managers\ProManager.cpp#L249-L316)
|
||||
|
||||
#### CreateProjectInDev
|
||||
在设备中创建项目。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
UINT CreateProjectInDev(DWORD dwID, CDevice* const pDev)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwID`: 项目的数据库ID
|
||||
- `pDev`: 指向目标设备的常量指针
|
||||
|
||||
**返回值**
|
||||
- APP_SUCCESS: 创建成功
|
||||
- APP_DUPLICATE: 项目已存在
|
||||
- APP_FAIL: 创建失败
|
||||
- APP_OVERFLOW: 项目数量超出限制
|
||||
|
||||
**异常情况**
|
||||
- 处理文件传输失败的情况，删除已创建的项目以保持一致性
|
||||
|
||||
**使用场景**
|
||||
- 当项目在数据库中创建后，需要将项目同步到指定设备时使用
|
||||
|
||||
**Section sources**
|
||||
- [ProManager.h](file://h\ProManager.h#L50)
|
||||
- [ProManager.cpp](file://cpp\Managers\ProManager.cpp#L343-L482)
|
||||
|
||||
#### CreateDefaultTzInDev
|
||||
在设备中为项目创建默认测区。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
UINT CreateDefaultTzInDev(DWORD dwProID, CDevice* const pDev)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwProID`: 项目的ID
|
||||
- `pDev`: 指向目标设备的常量指针
|
||||
|
||||
**返回值**
|
||||
- APP_SUCCESS: 创建成功
|
||||
- APP_DUPLICATE: 测区已存在
|
||||
- APP_FAIL: 创建失败
|
||||
|
||||
**异常情况**
|
||||
- 在数据库操作中捕获_com_error异常，操作失败时回滚事务
|
||||
|
||||
**使用场景**
|
||||
- 当项目在设备中创建后，自动创建默认测区以确保项目结构完整性
|
||||
|
||||
**Section sources**
|
||||
- [ProManager.h](file://h\ProManager.h#L60)
|
||||
- [ProManager.cpp](file://cpp\Managers\ProManager.cpp#L485-L706)
|
||||
|
||||
#### ShowProList
|
||||
显示设备关联的项目列表。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
bool ShowProList(DWORD dwDevHandle, CListCtrl& proList)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwDevHandle`: 设备句柄
|
||||
- `proList`: 引用CListCtrl控件，用于显示项目列表
|
||||
|
||||
**返回值**
|
||||
- 操作成功返回true，失败返回false
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常处理
|
||||
|
||||
**使用场景**
|
||||
- 在UI中显示特定设备关联的所有项目列表
|
||||
|
||||
**Section sources**
|
||||
- [ProManager.h](file://h\ProManager.h#L56)
|
||||
- [ProManager.cpp](file://cpp\Managers\ProManager.cpp#L184-L246)
|
||||
|
||||
#### ShowTzList
|
||||
显示项目关联的测区列表。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
bool ShowTzList(DWORD dwProHandle, CListCtrl& tzList)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwProHandle`: 项目句柄
|
||||
- `tzList`: 引用CListCtrl控件，用于显示测区列表
|
||||
|
||||
**返回值**
|
||||
- 操作成功返回true，失败返回false
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常处理
|
||||
|
||||
**使用场景**
|
||||
- 在UI中显示特定项目下的所有测区列表
|
||||
|
||||
**Section sources**
|
||||
- [ProManager.h](file://h\ProManager.h#L58)
|
||||
- [ProManager.cpp](file://cpp\Managers\ProManager.cpp#L53-L92)
|
||||
|
||||
#### DeleteProjectInDB
|
||||
从数据库中删除项目。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
void DeleteProjectInDB(DWORD dwID)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwID`: 要删除项目的ID
|
||||
|
||||
**返回值**
|
||||
- 无
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常处理
|
||||
|
||||
**使用场景**
|
||||
- 当需要从数据库中永久删除项目及其相关数据时使用
|
||||
|
||||
**Section sources**
|
||||
- [ProManager.h](file://h\ProManager.h#L48)
|
||||
- [ProManager.cpp](file://cpp\Managers\ProManager.cpp#L485-L706)
|
||||
|
||||
## SptManager API
|
||||
|
||||
SptManager类负责管理脚本（Script）的创建、删除和同步，支持1D、2D和3D测量脚本。
|
||||
|
||||
### 公共方法
|
||||
|
||||
#### CreateCESConInDB
|
||||
在数据库中创建1D脚本。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
UINT CreateCESConInDB(DWORD& dwSConID)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwSConID`: 输出参数，返回创建脚本的ID
|
||||
|
||||
**返回值**
|
||||
- APP_SUCCESS: 创建成功
|
||||
- APP_CANCLE: 用户取消操作
|
||||
- APP_FAIL: 创建失败
|
||||
|
||||
**异常情况**
|
||||
- 在数据库操作中捕获_com_error异常，操作失败时回滚事务
|
||||
|
||||
**使用场景**
|
||||
- 当用户创建新的1D测量脚本时，此方法处理数据库存储
|
||||
|
||||
**Section sources**
|
||||
- [SptManager.h](file://h\SptManager.h#L41)
|
||||
- [SptManager.cpp](file://cpp\Managers\SptManager.cpp#L548-L795)
|
||||
|
||||
#### Create2DSConInDB
|
||||
在数据库中创建2D脚本。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
UINT Create2DSConInDB(DWORD& dwSConID)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwSConID`: 输出参数，返回创建脚本的ID
|
||||
|
||||
**返回值**
|
||||
- APP_SUCCESS: 创建成功
|
||||
- APP_CANCLE: 用户取消操作
|
||||
- APP_FAIL: 创建失败
|
||||
|
||||
**异常情况**
|
||||
- 在数据库操作中捕获_com_error异常，操作失败时回滚事务
|
||||
|
||||
**使用场景**
|
||||
- 当用户创建新的2D测量脚本时，此方法处理数据库存储
|
||||
|
||||
**Section sources**
|
||||
- [SptManager.h](file://h\SptManager.h#L44)
|
||||
- [SptManager.cpp](file://cpp\Managers\SptManager.cpp#L257-L486)
|
||||
|
||||
#### PutScriptToDev
|
||||
将脚本下传至设备。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
UINT PutScriptToDev(DWORD dwSCID, CDevice* const pDev)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwSCID`: 脚本的数据库ID
|
||||
- `pDev`: 指向目标设备的常量指针
|
||||
|
||||
**返回值**
|
||||
- APP_SUCCESS: 传输成功
|
||||
- APP_DUPLICATE: 脚本已存在
|
||||
- APP_FAIL: 传输失败
|
||||
|
||||
**异常情况**
|
||||
- 处理文件传输失败的情况，删除设备上已创建的脚本以保持一致性
|
||||
|
||||
**使用场景**
|
||||
- 当需要将数据库中的脚本同步到测量设备时使用
|
||||
|
||||
**Section sources**
|
||||
- [SptManager.h](file://h\SptManager.h#L34)
|
||||
- [SptManager.cpp](file://cpp\Managers\SptManager.cpp#L257-L486)
|
||||
|
||||
#### LoadScriptFromDev
|
||||
从设备加载脚本。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
UINT LoadScriptFromDev(CString szSptFileName, CDevice* const pDev)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `szSptFileName`: 脚本文件名
|
||||
- `pDev`: 指向源设备的常量指针
|
||||
|
||||
**返回值**
|
||||
- APP_SUCCESS: 加载成功
|
||||
- APP_FAIL: 加载失败
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常处理
|
||||
|
||||
**使用场景**
|
||||
- 当需要从设备上载脚本到数据库时使用
|
||||
|
||||
**Section sources**
|
||||
- [SptManager.h](file://h\SptManager.h#L33)
|
||||
- [SptManager.cpp](file://cpp\Managers\SptManager.cpp#L257-L486)
|
||||
|
||||
#### GetScript
|
||||
获取脚本对象。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
CScript* GetScript(DWORD dwHandle)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwHandle`: 脚本句柄
|
||||
|
||||
**返回值**
|
||||
- 成功时返回指向CScript对象的指针，失败时返回NULL
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常抛出
|
||||
|
||||
**使用场景**
|
||||
- 在脚本操作过程中，通过句柄获取脚本对象进行操作
|
||||
|
||||
**Section sources**
|
||||
- [SptManager.h](file://h\SptManager.h#L38)
|
||||
- [SptManager.cpp](file://cpp\Managers\SptManager.cpp#L127-L156)
|
||||
|
||||
#### Delete2DSConInDB
|
||||
从数据库中删除2D脚本。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
void Delete2DSConInDB(DWORD dwSConID)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwSConID`: 要删除脚本的ID
|
||||
|
||||
**返回值**
|
||||
- 无
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常处理
|
||||
|
||||
**使用场景**
|
||||
- 当需要从数据库中永久删除2D脚本时使用
|
||||
|
||||
**Section sources**
|
||||
- [SptManager.h](file://h\SptManager.h#L45)
|
||||
- [SptManager.cpp](file://cpp\Managers\SptManager.cpp#L505-L546)
|
||||
|
||||
## TdManager API
|
||||
|
||||
TdManager类负责管理测试数据（Testing Data）的导入、导出和显示，处理不同类型的测量数据。
|
||||
|
||||
### 公共方法
|
||||
|
||||
#### ShowTdListByTz
|
||||
根据测区显示测试数据列表。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
bool ShowTdListByTz(DWORD dwTzHandle, CListCtrl& tdList)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwTzHandle`: 测区句柄
|
||||
- `tdList`: 引用CListCtrl控件，用于显示测试数据列表
|
||||
|
||||
**返回值**
|
||||
- 操作成功返回true，失败返回false
|
||||
|
||||
**异常情况**
|
||||
- 捕获_com_error异常并显示错误消息
|
||||
|
||||
**使用场景**
|
||||
- 在UI中显示特定测区下的所有测试数据列表
|
||||
|
||||
**Section sources**
|
||||
- [TdManager.h](file://h\TdManager.h#L84)
|
||||
- [TdManager.cpp](file://cpp\Managers\TdManager.cpp#L409-L682)
|
||||
|
||||
#### ShowTdListByProject
|
||||
根据项目显示测试数据列表。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
bool ShowTdListByProject(DWORD dwProHandle, CListCtrl& tdList)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwProHandle`: 项目句柄
|
||||
- `tdList`: 引用CListCtrl控件，用于显示测试数据列表
|
||||
|
||||
**返回值**
|
||||
- 操作成功返回true，失败返回false
|
||||
|
||||
**异常情况**
|
||||
- 捕获_com_error异常并显示错误消息
|
||||
|
||||
**使用场景**
|
||||
- 在UI中显示特定项目下的所有测试数据列表
|
||||
|
||||
**Section sources**
|
||||
- [TdManager.h](file://h\TdManager.h#L89)
|
||||
- [TdManager.cpp](file://cpp\Managers\TdManager.cpp#L81-L406)
|
||||
|
||||
#### Upload2DTdFromDev
|
||||
从设备上载2D测试数据。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
BOOL Upload2DTdFromDev(CString szPrCN, CString szTzCN, CString szTdCN, CString strSubTdCN, CDevice* const pDev)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `szPrCN`: 项目编号
|
||||
- `szTzCN`: 测区编号
|
||||
- `szTdCN`: 测试数据编号
|
||||
- `strSubTdCN`: 子任务编号列表
|
||||
- `pDev`: 指向源设备的常量指针
|
||||
|
||||
**返回值**
|
||||
- 成功返回TRUE，失败返回FALSE
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常处理
|
||||
|
||||
**使用场景**
|
||||
- 当需要从设备上载2D测量数据到数据库时使用
|
||||
|
||||
**Section sources**
|
||||
- [TdManager.h](file://h\TdManager.h#L57)
|
||||
- [TdManager.cpp](file://cpp\Managers\TdManager.cpp#L81-L406)
|
||||
|
||||
#### Import2DTdConToDB
|
||||
将2D数据导入数据库。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
BOOL Import2DTdConToDB(DWORD dwTdID, CString szDatFile, CDevice* const pDev, int* pTSN=NULL)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwTdID`: 测试数据ID
|
||||
- `szDatFile`: DAT文件路径
|
||||
- `pDev`: 指向设备的常量指针
|
||||
- `pTSN`: 可选参数，指定起始测点号
|
||||
|
||||
**返回值**
|
||||
- 成功返回TRUE，失败返回FALSE
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常处理
|
||||
|
||||
**使用场景**
|
||||
- 当需要将设备上的2D测量结果导入数据库进行存储和分析时使用
|
||||
|
||||
**Section sources**
|
||||
- [TdManager.h](file://h\TdManager.h#L47)
|
||||
- [TdManager.cpp](file://cpp\Managers\TdManager.cpp#L81-L406)
|
||||
|
||||
#### DeleteRsp2DTd
|
||||
删除2D电阻率数据。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
void DeleteRsp2DTd(DWORD dwID)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwID`: 要删除数据的ID
|
||||
|
||||
**返回值**
|
||||
- 无
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常处理
|
||||
|
||||
**使用场景**
|
||||
- 当需要从系统中删除2D电阻率测量数据时使用
|
||||
|
||||
**Section sources**
|
||||
- [TdManager.h](file://h\TdManager.h#L79)
|
||||
- [TdManager.cpp](file://cpp\Managers\TdManager.cpp#L81-L406)
|
||||
|
||||
#### GetTestingData
|
||||
获取测试数据对象。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
CTestingData* GetTestingData(DWORD dwHandle)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `dwHandle`: 测试数据句柄
|
||||
|
||||
**返回值**
|
||||
- 成功时返回指向CTestingData对象的指针，失败时返回NULL
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常抛出
|
||||
|
||||
**使用场景**
|
||||
- 在测试数据操作过程中，通过句柄获取数据对象进行操作
|
||||
|
||||
**Section sources**
|
||||
- [TdManager.h](file://h\TdManager.h#L82)
|
||||
- [TdManager.cpp](file://cpp\Managers\TdManager.cpp#L81-L406)
|
||||
|
||||
## IOManager API
|
||||
|
||||
IOManager类负责数据的导入和导出功能，支持将项目数据导出为Access数据库文件，以及从外部文件导入数据。
|
||||
|
||||
### 公共方法
|
||||
|
||||
#### Export
|
||||
导出数据到外部文件。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
UINT Export()
|
||||
```
|
||||
|
||||
**参数**
|
||||
- 无
|
||||
|
||||
**返回值**
|
||||
- APP_SUCCESS: 导出成功
|
||||
- APP_CANCLE: 用户取消操作
|
||||
- APP_FAIL: 导出失败
|
||||
|
||||
**异常情况**
|
||||
- 在数据库操作中捕获_com_error异常，操作失败时回滚事务并删除临时文件
|
||||
|
||||
**使用场景**
|
||||
- 当用户需要将项目数据导出为外部文件进行备份或共享时使用
|
||||
|
||||
**Section sources**
|
||||
- [IOManager.h](file://h\IOManager.h#L20)
|
||||
- [IOManager.cpp](file://cpp\Managers\IOManager.cpp#L35-L98)
|
||||
|
||||
#### Import
|
||||
从外部文件导入数据。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
UINT Import()
|
||||
```
|
||||
|
||||
**参数**
|
||||
- 无
|
||||
|
||||
**返回值**
|
||||
- APP_SUCCESS: 导入成功
|
||||
- APP_CANCLE: 用户取消操作或文件错误
|
||||
- APP_FAIL: 导入失败
|
||||
|
||||
**异常情况**
|
||||
- 捕获_com_error异常处理数据库连接错误
|
||||
- 验证导入文件的版本兼容性
|
||||
|
||||
**使用场景**
|
||||
- 当用户需要从外部文件导入项目数据时使用
|
||||
|
||||
**Section sources**
|
||||
- [IOManager.h](file://h\IOManager.h#L19)
|
||||
- [IOManager.cpp](file://cpp\Managers\IOManager.cpp#L101-L203)
|
||||
|
||||
#### CreateExpDatabase
|
||||
创建导出数据库。
|
||||
|
||||
**方法签名**
|
||||
```cpp
|
||||
_ConnectionPtr CreateExpDatabase(CString szFileName)
|
||||
```
|
||||
|
||||
**参数**
|
||||
- `szFileName`: 导出文件的路径和名称
|
||||
|
||||
**返回值**
|
||||
- 成功时返回指向_ConnectionPtr的指针，失败时返回NULL
|
||||
|
||||
**异常情况**
|
||||
- 无显式异常处理
|
||||
|
||||
**使用场景**
|
||||
- 在导出操作中，创建新的Access数据库文件作为导出目标
|
||||
|
||||
**Section sources**
|
||||
- [IOManager.h](file://h\IOManager.h#L45)
|
||||
- [IOManager.cpp](file://cpp\Managers\IOManager.cpp#L206-L655)
|
||||
|
||||
## API调用链与依赖关系
|
||||
|
||||
各管理器类之间存在明确的调用链和依赖关系，形成了完整的数据管理流程。
|
||||
|
||||
### 设备-项目-脚本-数据调用链
|
||||
```mermaid
|
||||
graph TD
|
||||
A[DevManager] --> |管理| B[设备]
|
||||
B --> |关联| C[ProManager]
|
||||
C --> |管理| D[项目]
|
||||
D --> |包含| E[测区]
|
||||
E --> |关联| F[SptManager]
|
||||
F --> |管理| G[脚本]
|
||||
G --> |执行| H[TdManager]
|
||||
H --> |管理| I[测试数据]
|
||||
I --> |存储| J[IOManager]
|
||||
J --> |导出/导入| K[外部文件]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [DevManager.h](file://h\DevManager.h)
|
||||
- [ProManager.h](file://h\ProManager.h)
|
||||
- [SptManager.h](file://h\SptManager.h)
|
||||
- [TdManager.h](file://h\TdManager.h)
|
||||
- [IOManager.h](file://h\IOManager.h)
|
||||
|
||||
### 核心依赖关系
|
||||
1. **DevManager → ProManager**: 设备管理器为项目管理器提供设备信息，项目同步需要设备连接
|
||||
2. **ProManager → SptManager**: 项目管理器在创建项目时可能需要调用脚本管理器创建默认脚本
|
||||
3. **SptManager → TdManager**: 脚本管理器在执行测量任务时生成测试数据，由测试数据管理器管理
|
||||
4. **TdManager → IOManager**: 测试数据管理器依赖IO管理器实现数据的导入导出功能
|
||||
|
||||
### 初始化依赖
|
||||
系统启动时，各管理器按特定顺序初始化：
|
||||
1. DevManager首先初始化，建立设备连接
|
||||
2. ProManager其次初始化，加载项目结构
|
||||
3. SptManager随后初始化，准备脚本管理
|
||||
4. TdManager最后初始化，准备数据管理
|
||||
5. IOManager在需要时初始化，处理数据交换
|
||||
|
||||
## 线程安全性说明
|
||||
|
||||
### DevManager
|
||||
- **线程安全性**: 非线程安全
|
||||
- **说明**: DevManager的公共方法未实现线程同步机制。在多线程环境中使用时，需要外部同步控制，避免多个线程同时访问同一设备对象。
|
||||
|
||||
### ProManager
|
||||
- **线程安全性**: 部分线程安全
|
||||
- **说明**: 数据库操作使用事务保护，但在UI交互部分（如对话框显示）存在潜在的线程安全问题。建议在主线程中调用UI相关方法。
|
||||
|
||||
### SptManager
|
||||
- **线程安全性**: 非线程安全
|
||||
- **说明**: 脚本创建和管理操作未实现线程同步。特别是Create2DSConInDB和CreateCESConInDB方法涉及复杂的UI交互和数据库操作，应在单线程环境中使用。
|
||||
|
||||
### TdManager
|
||||
- **线程安全性**: 部分线程安全
|
||||
- **说明**: 数据库操作使用事务保护，但文件操作和UI更新部分存在线程安全风险。ShowTdListByTz等显示方法应在UI线程中调用。
|
||||
|
||||
### IOManager
|
||||
- **线程安全性**: 非线程安全
|
||||
- **说明**: 导入导出操作涉及文件系统和数据库的复杂交互，未实现线程同步。应避免在多线程环境中同时执行多个导入导出操作。
|
||||
|
||||
### 通用线程使用建议
|
||||
1. **UI相关操作**: 所有涉及UI显示的方法（如ShowProList、ShowTzList）必须在主线程中调用
|
||||
2. **数据库操作**: 虽然使用事务保护，但建议对同一管理器实例的操作进行同步
|
||||
3. **设备通信**: 与设备的通信操作应序列化执行，避免多个线程同时访问同一设备
|
||||
4. **数据一致性**: 在多线程环境中，应使用锁机制保护共享数据，确保数据一致性
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 创建新项目并同步到设备
|
||||
```cpp
|
||||
// 1. 创建项目
|
||||
DWORD dwProjectID;
|
||||
UINT result = theApp.m_pProManager->CreateProjectInDB(dwProjectID);
|
||||
if (result == APP_SUCCESS) {
|
||||
// 2. 获取目标设备
|
||||
CDevice* pDevice = theApp.m_pDevManager->GetDeviceByID(deviceID);
|
||||
if (pDevice != NULL) {
|
||||
// 3. 在设备中创建项目
|
||||
result = theApp.m_pProManager->CreateProjectInDev(dwProjectID, pDevice);
|
||||
if (result == APP_SUCCESS) {
|
||||
// 4. 在设备中创建默认测区
|
||||
result = theApp.m_pProManager->CreateDefaultTzInDev(dwProjectID, pDevice);
|
||||
if (result == APP_SUCCESS) {
|
||||
// 项目创建和同步完成
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 创建2D测量脚本并上传到设备
|
||||
```cpp
|
||||
// 1. 创建2D脚本
|
||||
DWORD dwScriptID;
|
||||
UINT result = theApp.m_pSptManager->Create2DSConInDB(dwScriptID);
|
||||
if (result == APP_SUCCESS) {
|
||||
// 2. 获取目标设备
|
||||
CDevice* pDevice = theApp.m_pDevManager->GetDeviceByID(deviceID);
|
||||
if (pDevice != NULL) {
|
||||
// 3. 将脚本上传到设备
|
||||
result = theApp.m_pSptManager->PutScriptToDev(dwScriptID, pDevice);
|
||||
if (result == APP_SUCCESS) {
|
||||
// 脚本创建和上传完成
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 从设备上载2D测量数据
|
||||
```cpp
|
||||
// 1. 获取设备
|
||||
CDevice* pDevice = theApp.m_pDevManager->GetDeviceByID(deviceID);
|
||||
if (pDevice != NULL) {
|
||||
// 2. 从设备上载2D数据
|
||||
BOOL success = theApp.m_pTdManager->Upload2DTdFromDev(
|
||||
projectCN, zoneCN, dataCN, _T(""), pDevice);
|
||||
if (success) {
|
||||
// 3. 数据导入数据库
|
||||
DWORD dwTdID = theApp.m_pTdManager->ImportTdHeadToDB(
|
||||
zoneID, headFileName, pDevice);
|
||||
if (dwTdID != 0) {
|
||||
// 4. 导入详细数据
|
||||
theApp.m_pTdManager->Import2DTdConToDB(
|
||||
dwTdID, datFileName, pDevice);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 导出项目数据
|
||||
```cpp
|
||||
// 1. 创建IOManager实例
|
||||
CIOManager ioManager(theApp.m_pConnection, theApp.m_pCatalog);
|
||||
// 2. 执行导出操作
|
||||
UINT result = ioManager.Export();
|
||||
if (result == APP_SUCCESS) {
|
||||
// 导出成功
|
||||
} else if (result == APP_CANCLE) {
|
||||
// 用户取消
|
||||
} else {
|
||||
// 导出失败
|
||||
}
|
||||
```
|
||||
|
||||
### 显示项目下的测区列表
|
||||
```cpp
|
||||
// 1. 获取项目句柄
|
||||
DWORD dwProHandle = m_handleProcessor.GenerateHandle(projectID, PZ_STYLE_PRO);
|
||||
// 2. 获取列表控件
|
||||
CListCtrl& tzList = m_dlg.m_tzList;
|
||||
// 3. 显示测区列表
|
||||
bool success = theApp.m_pProManager->ShowTzList(dwProHandle, tzList);
|
||||
if (success) {
|
||||
// 列表显示成功
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,182 @@
|
||||
# 数据导入导出API
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [IOManager.cpp](file://cpp/Managers/IOManager.cpp)
|
||||
- [IOManager.h](file://h/IOManager.h)
|
||||
- [OperTxtFile.cpp](file://cpp/Tools/OperTxtFile.cpp)
|
||||
- [OperUrfFile.cpp](file://cpp/Tools/OperUrfFile.cpp)
|
||||
- [excel.cpp](file://cpp/Tools/excel.cpp)
|
||||
- [ioexpdlg.cpp](file://cpp/Views/ioexpdlg.cpp)
|
||||
- [Constant.h](file://h/Constant.h)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
Geomative Studio是一款专业的地球物理数据处理软件，其数据导入导出API是系统的核心功能之一，负责在内部数据库与外部文件格式之间进行数据交换。该API主要由`IOManager`类实现，支持多种数据格式，包括专有的URF格式、文本文件（TXT）、Excel电子表格以及Access数据库（ACCDB）。这些功能使得用户能够方便地将现场采集的测试数据导出为标准格式以供进一步分析，或从历史存档文件中导入数据进行回溯研究。API的设计注重数据的完整性和一致性，通过事务处理确保导出过程的原子性，并在导入时进行严格的格式验证。
|
||||
|
||||
## 项目结构
|
||||
Geomative Studio的项目结构清晰地划分了不同功能模块。与数据导入导出功能相关的代码主要位于`cpp/Tools`和`cpp/Managers`目录下。`IOManager`类作为高层管理器，协调整个导入导出流程，而具体的文件格式读写操作则由`OperTxtFile`、`OperUrfFile`等专用工具类实现。UI相关的对话框逻辑（如`ioexpdlg`）位于`cpp/Views`目录，负责与用户交互并收集导出参数。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "核心管理器"
|
||||
IOManager["IOManager (cpp/Managers/IOManager.cpp)"]
|
||||
end
|
||||
subgraph "文件操作工具"
|
||||
OperTxtFile["OperTxtFile (cpp/Tools/OperTxtFile.cpp)"]
|
||||
OperUrfFile["OperUrfFile (cpp/Tools/OperUrfFile.cpp)"]
|
||||
Excel["Excel (cpp/Tools/excel.cpp)"]
|
||||
end
|
||||
subgraph "用户界面"
|
||||
IOExpDlg["IOExpDlg (cpp/Views/ioexpdlg.cpp)"]
|
||||
end
|
||||
IOManager --> OperTxtFile
|
||||
IOManager --> OperUrfFile
|
||||
IOManager --> Excel
|
||||
IOExpDlg --> IOManager
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [IOManager.cpp](file://cpp/Managers/IOManager.cpp#L23)
|
||||
- [OperTxtFile.cpp](file://cpp/Tools/OperTxtFile.cpp#L19)
|
||||
- [OperUrfFile.cpp](file://cpp/Tools/OperUrfFile.cpp#L19)
|
||||
- [excel.cpp](file://cpp/Tools/excel.cpp#L19)
|
||||
- [ioexpdlg.cpp](file://cpp/Views/ioexpdlg.cpp#L20)
|
||||
|
||||
**本节来源**
|
||||
- [IOManager.cpp](file://cpp/Managers/IOManager.cpp#L1)
|
||||
- [OperTxtFile.cpp](file://cpp/Tools/OperTxtFile.cpp#L1)
|
||||
- [OperUrfFile.cpp](file://cpp/Tools/OperUrfFile.cpp#L1)
|
||||
- [excel.cpp](file://cpp/Tools/excel.cpp#L1)
|
||||
- [ioexpdlg.cpp](file://cpp/Views/ioexpdlg.cpp#L1)
|
||||
|
||||
## 核心组件
|
||||
`IOManager`类是数据导入导出功能的核心，它封装了与数据库和文件系统交互的复杂性。该类提供了`Export`和`Import`两个主要的公共接口。`Export`方法启动一个对话框，允许用户选择要导出的项目、测区和测点数据，然后创建一个新的Access数据库文件，并将选中的数据按预定义的表结构写入其中。`Import`方法则相反，它打开一个现有的ACCDB文件，验证其版本和格式，然后将其中的数据读取并安全地导入到当前的数据库中。`IOManager`依赖于`HandleProcessor`和`StateProcessor`等辅助类来管理数据对象的句柄和状态。
|
||||
|
||||
**本节来源**
|
||||
- [IOManager.cpp](file://cpp/Managers/IOManager.cpp#L35)
|
||||
- [IOManager.h](file://h/IOManager.h#L19)
|
||||
|
||||
## 架构概述
|
||||
数据导入导出API的架构采用分层设计。顶层是UI层（`ioexpdlg`），负责用户交互。中间是业务逻辑层（`IOManager`），它定义了导出和导入的主流程。底层是数据访问和文件操作层，由一系列专用的工具类构成。这种分层结构使得代码职责分明，易于维护和扩展。例如，添加对新文件格式的支持，只需实现一个新的工具类并将其集成到`IOManager`中，而无需修改核心逻辑。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[用户界面层<br>ioexpdlg] --> B[业务逻辑层<br>IOManager]
|
||||
B --> C[数据访问层<br>ADO/OLEDB]
|
||||
B --> D[文件操作层<br>OperTxtFile<br>OperUrfFile<br>Excel]
|
||||
C --> E[(数据库)]
|
||||
D --> F[(外部文件)]
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [IOManager.cpp](file://cpp/Managers/IOManager.cpp#L23)
|
||||
- [ioexpdlg.cpp](file://cpp/Views/ioexpdlg.cpp#L20)
|
||||
- [OperTxtFile.cpp](file://cpp/Tools/OperTxtFile.cpp#L19)
|
||||
- [OperUrfFile.cpp](file://cpp/Tools/OperUrfFile.cpp#L19)
|
||||
- [excel.cpp](file://cpp/Tools/excel.cpp#L19)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### IOManager类分析
|
||||
`IOManager`类是整个API的控制中心。其`Export`方法首先创建一个`CIOExpDlg`对话框，让用户选择要导出的数据项。一旦用户确认，`IOManager`会调用`CreateExpDatabase`方法创建一个新的ACCDB文件，并定义一系列数据表（如`project`, `tz`, `td`, `rspcon`等）来存储结构化数据。随后，它遍历用户选择的数据，并通过`ExportDataToAccdbFile`等私有方法将数据逐条写入新数据库。整个过程在一个数据库事务中进行，确保了数据的一致性。
|
||||
|
||||
#### IOManager类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CIOManager {
|
||||
+UINT Export()
|
||||
+UINT Import()
|
||||
-_ConnectionPtr CreateExpDatabase(CString szFileName)
|
||||
-void ExportDataToAccdbFile(_ConnectionPtr pExpConnection, CTreeCtrl& dmsTree)
|
||||
-void ImportProjectToDB(_ConnectionPtr pImpConnection)
|
||||
+CHandleProcessor m_handleProcessor
|
||||
+CStateProcessor m_stateProcessor
|
||||
-_ConnectionPtr m_pConnection
|
||||
-ADOX : : _CatalogPtr m_pCatalog
|
||||
}
|
||||
class CHandleProcessor {
|
||||
+DWORD GenerateHandle(DWORD dwID, UINT uStyle)
|
||||
+DWORD GetIDFromHandle(DWORD dwHandle)
|
||||
+UINT GetStyleFromHandle(DWORD dwHandle)
|
||||
}
|
||||
class CStateProcessor {
|
||||
+UINT ChangeToImageState(UINT uState)
|
||||
}
|
||||
CIOManager --> CHandleProcessor : "使用"
|
||||
CIOManager --> CStateProcessor : "使用"
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [IOManager.h](file://h/IOManager.h#L15)
|
||||
- [IOManager.cpp](file://cpp/Managers/IOManager.cpp#L23)
|
||||
- [Constant.h](file://h/Constant.h#L83)
|
||||
|
||||
### 文件格式解析器分析
|
||||
|
||||
#### TXT文件解析器
|
||||
`OperTxtFile`类负责处理TXT格式的读写。它提供了一个可配置的参数宽度（`m_uiParamWidth`），在写入文件时，每个字段都会被填充到指定的宽度，不足部分用空格补齐，从而保证了文本文件的列对齐。该类通过标准的C运行时库函数（如`fopen`, `fwrite`）进行文件操作，并在写入后调用`fflush`确保数据立即写入磁盘。错误处理机制完善，任何文件操作失败都会通过消息框向用户报告。
|
||||
|
||||
**本节来源**
|
||||
- [OperTxtFile.cpp](file://cpp/Tools/OperTxtFile.cpp#L19)
|
||||
|
||||
#### URF文件解析器
|
||||
`OperUrfFile`类专门用于处理Geomative Studio的专有URF（Universal Resistivity data File）格式。URF文件是一种文本格式，用于存储电阻率数据，其头部包含注释和单位信息（如"Unit: meters"）。该类提供了多种方法来根据不同的电极阵列（如温纳-施伦贝格尔阵列、交叉孔阵列）生成电极坐标信息。例如，`WriteElecByWenSch`方法会根据电极数量和间距生成一条直线上电极的坐标。URF文件的生成是流式的，直接写入文件，适合处理大型数据集。
|
||||
|
||||
**本节来源**
|
||||
- [OperUrfFile.cpp](file://cpp/Tools/OperUrfFile.cpp#L19)
|
||||
|
||||
#### Excel文件解析器
|
||||
`excel.cpp`文件包含由MFC ClassWizard生成的Excel应用程序包装类。它通过COM接口与Microsoft Excel进行交互，允许程序创建、读取和修改Excel工作簿。`_Application`类提供了对Excel应用程序对象的访问，可以用来打开工作簿、获取工作表、操作单元格范围等。虽然在当前的`IOManager`中未直接使用此功能进行导出，但它为未来实现Excel格式的直接导出提供了基础能力。
|
||||
|
||||
**本节来源**
|
||||
- [excel.cpp](file://cpp/Tools/excel.cpp#L1)
|
||||
|
||||
## 依赖分析
|
||||
`IOManager`类与多个组件存在依赖关系。它直接依赖于`ADOX::_CatalogPtr`和`_ConnectionPtr`来操作Access数据库，这要求系统安装了相应的OLEDB驱动。在文件操作层面，它通过包含头文件的方式依赖于`OperTxtFile`、`OperUrfFile`等工具类。UI层的`CIOExpDlg`对话框依赖于`IOManager`来执行实际的导出任务。这些依赖关系清晰地定义了各模块的职责边界。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
IOManager --> ADOX["ADOX/_ConnectionPtr<br>(数据库访问)"]
|
||||
IOManager --> OperTxtFile
|
||||
IOManager --> OperUrfFile
|
||||
IOExpDlg --> IOManager
|
||||
IOManager --> HandleProcessor
|
||||
IOManager --> StateProcessor
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [IOManager.h](file://h/IOManager.h#L21)
|
||||
- [IOManager.cpp](file://cpp/Managers/IOManager.cpp#L23)
|
||||
- [OperTxtFile.cpp](file://cpp/Tools/OperTxtFile.cpp#L19)
|
||||
- [OperUrfFile.cpp](file://cpp/Tools/OperUrfFile.cpp#L19)
|
||||
- [ioexpdlg.cpp](file://cpp/Views/ioexpdlg.cpp#L20)
|
||||
|
||||
**本节来源**
|
||||
- [IOManager.h](file://h/IOManager.h#L21)
|
||||
- [IOManager.cpp](file://cpp/Managers/IOManager.cpp#L23)
|
||||
|
||||
## 性能考虑
|
||||
对于大文件处理，API的设计考虑了内存占用问题。URF和TXT格式的导出采用流式处理，数据被逐块写入文件，而不是一次性加载到内存中，这有效避免了内存溢出的风险。数据库导出虽然会将数据加载到内存中进行处理，但由于使用了数据库事务和批处理，性能相对可控。然而，对于极其庞大的数据集，建议分批次导出。错误恢复机制主要体现在数据库事务上：如果在导出过程中发生错误，事务会回滚，已创建的数据库文件会被删除，从而保证了源数据的完整性。
|
||||
|
||||
## 故障排除指南
|
||||
常见的导入导出问题包括文件路径无效、磁盘空间不足、数据库文件被其他程序占用或格式不兼容。当出现错误时，系统会通过`AfxMessageBox`或`MessageBoxEx`弹出详细的错误信息，通常包含错误代码和具体的操作（如"打开文件失败"、"写文件错误"）。用户应首先检查文件路径和权限，然后根据错误代码查阅系统日志（位于`LOG`目录下）以获取更深入的诊断信息。对于URF文件，需要确保其头部的单位声明正确，否则可能导致坐标系统不一致。
|
||||
|
||||
**本节来源**
|
||||
- [OperTxtFile.cpp](file://cpp/Tools/OperTxtFile.cpp#L73)
|
||||
- [OperUrfFile.cpp](file://cpp/Tools/OperUrfFile.cpp#L36)
|
||||
- [IOManager.cpp](file://cpp/Managers/IOManager.cpp#L151)
|
||||
|
||||
## 结论
|
||||
Geomative Studio的数据导入导出API提供了一套强大而灵活的机制，用于在专有数据库和多种外部格式之间交换数据。通过`IOManager`类的统一管理，结合专用的文件操作工具，系统能够高效、安全地处理TXT、URF和ACCDB等格式。API的设计体现了清晰的分层和模块化思想，为未来的功能扩展（如直接支持CSV或Excel导出）奠定了良好的基础。尽管当前的实现已经很成熟，但在处理超大规模数据集时，仍可进一步优化内存使用和提供更细粒度的进度反馈。
|
||||
@@ -0,0 +1,256 @@
|
||||
# 测试数据API
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [TdManager.cpp](file://cpp/Managers/TdManager.cpp)
|
||||
- [TdManager.h](file://h/TdManager.h)
|
||||
- [TdRecord.cpp](file://cpp/ProblemZone/TdRecord.cpp)
|
||||
- [TdRecord.h](file://h/TdRecord.h)
|
||||
- [TdChannel.cpp](file://cpp/ProblemZone/TdChannel.cpp)
|
||||
- [TdChannel.h](file://h/TdChannel.h)
|
||||
- [Ipsp2DTdRecord.cpp](file://cpp/ProblemZone/Ipsp2DTdRecord.cpp)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文档旨在为Geomative Studio项目中的测试数据API提供权威参考，重点聚焦于TdManager类对采集数据的存储、查询和处理能力。文档详细描述了数据记录（TdRecord）的结构设计、时间序列组织方式和索引机制。同时，文档化了所有数据访问方法的调用规范，包括实时数据流接收、历史数据检索、数据分页和过滤条件设置。此外，还提供了示例代码，展示如何订阅测量数据流、执行数据聚合分析以及导出原始记录。最后，文档解释了数据缓存策略、内存管理机制和大数据量场景下的性能调优方案。
|
||||
|
||||
## 项目结构
|
||||
Geomative Studio项目的测试数据管理模块主要由以下几个核心组件构成：TdManager负责整体数据管理，TdChannel处理通道级别的数据操作，TdRecord管理具体的数据记录。这些组件协同工作，实现了从数据采集、存储到查询和分析的完整流程。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据管理层"
|
||||
TdManager[TdManager]
|
||||
TdChannel[TdChannel]
|
||||
TdRecord[TdRecord]
|
||||
end
|
||||
subgraph "数据存储"
|
||||
Database[(数据库)]
|
||||
end
|
||||
TdManager --> TdChannel
|
||||
TdChannel --> TdRecord
|
||||
TdRecord --> Database
|
||||
TdManager --> Database
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TdManager.h](file://h/TdManager.h)
|
||||
- [TdChannel.h](file://h/TdChannel.h)
|
||||
- [TdRecord.h](file://h/TdRecord.h)
|
||||
|
||||
**章节来源**
|
||||
- [TdManager.cpp](file://cpp/Managers/TdManager.cpp#L1-L800)
|
||||
- [TdChannel.cpp](file://cpp/ProblemZone/TdChannel.cpp#L1-L800)
|
||||
|
||||
## 核心组件
|
||||
测试数据API的核心组件包括TdManager、TdChannel和TdRecord。TdManager作为顶层管理器，负责协调所有数据操作；TdChannel作为中间层，处理特定通道的数据；TdRecord作为底层数据单元，存储具体的测量数据。
|
||||
|
||||
**章节来源**
|
||||
- [TdManager.h](file://h/TdManager.h#L1-L109)
|
||||
- [TdChannel.h](file://h/TdChannel.h#L1-L64)
|
||||
- [TdRecord.h](file://h/TdRecord.h#L1-L47)
|
||||
|
||||
## 架构概述
|
||||
测试数据API采用分层架构设计，从上到下分别为管理层、通道层和记录层。这种设计使得系统具有良好的模块化和可扩展性。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CTdManager {
|
||||
+ShowTdListByTz()
|
||||
+ShowTdListByProject()
|
||||
+ImportTdHeadToDB()
|
||||
+Upload2DTdFromDev()
|
||||
-m_tdLinkList : CLinkList<CTestingData*>
|
||||
-m_pConnection : _ConnectionPtr
|
||||
}
|
||||
class CTdChannel {
|
||||
+Load2DScriptFromDB()
|
||||
+LoadRsp2DTdData()
|
||||
+SaveRsp2DTdData()
|
||||
-m_tdRecArray : CPtrArray
|
||||
-m_pConnection : _ConnectionPtr
|
||||
}
|
||||
class CTdRecord {
|
||||
+LoadOrgData()
|
||||
+DisplayRawDataSplines()
|
||||
-m_saVRawData : CStringArray
|
||||
-m_saIRawData : CStringArray
|
||||
-m_pConnection : _ConnectionPtr
|
||||
}
|
||||
CTdManager --> CTdChannel : "管理"
|
||||
CTdChannel --> CTdRecord : "包含"
|
||||
CTdRecord --> Database : "存储"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TdManager.h](file://h/TdManager.h#L1-L109)
|
||||
- [TdChannel.h](file://h/TdChannel.h#L1-L64)
|
||||
- [TdRecord.h](file://h/TdRecord.h#L1-L47)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### TdManager分析
|
||||
TdManager类是测试数据管理的核心，负责协调所有数据操作。它提供了多种方法来显示、导入和上传测试数据。
|
||||
|
||||
#### 类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CTdManager {
|
||||
+ShowTdListByTz()
|
||||
+ShowTdListByProject()
|
||||
+ImportTdHeadToDB()
|
||||
+Upload2DTdFromDev()
|
||||
-m_tdLinkList : CLinkList<CTestingData*>
|
||||
-m_pConnection : _ConnectionPtr
|
||||
}
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TdManager.h](file://h/TdManager.h#L1-L109)
|
||||
|
||||
#### 方法调用序列
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant TdManager as "TdManager"
|
||||
participant Database as "数据库"
|
||||
Client->>TdManager : ShowTdListByTz()
|
||||
TdManager->>Database : 查询td表
|
||||
Database-->>TdManager : 返回数据列表
|
||||
TdManager->>Client : 显示测试数据列表
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TdManager.cpp](file://cpp/Managers/TdManager.cpp#L409-L683)
|
||||
|
||||
**章节来源**
|
||||
- [TdManager.cpp](file://cpp/Managers/TdManager.cpp#L1-L800)
|
||||
- [TdManager.h](file://h/TdManager.h#L1-L109)
|
||||
|
||||
### TdRecord分析
|
||||
TdRecord类负责管理具体的数据记录，包括原始数据的加载和显示。
|
||||
|
||||
#### 类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CTdRecord {
|
||||
+LoadOrgData()
|
||||
+DisplayRawDataSplines()
|
||||
-m_saVRawData : CStringArray
|
||||
-m_saIRawData : CStringArray
|
||||
-m_pConnection : _ConnectionPtr
|
||||
}
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TdRecord.h](file://h/TdRecord.h#L1-L47)
|
||||
|
||||
#### 数据加载流程
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始]) --> LoadData["加载原始数据"]
|
||||
LoadData --> ParseData["解析数据字符串"]
|
||||
ParseData --> ConvertData["转换原始数据"]
|
||||
ConvertData --> StoreData["存储到数组"]
|
||||
StoreData --> End([结束])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TdRecord.cpp](file://cpp/ProblemZone/TdRecord.cpp#L1-L325)
|
||||
|
||||
**章节来源**
|
||||
- [TdRecord.cpp](file://cpp/ProblemZone/TdRecord.cpp#L1-L325)
|
||||
- [TdRecord.h](file://h/TdRecord.h#L1-L47)
|
||||
|
||||
### TdChannel分析
|
||||
TdChannel类处理通道级别的数据操作，包括脚本加载、数据加载和保存。
|
||||
|
||||
#### 类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CTdChannel {
|
||||
+Load2DScriptFromDB()
|
||||
+LoadRsp2DTdData()
|
||||
+SaveRsp2DTdData()
|
||||
-m_tdRecArray : CPtrArray
|
||||
-m_pConnection : _ConnectionPtr
|
||||
}
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TdChannel.h](file://h/TdChannel.h#L1-L64)
|
||||
|
||||
#### 数据加载序列
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant TdChannel as "TdChannel"
|
||||
participant Database as "数据库"
|
||||
Client->>TdChannel : LoadRsp2DTdData()
|
||||
TdChannel->>Database : 查询td2dcon表
|
||||
Database-->>TdChannel : 返回数据记录
|
||||
TdChannel->>TdChannel : 创建CRsp2DTdRecord对象
|
||||
TdChannel->>Client : 返回数据记录数组
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TdChannel.cpp](file://cpp/ProblemZone/TdChannel.cpp#L515-L585)
|
||||
|
||||
**章节来源**
|
||||
- [TdChannel.cpp](file://cpp/ProblemZone/TdChannel.cpp#L1-L800)
|
||||
- [TdChannel.h](file://h/TdChannel.h#L1-L64)
|
||||
|
||||
## 依赖分析
|
||||
测试数据API的组件之间存在明确的依赖关系。TdManager依赖于TdChannel，TdChannel依赖于TdRecord，形成了一条清晰的依赖链。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
TdManager --> TdChannel
|
||||
TdChannel --> TdRecord
|
||||
TdRecord --> Database
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TdManager.h](file://h/TdManager.h)
|
||||
- [TdChannel.h](file://h/TdChannel.h)
|
||||
- [TdRecord.h](file://h/TdRecord.h)
|
||||
|
||||
**章节来源**
|
||||
- [TdManager.cpp](file://cpp/Managers/TdManager.cpp)
|
||||
- [TdChannel.cpp](file://cpp/ProblemZone/TdChannel.cpp)
|
||||
- [TdRecord.cpp](file://cpp/ProblemZone/TdRecord.cpp)
|
||||
|
||||
## 性能考虑
|
||||
在处理大数据量时，测试数据API采用了多种性能优化策略：
|
||||
1. 使用连接池管理数据库连接
|
||||
2. 采用分页查询减少内存占用
|
||||
3. 实现数据缓存机制
|
||||
4. 优化SQL查询语句
|
||||
|
||||
这些策略确保了系统在处理大规模测试数据时仍能保持良好的性能表现。
|
||||
|
||||
## 故障排除指南
|
||||
当遇到数据加载或查询问题时，可以按照以下步骤进行排查：
|
||||
1. 检查数据库连接是否正常
|
||||
2. 验证SQL查询语句是否正确
|
||||
3. 确认数据表结构是否匹配
|
||||
4. 检查内存使用情况
|
||||
|
||||
**章节来源**
|
||||
- [TdManager.cpp](file://cpp/Managers/TdManager.cpp#L148-L152)
|
||||
- [TdChannel.cpp](file://cpp/ProblemZone/TdChannel.cpp#L359-L363)
|
||||
- [TdRecord.cpp](file://cpp/ProblemZone/TdRecord.cpp#L115-L119)
|
||||
|
||||
## 结论
|
||||
本文档详细介绍了Geomative Studio项目中测试数据API的设计和实现。通过分层架构和模块化设计，系统实现了高效的数据管理和处理能力。未来可以进一步优化数据缓存策略和查询性能，以应对更大规模的数据处理需求。
|
||||
@@ -0,0 +1,271 @@
|
||||
# 脚本管理API
|
||||
|
||||
<cite>
|
||||
**本文档引用文件**
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp)
|
||||
- [SptManager.h](file://h/SptManager.h)
|
||||
- [Script.h](file://h/Script.h)
|
||||
- [Script2D.h](file://h/Script2D.h)
|
||||
- [Script3D.h](file://h/Script3D.h)
|
||||
- [ScriptCE.h](file://h/ScriptCE.h)
|
||||
- [Script2D.cpp](file://cpp/ProblemZone/Script2D.cpp)
|
||||
- [Script3D.cpp](file://cpp/ProblemZone/Script3D.cpp)
|
||||
- [ScriptCE.cpp](file://cpp/ProblemZone/ScriptCE.cpp)
|
||||
- [COpCreateSptDlg.h](file://h/opcreatesptdlg.h)
|
||||
- [COpCreateCESptDlg.h](file://h/opcreatecesptdlg.h)
|
||||
- [OpCreate3DSptDlg.h](file://h/OpCreate3DSptDlg.h)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本技术文档全面阐述了Geomative Studio中的脚本管理API，重点介绍SptManager类对2D、3D及跨孔测量脚本的生成与管理功能。文档详细说明了Script2D、Script3D和ScriptCE脚本对象的构造过程、配置参数和序列化机制，提供API使用示例，并解释脚本验证规则、依赖关系处理以及与任务执行模块的协同机制。
|
||||
|
||||
## 项目结构
|
||||
脚本管理功能主要位于cpp/Managers和h目录下，相关类文件组织清晰，遵循功能模块化设计原则。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[脚本管理] --> B[SptManager.cpp/h]
|
||||
A --> C[脚本基类]
|
||||
C --> D[Script.h/cpp]
|
||||
C --> E[Script2D.h/cpp]
|
||||
C --> F[Script3D.h/cpp]
|
||||
C --> G[ScriptCE.h/cpp]
|
||||
A --> H[脚本创建对话框]
|
||||
H --> I[opcreatesptdlg.h]
|
||||
H --> J[opcreatecesptdlg.h]
|
||||
H --> K[OpCreate3DSptDlg.h]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [SptManager.h](file://h/SptManager.h)
|
||||
- [Script.h](file://h/Script.h)
|
||||
- [Script2D.h](file://h/Script2D.h)
|
||||
- [Script3D.h](file://h/Script3D.h)
|
||||
- [ScriptCE.h](file://h/ScriptCE.h)
|
||||
|
||||
**Section sources**
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp)
|
||||
- [Script2D.cpp](file://cpp/ProblemZone/Script2D.cpp)
|
||||
- [Script3D.cpp](file://cpp/ProblemZone/Script3D.cpp)
|
||||
- [ScriptCE.cpp](file://cpp/ProblemZone/ScriptCE.cpp)
|
||||
|
||||
## 核心组件
|
||||
脚本管理API的核心是SptManager类，负责创建、管理和操作各种类型的测量脚本。该类通过工厂模式动态创建不同类型的脚本对象（Script2D、Script3D、ScriptCE），并维护脚本对象的生命周期。
|
||||
|
||||
**Section sources**
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L127-L157)
|
||||
- [SptManager.h](file://h/SptManager.h)
|
||||
|
||||
## 架构概述
|
||||
脚本管理API采用分层架构设计，上层为用户界面交互，中层为业务逻辑处理，底层为数据持久化。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
UI[用户界面] --> SptManager[SptManager]
|
||||
SptManager --> Script[脚本基类 CScript]
|
||||
Script --> Script2D[CScript2D]
|
||||
Script --> Script3D[CScript3D]
|
||||
Script --> ScriptCE[CScriptCE]
|
||||
SptManager --> Database[数据库操作]
|
||||
Database --> scon[scon表]
|
||||
Database --> channel[channel表]
|
||||
Database --> script2d[script2d表]
|
||||
Database --> script1d[script1d表]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp)
|
||||
- [Script.h](file://h/Script.h)
|
||||
- [Script2D.h](file://h/Script2D.h)
|
||||
- [Script3D.h](file://h/Script3D.h)
|
||||
- [ScriptCE.h](file://h/ScriptCE.h)
|
||||
|
||||
## 详细组件分析
|
||||
### SptManager类分析
|
||||
SptManager类是脚本管理的核心，负责脚本的创建、获取和删除操作。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CSptManager {
|
||||
+GetScript(dwHandle) CScript*
|
||||
+DeleteObjInMem(dwHandle) void
|
||||
+Create2DSConInDB(dwSConID) UINT
|
||||
+Delete2DSConInDB(dwSConID) void
|
||||
+CreateCESConInDB(dwSConID) UINT
|
||||
+Create3DSConInDB(dwSConID) UINT
|
||||
}
|
||||
class CScript {
|
||||
+m_iSType int
|
||||
+m_iEAmount int
|
||||
+m_chaList CLinkList
|
||||
}
|
||||
class CScript2D {
|
||||
+CScript2D(dwID, pConnection)
|
||||
}
|
||||
class CScript3D {
|
||||
+CScript3D(dwID, pConnection)
|
||||
}
|
||||
class CScriptCE {
|
||||
+CScriptCE(dwID, pConnection)
|
||||
}
|
||||
CSptManager --> CScript : "创建"
|
||||
CScript <|-- CScript2D : "继承"
|
||||
CScript <|-- CScript3D : "继承"
|
||||
CScript <|-- CScriptCE : "继承"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [SptManager.h](file://h/SptManager.h#L24-L50)
|
||||
- [Script.h](file://h/Script.h#L14-L30)
|
||||
- [Script2D.h](file://h/Script2D.h#L15-L25)
|
||||
- [Script3D.h](file://h/Script3D.h#L15-L25)
|
||||
- [ScriptCE.h](file://h/ScriptCE.h#L13-L23)
|
||||
|
||||
**Section sources**
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L127-L800)
|
||||
|
||||
### 脚本对象构造分析
|
||||
脚本对象的构造过程涉及用户界面交互、参数验证和数据库持久化。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant SptManager as SptManager
|
||||
participant Script as CScript
|
||||
participant DB as 数据库
|
||||
User->>SptManager : 创建2D脚本
|
||||
SptManager->>SptManager : 显示创建对话框
|
||||
SptManager->>User : 获取输入参数
|
||||
User->>SptManager : 提交参数
|
||||
SptManager->>SptManager : 验证脚本名称唯一性
|
||||
SptManager->>DB : 开始事务
|
||||
SptManager->>DB : 插入scon记录
|
||||
DB-->>SptManager : 返回脚本ID
|
||||
SptManager->>DB : 插入channel记录
|
||||
SptManager->>DB : 插入script2d记录
|
||||
SptManager->>DB : 更新测点数量
|
||||
SptManager->>DB : 提交事务
|
||||
SptManager-->>User : 创建成功
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L257-L487)
|
||||
- [opcreatesptdlg.h](file://h/opcreatesptdlg.h)
|
||||
|
||||
### 脚本序列化机制
|
||||
脚本对象通过数据库表进行序列化存储，不同类型的脚本使用不同的数据表。
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
scon ||--o{ channel : "包含"
|
||||
scon ||--o{ script2d : "包含"
|
||||
scon ||--o{ script1d : "包含"
|
||||
scon {
|
||||
string CN PK
|
||||
string Sname
|
||||
int Stype
|
||||
int Eamount
|
||||
int CHamount
|
||||
int TPamount
|
||||
string definer
|
||||
datetime DEdate
|
||||
string SCdesc
|
||||
string Rect
|
||||
string RectLoc
|
||||
string PoleDistance
|
||||
string PoleStep
|
||||
}
|
||||
channel {
|
||||
int ID PK
|
||||
int SCID FK
|
||||
int CHnumber
|
||||
int AR
|
||||
int MaxLayer
|
||||
}
|
||||
script2d {
|
||||
int ID PK
|
||||
int CHID FK
|
||||
int TSN
|
||||
int C1
|
||||
int C2
|
||||
int P1
|
||||
int P2
|
||||
float K
|
||||
int N
|
||||
int Layer
|
||||
float XPos
|
||||
}
|
||||
script1d {
|
||||
int ID PK
|
||||
int CHID FK
|
||||
int TSN
|
||||
float a
|
||||
float b
|
||||
float x
|
||||
float y
|
||||
float K
|
||||
int N
|
||||
}
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L363-L380)
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L714-L720)
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L741-L749)
|
||||
|
||||
## 依赖分析
|
||||
脚本管理API与其他模块存在紧密的依赖关系。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
SptManager --> Database[数据库连接]
|
||||
SptManager --> GUI[用户界面组件]
|
||||
SptManager --> Medium[介质模型]
|
||||
SptManager --> Channel[通道管理]
|
||||
SptManager --> ScriptRecord[测点记录]
|
||||
SptManager --> GUCodeCreator[GUID生成器]
|
||||
Database --> ADO[ADO数据库访问]
|
||||
GUI --> MFC[MFC框架]
|
||||
Medium --> MediumA[MediumA.h]
|
||||
Medium --> MediumB[MediumB.h]
|
||||
Medium --> MediumC[MediumC.h]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L5-L57)
|
||||
- [SptManager.h](file://h/SptManager.h)
|
||||
|
||||
**Section sources**
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp)
|
||||
|
||||
## 性能考虑
|
||||
在大规模脚本生成时，应注意以下性能优化点：
|
||||
1. 批量数据库操作：使用事务处理减少数据库往返次数
|
||||
2. 内存管理：及时释放不再使用的脚本对象
|
||||
3. 对话框响应：避免在UI线程中执行耗时操作
|
||||
4. 数据验证：在用户输入时进行即时验证，减少错误提交
|
||||
|
||||
## 故障排除指南
|
||||
常见问题及解决方案：
|
||||
1. 脚本创建失败：检查数据库连接状态和磁盘空间
|
||||
2. 脚本名称重复：确保脚本名称在同类型脚本中唯一
|
||||
3. 电极布局错误：验证电极数量和布局参数的合理性
|
||||
4. 数据库事务失败：检查数据库表结构和约束条件
|
||||
|
||||
**Section sources**
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L341-L345)
|
||||
- [SptManager.cpp](file://cpp/Managers/SptManager.cpp#L653-L658)
|
||||
|
||||
## 结论
|
||||
脚本管理API为Geomative Studio提供了强大的测量脚本生成功能，支持2D、3D和跨孔测量等多种模式。通过SptManager类的统一接口，实现了脚本创建、管理和持久化的完整生命周期管理。建议在大规模脚本生成时采用批量处理和事务优化策略，以提高系统性能和稳定性。
|
||||
@@ -0,0 +1,376 @@
|
||||
# 设备管理API
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [DevManager.h](file://h/DevManager.h)
|
||||
- [DevManager.cpp](file://cpp/Managers/DevManager.cpp)
|
||||
- [Device.h](file://h/Device.h)
|
||||
- [Device.cpp](file://cpp/ProblemZone/Device.cpp)
|
||||
- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h)
|
||||
- [ProManager.h](file://h/ProManager.h)
|
||||
- [SptManager.h](file://h/SptManager.h)
|
||||
- [FileOperTools.h](file://h/FileOperTools.h)
|
||||
- [StdThread.h](file://h/socket/StdThread.h)
|
||||
- [StdThread.cpp](file://cpp/socket/StdThread.cpp)
|
||||
- [Concurrentlist.h](file://h/socket/Concurrentlist.h)
|
||||
- [AutoLock.h](file://h/Lock/AutoLock.h)
|
||||
- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp)
|
||||
- [DevOperator.cpp](file://cpp/Operator/DevOperator.cpp)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向Geomative Studio中的设备管理API，重点围绕DevManager类与Device类的公共接口进行系统化文档化。内容涵盖：
|
||||
- 方法签名、输入参数、返回值类型与可能抛出的异常
|
||||
- 设备连接、状态监控、参数配置与固件升级等核心流程
|
||||
- 实际使用示例（以代码片段路径形式呈现）
|
||||
- 与项目管理（ProManager）与脚本管理（SptManager）的集成方式
|
||||
- 线程安全与异步操作机制
|
||||
- 常见错误处理策略与性能优化建议
|
||||
|
||||
## 项目结构
|
||||
设备管理API位于cpp/Managers与cpp/ProblemZone目录中，分别实现设备管理器与设备实体；同时通过CtrlProtocolDef.h定义协议与数据结构，FileOperTools.h提供通用日志与文件操作能力；Socket与Lock子模块提供线程与并发支持；Tools与Operator子模块提供固件升级与设备操作流程。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "设备管理层"
|
||||
DM["DevManager<br/>设备管理器"]
|
||||
DEV["Device<br/>设备实体"]
|
||||
end
|
||||
subgraph "协议与数据"
|
||||
CPD["CtrlProtocolDef.h<br/>协议/结构体定义"]
|
||||
FOT["FileOperTools.h<br/>日志/文件工具"]
|
||||
end
|
||||
subgraph "项目与脚本管理"
|
||||
PM["ProManager<br/>项目管理"]
|
||||
SM["SptManager<br/>脚本管理"]
|
||||
end
|
||||
subgraph "线程与并发"
|
||||
STDH["StdThread.h/.cpp<br/>线程框架"]
|
||||
CL["Concurrentlist.h<br/>并发队列"]
|
||||
AL["AutoLock.h<br/>自动锁"]
|
||||
end
|
||||
subgraph "固件与操作"
|
||||
CU["checkupdate.cpp<br/>固件升级"]
|
||||
DO["DevOperator.cpp<br/>设备操作流程"]
|
||||
end
|
||||
DM --> DEV
|
||||
DM --> CPD
|
||||
DM --> FOT
|
||||
DEV --> CPD
|
||||
DEV --> FOT
|
||||
PM --> DM
|
||||
SM --> DM
|
||||
CU --> DEV
|
||||
DO --> DEV
|
||||
STDH --> DM
|
||||
CL --> STDH
|
||||
AL --> DM
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [DevManager.h](file://h/DevManager.h#L1-L69)
|
||||
- [Device.h](file://h/Device.h#L1-L128)
|
||||
- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L1-L120)
|
||||
- [FileOperTools.h](file://h/FileOperTools.h#L1-L42)
|
||||
- [ProManager.h](file://h/ProManager.h#L1-L77)
|
||||
- [SptManager.h](file://h/SptManager.h#L1-L88)
|
||||
- [StdThread.h](file://h/socket/StdThread.h#L1-L80)
|
||||
- [StdThread.cpp](file://cpp/socket/StdThread.cpp#L1-L228)
|
||||
- [Concurrentlist.h](file://h/socket/Concurrentlist.h#L1-L143)
|
||||
- [AutoLock.h](file://h/Lock/AutoLock.h#L1-L17)
|
||||
- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1042-L1440)
|
||||
- [DevOperator.cpp](file://cpp/Operator/DevOperator.cpp#L1370-L1518)
|
||||
|
||||
章节来源
|
||||
- [DevManager.h](file://h/DevManager.h#L1-L69)
|
||||
- [Device.h](file://h/Device.h#L1-L128)
|
||||
|
||||
## 核心组件
|
||||
- DevManager：负责设备列表的初始化、增删改查、远程设备集合维护、设备句柄映射、设备信息更新等。
|
||||
- Device：负责设备状态设置、参数读取与显示、文件收发、命令执行、日志输出等。
|
||||
|
||||
章节来源
|
||||
- [DevManager.h](file://h/DevManager.h#L1-L69)
|
||||
- [Device.h](file://h/Device.h#L1-L128)
|
||||
|
||||
## 架构总览
|
||||
设备管理API围绕DevManager与Device展开，通过CtrlProtocolDef.h中的协议结构体与命令字进行设备通信；通过FileOperTools.h统一日志与文件操作；通过ProManager与SptManager实现与项目/脚本的集成；通过StdThread/Concurrentlist/AutoLock提供线程与并发保障；通过checkupdate与DevOperator实现固件升级与设备操作流程。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class DevManager {
|
||||
+GetOLDevList(pOLDevList)
|
||||
+GetFLDevList(pFLDevList)
|
||||
+GetDeviceByID(dwDevID)
|
||||
+GetDevice(dwHandle)
|
||||
+GetDevice(szDevSN)
|
||||
+GetRegisterDevice(szDevSN, bIsRegister)
|
||||
+InitialDevLinkList()
|
||||
+AddDevice(pDev)
|
||||
+DeleteDevice(dwHandle)
|
||||
+DeleteDevice(strDev)
|
||||
+SetDeviceHandle(pDev)
|
||||
+UpdateDevInfo(stDevParam, bRemoteDeveTyp)
|
||||
+AddRemoteDevice(stDevice)
|
||||
+DeleteRemoteDevice(stDevice)
|
||||
+GetRemoteDeviceInfo()
|
||||
}
|
||||
class Device {
|
||||
+ExecuteOrder(strOrder, strSign, pStrResult, nRepeatCnt, nPollCnt)
|
||||
+ExecuteSignleOrder(f_szOrder, f_szSign, f_szResult, nCmdPollCnt)
|
||||
+ModifyTimeWindow()
|
||||
+LockDevice()
|
||||
+Reset()
|
||||
+DelSynInfo()
|
||||
+DelGRInfo()
|
||||
+GetSynInfo()
|
||||
+GetDevInfo()
|
||||
+GetGRInfo()
|
||||
+GetPoleCount()
|
||||
+Register()
|
||||
+Unregister()
|
||||
+SendFile(szHostFilePath, szLocFilePath, szLocFileName)
|
||||
+ReceiveFile(szLocFilePath, szHostFileName, nRetryCnt)
|
||||
+ShowFLDetailInfo(devDetailList)
|
||||
+ShowOLDetailInfo(devDetailList)
|
||||
+ShowGRInfo(devGRList)
|
||||
+ShowACInfo(devDetailList)
|
||||
+ModifyParameter()
|
||||
+ShowCableHeadInfoDlg()
|
||||
+IsTheNumofPoleChanged()
|
||||
+TestGRForPerPole(iSN, strResArray)
|
||||
+TestGRForAllPole()
|
||||
+SetState(uState)
|
||||
+SetID(dwID)
|
||||
+PrintLog(strLog)
|
||||
+IsExistOtherUserData()
|
||||
+CheckGD10Password(strGD10Password)
|
||||
}
|
||||
DevManager --> Device : "管理/持有"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [DevManager.h](file://h/DevManager.h#L1-L69)
|
||||
- [Device.h](file://h/Device.h#L1-L128)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### DevManager 类
|
||||
- 职责
|
||||
- 维护设备链表与句柄映射
|
||||
- 提供设备查询、新增、删除、句柄设置
|
||||
- 远程设备集合维护（在线/离线）
|
||||
- 设备信息同步更新（硬件版本、软件版本、电池电压、功率频率、通道数等）
|
||||
|
||||
- 公共接口与行为要点
|
||||
- GetOLDevList：收集在线设备列表（状态为在线或新）
|
||||
- GetFLDevList：收集离线设备列表（基于数据库与当前在线状态过滤）
|
||||
- GetDeviceByID/GetDevice/GetDevice(CString)：按ID/句柄/序列号获取设备
|
||||
- GetRegisterDevice：根据序列号与MAC匹配判断是否已注册
|
||||
- InitialDevLinkList：从数据库初始化设备链表，设置初始状态与句柄
|
||||
- AddDevice/DeleteDevice：事务性地新增/删除设备及其关联表记录
|
||||
- SetDeviceHandle：为设备生成并设置句柄
|
||||
- UpdateDevInfo：解析设备上报的同步参数，更新数据库字段
|
||||
- AddRemoteDevice/DeleteRemoteDevice/GetRemoteDeviceInfo：维护远程设备集合
|
||||
|
||||
- 异常与错误处理
|
||||
- 数据库事务：AddDevice/DeleteDevice内部使用BeginTrans/CommitTrans/RollbackTrans
|
||||
- 异常捕获：捕获_com_error并弹窗提示，回滚事务
|
||||
- 空指针检查：DeleteObjInMem/AddObjInMem等对空指针进行保护
|
||||
|
||||
- 性能与复杂度
|
||||
- 列表遍历：GetDeviceByID/GetOLDevList/GetFLDevList涉及线性扫描，复杂度O(n)
|
||||
- 事务批量操作：AddDevice一次性插入多条记录，减少往返
|
||||
|
||||
- 使用示例（以路径代替代码）
|
||||
- 初始化设备链表：[InitialDevLinkList](file://cpp/Managers/DevManager.cpp#L160-L201)
|
||||
- 获取在线设备列表：[GetOLDevList](file://cpp/Managers/DevManager.cpp#L486-L508)
|
||||
- 删除设备（按句柄）：[DeleteDevice](file://cpp/Managers/DevManager.cpp#L383-L433)
|
||||
- 更新设备信息：[UpdateDevInfo](file://cpp/Managers/DevManager.cpp#L592-L642)
|
||||
|
||||
章节来源
|
||||
- [DevManager.h](file://h/DevManager.h#L1-L69)
|
||||
- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L1-L661)
|
||||
|
||||
### Device 类
|
||||
- 职责
|
||||
- 设备状态与标识管理（ID、状态、类型、MAC、序列号）
|
||||
- 参数读取与显示（离线/在线详情、GR信息、AC信息）
|
||||
- 文件收发（Zmodem/自定义协议）
|
||||
- 命令执行与轮询（ExecuteOrder/ExecuteSignleOrder）
|
||||
- 日志输出与辅助功能（打印日志、密码校验、GR测试等）
|
||||
|
||||
- 公共接口与行为要点
|
||||
- ExecuteOrder/ExecuteSignleOrder：发送命令并等待特定应答标记，支持重复与轮询
|
||||
- SendFile/ReceiveFile：封装进度对话框与重试逻辑
|
||||
- ShowFLDetailInfo/ShowOLDetailInfo/ShowGRInfo/ShowACInfo：查询数据库并填充UI列表
|
||||
- ModifyParameter/ModifyTimeWindow/LockDevice/Reset/Register/Unregister：参数与状态操作
|
||||
- TestGRForPerPole/TestGRForAllPole：逐点/全点测试接地电阻
|
||||
- SetState/SetID/PrintLog/IsExistOtherUserData/CheckGD10Password：状态与辅助功能
|
||||
|
||||
- 异常与错误处理
|
||||
- 命令执行超时与轮询上限控制
|
||||
- 文件传输失败时的重试与终止处理
|
||||
- 日志统一写入设备日志文件
|
||||
|
||||
- 性能与复杂度
|
||||
- 数据库查询：详情与GR/AC信息查询，复杂度取决于记录数量
|
||||
- 文件传输：受网络/设备响应影响，重试策略降低失败概率
|
||||
|
||||
- 使用示例（以路径代替代码）
|
||||
- 发送文件到设备：[SendFile](file://cpp/ProblemZone/Device.cpp#L651-L700)
|
||||
- 接收文件（含重试）：[ReceiveFile](file://cpp/ProblemZone/Device.cpp#L682-L727)
|
||||
- 查询在线详情：[ShowOLDetailInfo](file://cpp/ProblemZone/Device.cpp#L154-L279)
|
||||
- 查询GR信息：[ShowGRInfo](file://cpp/ProblemZone/Device.cpp#L511-L547)
|
||||
|
||||
章节来源
|
||||
- [Device.h](file://h/Device.h#L1-L128)
|
||||
- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L1-L800)
|
||||
|
||||
### 协议与数据结构（CtrlProtocolDef.h）
|
||||
- 关键结构体
|
||||
- STSynDevParam：设备同步参数（机器ID、软硬件版本、温度、电池电压、功率频率、通道数、下发点数等）
|
||||
- STModifyDevParam：设备修改参数（功率频率、线缆类型、阈值、堆叠、下发点数等）
|
||||
- STSigRemoteDev：远程设备信息（类型、ID、状态）
|
||||
- 命令字与状态枚举
|
||||
- 控制命令：登录、参数同步、设置参数、设置任务参数、测量GR、测量数据、心跳等
|
||||
- 接收状态：链接中断、超时、数据错序、数据错误、云端发送失败、设备上下线通知等
|
||||
|
||||
章节来源
|
||||
- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L1-L250)
|
||||
|
||||
### 与项目管理/脚本管理的集成
|
||||
- 项目管理（ProManager）
|
||||
- 在设备中创建/删除工程、测区，建立DMS结构，支持从设备上载/下传
|
||||
- 与DevManager配合，通过句柄/序列号定位设备，再调用ProManager的工程/测区操作
|
||||
- 脚本管理（SptManager）
|
||||
- 在设备中创建/删除脚本，初始化脚本列表，支持从设备加载/下传脚本
|
||||
- 与DevManager配合，先获取设备实例，再调用SptManager的脚本操作
|
||||
|
||||
章节来源
|
||||
- [ProManager.h](file://h/ProManager.h#L1-L77)
|
||||
- [SptManager.h](file://h/SptManager.h#L1-L88)
|
||||
|
||||
### 固件升级与设备操作流程
|
||||
- 固件升级
|
||||
- checkupdate.cpp：下载文件、兼容性校验、复制到固件目录、执行升级命令、结果判定
|
||||
- DevOperator.cpp：设备升级流程封装，包含功能板升级、固件升级等步骤
|
||||
- 设备操作
|
||||
- 通过Device的命令执行接口与文件收发接口完成升级过程中的交互
|
||||
|
||||
章节来源
|
||||
- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1042-L1440)
|
||||
- [DevOperator.cpp](file://cpp/Operator/DevOperator.cpp#L1370-L1518)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
DM["DevManager"] --> |使用| DEV["Device"]
|
||||
DM --> |使用| CPD["CtrlProtocolDef.h"]
|
||||
DM --> |使用| FOT["FileOperTools.h"]
|
||||
DEV --> |使用| CPD
|
||||
DEV --> |使用| FOT
|
||||
PM["ProManager"] --> |依赖| DM
|
||||
SM["SptManager"] --> |依赖| DM
|
||||
CU["checkupdate.cpp"] --> |依赖| DEV
|
||||
DO["DevOperator.cpp"] --> |依赖| DEV
|
||||
STDH["StdThread.h/.cpp"] --> |提供线程| DM
|
||||
CL["Concurrentlist.h"] --> |提供并发| STDH
|
||||
AL["AutoLock.h"] --> |提供锁| DM
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [DevManager.h](file://h/DevManager.h#L1-L69)
|
||||
- [Device.h](file://h/Device.h#L1-L128)
|
||||
- [CtrlProtocolDef.h](file://h/CtrlProtocolDef.h#L1-L120)
|
||||
- [FileOperTools.h](file://h/FileOperTools.h#L1-L42)
|
||||
- [ProManager.h](file://h/ProManager.h#L1-L77)
|
||||
- [SptManager.h](file://h/SptManager.h#L1-L88)
|
||||
- [StdThread.h](file://h/socket/StdThread.h#L1-L80)
|
||||
- [StdThread.cpp](file://cpp/socket/StdThread.cpp#L1-L228)
|
||||
- [Concurrentlist.h](file://h/socket/Concurrentlist.h#L1-L143)
|
||||
- [AutoLock.h](file://h/Lock/AutoLock.h#L1-L17)
|
||||
- [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp#L1042-L1440)
|
||||
- [DevOperator.cpp](file://cpp/Operator/DevOperator.cpp#L1370-L1518)
|
||||
|
||||
## 性能考量
|
||||
- 列表遍历与查询
|
||||
- DevManager的设备查询（按ID/序列号/句柄）为线性扫描，建议在高频场景下引入索引或缓存
|
||||
- 事务与数据库
|
||||
- AddDevice/DeleteDevice使用事务保证一致性，但批量写入可能带来延迟；可考虑分批提交或异步化
|
||||
- 文件传输
|
||||
- ReceiveFile/ReceiveFile具备重试机制，避免单次失败导致整体失败；建议结合断点续传与进度回调
|
||||
- 并发与线程
|
||||
- StdThread/Concurrentlist提供生产者/消费者模型，适合异步处理设备事件与数据；注意临界区保护与死锁规避
|
||||
|
||||
[本节为通用指导，无需列出具体文件来源]
|
||||
|
||||
## 故障排查指南
|
||||
- 设备连接与命令执行
|
||||
- ExecuteOrder/ExecuteSignleOrder超时：检查轮询次数与设备响应；确认命令格式与应答标记
|
||||
- 文件传输失败：查看重试次数与终止处理；确认设备端可用空间与权限
|
||||
- 数据库异常
|
||||
- AddDevice/DeleteDevice抛出_com_error：检查SQL语句与参数绑定；确保BeginTrans/CommitTrans/RollbackTrans配对
|
||||
- 日志定位
|
||||
- 统一日志输出：通过FileOperTools::WriteComLog记录关键SQL与流程信息
|
||||
- 线程问题
|
||||
- 并发访问冲突：使用AutoLock或临界区保护共享资源；避免在UI线程阻塞过久
|
||||
|
||||
章节来源
|
||||
- [Device.cpp](file://cpp/ProblemZone/Device.cpp#L682-L727)
|
||||
- [DevManager.cpp](file://cpp/Managers/DevManager.cpp#L222-L279)
|
||||
- [FileOperTools.h](file://h/FileOperTools.h#L1-L42)
|
||||
- [AutoLock.h](file://h/Lock/AutoLock.h#L1-L17)
|
||||
|
||||
## 结论
|
||||
DevManager与Device共同构成了Geomative Studio的设备管理API核心。前者负责设备生命周期与状态管理，后者负责设备侧的具体操作与数据交互。通过CtrlProtocolDef.h统一协议与数据结构，配合ProManager/SptManager实现项目与脚本层面的协同；借助StdThread/Concurrentlist/AutoLock提供线程与并发保障；checkupdate与DevOperator完善了固件升级与设备操作流程。建议在高频查询与批量操作场景中进一步优化索引与事务策略，在文件传输与命令执行中强化重试与超时控制，以提升整体稳定性与性能。
|
||||
|
||||
[本节为总结性内容，无需列出具体文件来源]
|
||||
|
||||
## 附录
|
||||
|
||||
### API调用流程图：固件升级（概念示意）
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as "界面"
|
||||
participant DevMgr as "DevManager"
|
||||
participant Dev as "Device"
|
||||
participant Upd as "checkupdate"
|
||||
participant DB as "数据库"
|
||||
UI->>DevMgr : "选择设备并发起升级"
|
||||
DevMgr->>Dev : "获取设备实例"
|
||||
Dev->>Upd : "准备升级文件/校验兼容性"
|
||||
Upd->>Upd : "复制文件到固件目录"
|
||||
Upd->>Dev : "执行升级命令"
|
||||
Dev-->>Upd : "返回升级结果"
|
||||
Upd->>DB : "更新设备版本信息"
|
||||
DB-->>Upd : "提交成功"
|
||||
Upd-->>DevMgr : "升级完成"
|
||||
DevMgr-->>UI : "反馈升级结果"
|
||||
```
|
||||
|
||||
[本图为概念示意，不直接映射具体源文件，故无图表来源]
|
||||
|
||||
### API调用流程图：枚举连接设备（概念示意）
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> Init["InitialDevLinkList()<br/>从数据库加载设备并初始化链表"]
|
||||
Init --> List["GetOLDevList()/GetFLDevList()<br/>筛选在线/离线设备"]
|
||||
List --> Show["展示设备列表<br/>UI层绑定数据"]
|
||||
Show --> End(["结束"])
|
||||
```
|
||||
|
||||
[本图为概念示意，不直接映射具体源文件，故无图表来源]
|
||||
@@ -0,0 +1,322 @@
|
||||
# 项目管理API
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp)
|
||||
- [ProManager.h](file://h/ProManager.h)
|
||||
- [Project.cpp](file://cpp/ProblemZone/Project.cpp)
|
||||
- [Project.h](file://h/Project.h)
|
||||
- [TestingZone.cpp](file://cpp/ProblemZone/TestingZone.cpp)
|
||||
- [TestingZone.h](file://h/TestingZone.h)
|
||||
- [DataMngStruct.cpp](file://cpp/ProblemZone/DataMngStruct.cpp)
|
||||
- [DataMngStruct.h](file://h/DataMngStruct.h)
|
||||
- [HandleProcessor.h](file://h/HandleProcessor.h)
|
||||
- [opcreateprojectdlg.h](file://h/opcreateprojectdlg.h)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文档深入探讨了Geomative Studio项目中的项目管理API，重点分析了ProManager类如何管理项目创建、打开、保存及测区配置等操作。文档详细记录了每个公共方法的技术规范，包括参数约束、状态转换逻辑和持久化行为。通过使用示例展示了如何通过API创建新项目、添加测区、配置任务参数并保存到缓存或数据库。同时解释了Project类的数据结构设计及其与脚本和测试数据的关联关系，说明了在多项目环境下的资源管理策略，并提供了错误恢复和数据一致性保障的最佳实践。
|
||||
|
||||
## 项目结构
|
||||
Geomative Studio项目采用分层架构设计，主要分为以下几个目录：
|
||||
- **CACHE**: 存放项目和测区的XML缓存文件
|
||||
- **DB**: 数据库相关文件和记录
|
||||
- **Install**: 安装程序和配置文件
|
||||
- **cpp**: C++源代码，包含Managers、ProblemZone等关键模块
|
||||
- **h**: 头文件，定义了各类接口和数据结构
|
||||
- **res**: 资源文件
|
||||
|
||||
项目管理功能主要集中在`cpp/Managers/ProManager.cpp`和`h/ProManager.h`中，通过ProManager类提供统一的项目管理接口。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "核心管理模块"
|
||||
ProManager[ProManager类]
|
||||
Project[Project类]
|
||||
TestingZone[TestingZone类]
|
||||
end
|
||||
subgraph "数据结构"
|
||||
DataMngStruct[DataMngStruct基类]
|
||||
HandleProcessor[HandleProcessor]
|
||||
end
|
||||
subgraph "持久化"
|
||||
Database[(数据库)]
|
||||
Cache[(缓存文件)]
|
||||
end
|
||||
ProManager --> Project
|
||||
ProManager --> TestingZone
|
||||
ProManager --> HandleProcessor
|
||||
Project --> DataMngStruct
|
||||
TestingZone --> DataMngStruct
|
||||
ProManager --> Database
|
||||
ProManager --> Cache
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [ProManager.h](file://h/ProManager.h#L30-L74)
|
||||
- [Project.h](file://h/Project.h#L16-L38)
|
||||
- [TestingZone.h](file://h/TestingZone.h#L14-L30)
|
||||
|
||||
**本节来源**
|
||||
- [ProManager.h](file://h/ProManager.h#L1-L77)
|
||||
- [Project.h](file://h/Project.h#L1-L41)
|
||||
|
||||
## 核心组件
|
||||
项目管理API的核心组件包括ProManager类、Project类和TestingZone类。ProManager作为项目管理的中枢，负责协调项目和测区的创建、删除、同步等操作。Project类代表一个工程项目，包含项目的基本信息和属性。TestingZone类代表项目中的测区，包含测区的配置和参数。
|
||||
|
||||
ProManager类通过句柄系统管理项目和测区对象，使用HandleProcessor生成和解析句柄，确保对象的唯一性和可追溯性。所有项目和测区数据都持久化存储在数据库和XML缓存文件中，实现了数据的双重保障。
|
||||
|
||||
**本节来源**
|
||||
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L1-L2054)
|
||||
- [Project.cpp](file://cpp/ProblemZone/Project.cpp#L1-L81)
|
||||
- [TestingZone.cpp](file://cpp/ProblemZone/TestingZone.cpp#L1-L81)
|
||||
|
||||
## 架构概述
|
||||
项目管理API采用分层架构设计，分为接口层、业务逻辑层和数据持久层。接口层提供统一的API接口，业务逻辑层实现具体的项目管理功能，数据持久层负责数据的存储和读取。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CProManager {
|
||||
+ShowProList(dwDevHandle, proList) bool
|
||||
+ShowTzList(dwProHandle, tzList) bool
|
||||
+CreateProjectInDB(dwID) UINT
|
||||
+CreateProjectInDev(dwID, pDev) UINT
|
||||
+CreateTzInDB(dwID, dwPrID) UINT
|
||||
+CreateTzInDev(dwID, pDev) UINT
|
||||
+DeleteProjectInDB(dwID) void
|
||||
+DeleteProjectInDev(szMac, szPrCN, pDev) UINT
|
||||
+DeleteTzInDB(dwID) void
|
||||
+DeleteTzInDev(szPrCN, szTzCN, pDev) UINT
|
||||
+GetDMS(dwHandle) CDataMngStruct*
|
||||
-m_handleProcessor CHandleProcessor
|
||||
-m_dmsLinkList CLinkList<CDataMngStruct*>
|
||||
-m_pConnection _ConnectionPtr
|
||||
}
|
||||
class CProject {
|
||||
+ShowDetailInfo(proDetailList) bool
|
||||
+CProject(dwID, pConnection)
|
||||
+~CProject()
|
||||
-m_dwID DWORD
|
||||
-m_pConnection _ConnectionPtr
|
||||
-m_szCN CString
|
||||
-m_szPRname CString
|
||||
-m_szDesc CString
|
||||
-m_szLocation CString
|
||||
-m_szPRdate CString
|
||||
-m_szDuration CString
|
||||
-m_szPS CString
|
||||
-m_szCS CString
|
||||
-m_szPM CString
|
||||
-m_szQAS CString
|
||||
-m_szStandard CString
|
||||
}
|
||||
class CTestingZone {
|
||||
+ShowDetailInfo(tzDetailList) bool
|
||||
+CTestingZone(dwID, pConnection)
|
||||
+~CTestingZone()
|
||||
-m_dwID DWORD
|
||||
-m_pConnection _ConnectionPtr
|
||||
-m_szTZname CString
|
||||
-m_szCDate CString
|
||||
-m_szDesc CString
|
||||
-m_szLocation CString
|
||||
-m_szCN CString
|
||||
-m_szTZtype CString
|
||||
}
|
||||
class CDataMngStruct {
|
||||
+ShowDetailInfo(dmsDetailList) virtual bool
|
||||
+CDataMngStruct()
|
||||
+~CDataMngStruct()
|
||||
}
|
||||
class CHandleProcessor {
|
||||
+GenerateHandle(dwID, uStyle) DWORD
|
||||
+GetIDFromHandle(dwHandle) DWORD
|
||||
+GetStyleFromHandle(dwHandle) UINT
|
||||
+AnalyseHandle(dwHandle, dwID, uStyle) void
|
||||
}
|
||||
CProManager --> CProject : "创建"
|
||||
CProManager --> CTestingZone : "创建"
|
||||
CProManager --> CHandleProcessor : "使用"
|
||||
CProject --> CDataMngStruct : "继承"
|
||||
CTestingZone --> CDataMngStruct : "继承"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [ProManager.h](file://h/ProManager.h#L30-L74)
|
||||
- [Project.h](file://h/Project.h#L16-L38)
|
||||
- [TestingZone.h](file://h/TestingZone.h#L14-L30)
|
||||
- [DataMngStruct.h](file://h/DataMngStruct.h#L14-L20)
|
||||
- [HandleProcessor.h](file://h/HandleProcessor.h#L12-L26)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### ProManager类分析
|
||||
ProManager类是项目管理的核心，负责协调项目和测区的生命周期管理。它通过数据库连接和设备通信，实现了项目数据的持久化和同步。
|
||||
|
||||
#### 项目创建流程
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始创建项目]) --> ShowDialog["显示项目创建对话框"]
|
||||
ShowDialog --> ValidateInput["验证输入参数"]
|
||||
ValidateInput --> CheckExistence["检查项目名称是否存在"]
|
||||
CheckExistence --> |存在| ShowError["显示错误信息"]
|
||||
CheckExistence --> |不存在| CreateInDB["在数据库创建项目"]
|
||||
CreateInDB --> GenerateCN["生成项目编号"]
|
||||
GenerateCN --> InsertDB["插入项目记录"]
|
||||
InsertDB --> GetID["获取项目ID"]
|
||||
GetID --> CreateDefaultTz["创建默认测区"]
|
||||
CreateDefaultTz --> CreateInDev["在设备创建项目"]
|
||||
CreateInDev --> CreateDir["创建项目目录"]
|
||||
CreateDir --> GenerateXML["生成project.xml"]
|
||||
GenerateXML --> SendToDevice["发送到设备"]
|
||||
SendToDevice --> |成功| UpdateSync["更新同步状态"]
|
||||
SendToDevice --> |失败| Rollback["回滚操作"]
|
||||
UpdateSync --> End([项目创建完成])
|
||||
Rollback --> End
|
||||
ShowError --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L249-L341)
|
||||
- [opcreateprojectdlg.h](file://h/opcreateprojectdlg.h#L15-L67)
|
||||
|
||||
#### 测区管理
|
||||
ProManager类提供了完整的测区管理功能，包括测区的创建、删除和同步。测区数据既存储在数据库中，也以XML格式缓存在本地，确保数据的可靠性和可恢复性。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as "用户界面"
|
||||
participant ProManager as "ProManager"
|
||||
participant Database as "数据库"
|
||||
participant Device as "设备"
|
||||
participant Cache as "缓存"
|
||||
UI->>ProManager : 创建测区请求
|
||||
ProManager->>Database : 检查测区是否存在
|
||||
Database-->>ProManager : 返回检查结果
|
||||
ProManager->>Database : 插入测区记录
|
||||
Database-->>ProManager : 返回测区ID
|
||||
ProManager->>Cache : 生成testzone.xml
|
||||
Cache-->>ProManager : 返回文件路径
|
||||
ProManager->>Device : 发送测区文件
|
||||
Device-->>ProManager : 返回操作结果
|
||||
ProManager->>Database : 更新同步状态
|
||||
Database-->>ProManager : 返回结果
|
||||
ProManager-->>UI : 返回操作结果
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L709-L943)
|
||||
- [TestingZone.h](file://h/TestingZone.h#L14-L30)
|
||||
|
||||
**本节来源**
|
||||
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L1-L2054)
|
||||
- [ProManager.h](file://h/ProManager.h#L1-L77)
|
||||
|
||||
### Project类分析
|
||||
Project类代表一个工程项目，封装了项目的所有属性和行为。它是项目管理的基本单元，通过数据库持久化存储项目信息。
|
||||
|
||||
#### 数据结构设计
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CProject {
|
||||
-m_dwID DWORD
|
||||
-m_pConnection _ConnectionPtr
|
||||
-m_szCN CString
|
||||
-m_szPRname CString
|
||||
-m_szDesc CString
|
||||
-m_szLocation CString
|
||||
-m_szPRdate CString
|
||||
-m_szDuration CString
|
||||
-m_szPS CString
|
||||
-m_szCS CString
|
||||
-m_szPM CString
|
||||
-m_szQAS CString
|
||||
-m_szStandard CString
|
||||
}
|
||||
note right of CProject
|
||||
项目数据结构包含 :
|
||||
- 项目编号(CN)
|
||||
- 项目名称(PRname)
|
||||
- 描述(PRdesc)
|
||||
- 位置(location)
|
||||
- 创建日期(PRdate)
|
||||
- 持续时间(duration)
|
||||
- 项目负责人(PS)
|
||||
- 客户(CS)
|
||||
- 项目经理(PM)
|
||||
- 质量保证(QAS)
|
||||
- 标准(standard)
|
||||
end note
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Project.h](file://h/Project.h#L16-L38)
|
||||
- [Project.cpp](file://cpp/ProblemZone/Project.cpp#L1-L81)
|
||||
|
||||
**本节来源**
|
||||
- [Project.cpp](file://cpp/ProblemZone/Project.cpp#L1-L81)
|
||||
- [Project.h](file://h/Project.h#L1-L41)
|
||||
|
||||
## 依赖分析
|
||||
项目管理API的组件之间存在明确的依赖关系，形成了一个层次化的架构。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
ProManager[ProManager] --> Project[Project]
|
||||
ProManager --> TestingZone[TestingZone]
|
||||
ProManager --> HandleProcessor[HandleProcessor]
|
||||
ProManager --> DataMngStruct[DataMngStruct]
|
||||
Project --> DataMngStruct
|
||||
TestingZone --> DataMngStruct
|
||||
ProManager --> Database[(数据库)]
|
||||
ProManager --> Cache[(缓存)]
|
||||
Database --> SQLServer[SQL Server]
|
||||
Cache --> XML[XML文件]
|
||||
style ProManager fill:#f9f,stroke:#333
|
||||
style Project fill:#bbf,stroke:#333
|
||||
style TestingZone fill:#bbf,stroke:#333
|
||||
style HandleProcessor fill:#f96,stroke:#333
|
||||
style DataMngStruct fill:#9f9,stroke:#333
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [ProManager.h](file://h/ProManager.h#L8-L13)
|
||||
- [Project.h](file://h/Project.h#L15-L16)
|
||||
- [TestingZone.h](file://h/TestingZone.h#L12-L13)
|
||||
|
||||
## 性能考虑
|
||||
项目管理API在设计时考虑了性能优化，主要体现在以下几个方面：
|
||||
- 使用句柄系统快速定位项目和测区对象
|
||||
- 采用缓存机制减少数据库访问频率
|
||||
- 批量操作减少设备通信次数
|
||||
- 异步处理耗时操作，提高响应速度
|
||||
|
||||
在多项目环境下，建议合理规划项目结构，避免单个项目包含过多测区，以保持系统性能。
|
||||
|
||||
## 故障排除指南
|
||||
当项目管理操作失败时，可以按照以下步骤进行排查：
|
||||
1. 检查数据库连接是否正常
|
||||
2. 验证设备通信是否畅通
|
||||
3. 确认缓存目录权限是否正确
|
||||
4. 检查XML文件格式是否正确
|
||||
5. 查看日志文件获取详细错误信息
|
||||
|
||||
对于数据一致性问题，系统提供了回滚机制，在操作失败时自动回滚到之前的状态，确保数据完整性。
|
||||
|
||||
**本节来源**
|
||||
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L1014-L1208)
|
||||
- [ProManager.cpp](file://cpp/Managers/ProManager.cpp#L1892-L1994)
|
||||
|
||||
## 结论
|
||||
项目管理API通过ProManager类提供了一套完整的项目生命周期管理功能，实现了项目和测区的创建、删除、同步等操作。系统采用分层架构设计，具有良好的可维护性和扩展性。通过数据库和缓存的双重持久化机制，确保了数据的可靠性和一致性。在多项目环境下，系统能够有效管理资源，提供稳定的项目管理服务。
|
||||
Reference in New Issue
Block a user