coco
376 lines
15 KiB
Markdown
376 lines
15 KiB
Markdown
# 设备管理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(["结束"])
|
||
```
|
||
|
||
[本图为概念示意，不直接映射具体源文件，故无图表来源] |