coco
182 lines
11 KiB
Markdown
182 lines
11 KiB
Markdown
# 数据导入导出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导出）奠定了良好的基础。尽管当前的实现已经很成熟，但在处理超大规模数据集时，仍可进一步优化内存使用和提供更细粒度的进度反馈。 |