geomative/GeomativeStudio/.qoder/repowiki/zh/content/核心功能/数据导入导出/文件传输协议.md

文件传输协议

**本文档中引用的文件** - [FileTransfer_crul.cpp](file://cpp/Tools/FileTransfer_crul.cpp) - [FileTransfer_crul.h](file://h/FileTransfer_crul.h) - [checkupdate.cpp](file://cpp/Tools/checkupdate.cpp) - [LicenseUpgrade.cpp](file://cpp/Operator/LicenseUpgrade.cpp)

目录

1. 项目结构
2. 核心组件
3. 架构概述
4. 详细组件分析
5. 依赖分析
6. 性能考虑
7. 故障排除指南
8. 结论

项目结构

该项目包含多个模块，其中文件传输功能主要位于cpp/Tools/目录下。关键文件包括FileTransfer_crul.cpp和FileTransfer_crul.h，它们实现了基于libcurl的HTTP/HTTPS文件下载功能。日志文件存储在LOG/目录下的filetrans_crul_log.txt中。

graph TD
A[文件传输系统] --> B[FileTransfer_crul.h]
A --> C[FileTransfer_crul.cpp]
B --> D[CFileTransfer_crul类]
C --> D
D --> E[DownloadFile方法]
D --> F[WriteToFile回调]
D --> G[GetUrlResConValild方法]
H[日志系统] --> I[LOG\\filetrans_crul_log.txt]
D --> I

图示来源

• FileTransfer_crul.h
• FileTransfer_crul.cpp

本节来源

• FileTransfer_crul.h
• FileTransfer_crul.cpp

核心组件

CFileTransfer_crul类封装了libcurl库的功能，提供了一个高层接口用于HTTP/HTTPS文件下载。该类支持连接超时设置、进度回调、错误处理等特性，并实现了安全的HTTPS传输（不验证SSL证书）。

本节来源

• FileTransfer_crul.h
• FileTransfer_crul.cpp

架构概述

该文件传输系统采用面向对象的设计模式，通过CFileTransfer_crul类封装libcurl的所有功能。系统支持同步文件下载，具有完整的错误处理机制和日志记录功能。

classDiagram
class CFileTransfer_crul {
+m_strUrl : CString
+m_strSavePath : CString
+m_strSaveName : CString
+m_nTimeOut : int
+m_bIsNeedProgress : bool
+m_bIsHttpsFlag : bool
+m_bIsSSLCertify : bool
+DownloadFile() : bool
+SetOption() : void
+GetUrlResConValild() : bool
+WriteToFile() : size_t
+PrintLog() : void
+InitalLogInfo() : void
}
CFileTransfer_crul --> "1" "curl_easy_init" : 使用
CFileTransfer_crul --> "1" "LOG\\filetrans_crul_log.txt" : 写入日志

图示来源

• FileTransfer_crul.h
• FileTransfer_crul.cpp

详细组件分析

CFileTransfer_crul类分析

CFileTransfer_crul类是整个文件传输系统的核心，它封装了libcurl的所有功能，提供了简洁易用的接口。

类结构分析

classDiagram
class CFileTransfer_crul {
<<class>>
+m_pCrEasyHandl : CURL*
+m_strUrl : CString
+m_strSavePath : CString
+m_strSaveName : CString
+m_nTimeOut : int
+m_bIsNeedProgress : bool
+m_bIsNeedErrInfo : bool
+m_bIsHttpsFlag : bool
+m_bIsSSLCertify : bool
+m_pLog : FILE*
+m_lTotalRecvFileSize : curl_off_t
+m_lCurRecvSize : curl_off_t
+m_nWriteFileSize : static int
+m_RecvFileSize : static DOUBLE
+CFileTransfer_crul()
+~CFileTransfer_crul()
+Inital() : bool
+UnInital() : void
+SetOption() : void
+DownloadFile() : bool
+GetUrlResConValild() : bool
+WriteToFile() : static size_t
+xferinfo() : static int
+PrintLog() : void
+InitalLogInfo() : void
}

图示来源

• FileTransfer_crul.h
• FileTransfer_crul.cpp

下载流程分析

DownloadFile方法执行完整的文件下载流程，从URL验证到文件写入：

sequenceDiagram
participant Client as "客户端"
participant FileTransfer as "CFileTransfer_crul"
participant Curl as "libcurl"
participant File as "目标文件"
Client->>FileTransfer : 调用DownloadFile()
FileTransfer->>FileTransfer : 验证参数
FileTransfer->>FileTransfer : 检查HTTPS设置
FileTransfer->>FileTransfer : 调用GetUrlResConValild()
FileTransfer->>Curl : curl_easy_init()
FileTransfer->>Curl : 设置各种选项
FileTransfer->>Curl : CURLOPT_URL
FileTransfer->>Curl : CURLOPT_TIMEOUT
FileTransfer->>Curl : CURLOPT_WRITEFUNCTION
FileTransfer->>Curl : CURLOPT_SSL_VERIFYPEER
FileTransfer->>File : fopen()
FileTransfer->>Curl : curl_easy_perform()
Curl->>FileTransfer : 数据块
FileTransfer->>FileTransfer : WriteToFile回调
FileTransfer->>File : fwrite()
FileTransfer->>FileTransfer : 更新进度
Curl->>FileTransfer : 下载完成
FileTransfer->>File : fclose()
FileTransfer->>Curl : curl_easy_cleanup()
FileTransfer->>Client : 返回结果

图示来源

• FileTransfer_crul.cpp

本节来源

• FileTransfer_crul.cpp

数据写入与完整性校验

WriteToFile回调函数负责将接收到的数据流式写入文件，并进行完整性校验。

flowchart TD
Start([开始写入]) --> ValidateInput["验证输入参数"]
ValidateInput --> WriteData["调用fwrite写入数据"]
WriteData --> CheckResult{"写入结果检查"}
CheckResult --> |成功| UpdateCounter["更新写入计数器"]
CheckResult --> |失败| LogError["记录错误日志"]
UpdateCounter --> ReturnResult["返回写入大小"]
LogError --> ReturnResult
ReturnResult --> End([结束])

图示来源

• FileTransfer_crul.cpp

本节来源

• FileTransfer_crul.cpp

HTTPS安全策略

系统支持HTTPS但不支持SSL证书验证的安全策略，这在特定环境下提供了灵活性。

flowchart TD
Start([开始]) --> CheckHTTPS{"是否HTTPS?"}
CheckHTTPS --> |是| CheckCertify{"是否需要SSL验证?"}
CheckCertify --> |否| DisableVerify["设置CURLOPT_SSL_VERIFYPEER=0"]
DisableVerify --> Continue["继续下载流程"]
CheckCertify --> |是| ShowError["显示不支持SSL验证错误"]
ShowError --> End["结束"]
CheckHTTPS --> |否| Continue
Continue --> End

图示来源

• FileTransfer_crul.cpp
• FileTransfer_crul.cpp

本节来源

• FileTransfer_crul.cpp
• FileTransfer_crul.cpp

传输日志记录机制

系统实现了详细的日志记录机制，所有操作都会被记录到LOG\filetrans_crul_log.txt文件中。

classDiagram
class CFileTransfer_crul {
+m_pLog : FILE*
+InitalLogInfo() : void
+PrintLog() : void
}
CFileTransfer_crul --> "1" "LOG\\filetrans_crul_log.txt" : 写入日志
CFileTransfer_crul --> "1" "SYSTEMTIME g_sysCurTime" : 获取时间

日志格式包含时间戳和详细信息：

YYYY-MM-DD HH:MM:SS.MMM  [行号] 日志内容

图示来源

• FileTransfer_crul.cpp
• FileTransfer_crul.cpp

本节来源

• FileTransfer_crul.cpp
• FileTransfer_crul.cpp

资源可用性验证

GetUrlResConValild函数通过HEAD请求验证资源可用性，确保下载前资源存在。

sequenceDiagram
participant FileTransfer as "CFileTransfer_crul"
participant Curl as "libcurl"
FileTransfer->>Curl : curl_easy_init()
FileTransfer->>Curl : 设置CURLOPT_URL
FileTransfer->>Curl : 设置CURLOPT_TIMEOUT
FileTransfer->>Curl : 设置CURLOPT_NOBODY=1
FileTransfer->>Curl : 设置CURLOPT_HEADER=1
FileTransfer->>Curl : 设置WriteFuncForUrlTest
FileTransfer->>Curl : 执行3次curl_easy_perform
loop 重试机制
Curl->>FileTransfer : 返回结果
FileTransfer->>FileTransfer : 检查是否CURLE_OK
end
FileTransfer->>Curl : curl_easy_getinfo获取响应码
FileTransfer->>FileTransfer : 检查响应码是否为200
FileTransfer->>Curl : curl_easy_cleanup()
FileTransfer->>调用者 : 返回验证结果

图示来源

• FileTransfer_crul.cpp

本节来源

• FileTransfer_crul.cpp

依赖分析

该文件传输系统依赖于libcurl库和Windows API，与其他模块通过清晰的接口进行交互。

graph TD
A[CFileTransfer_crul] --> B[libcurl]
A --> C[Windows API]
A --> D[LOG\\filetrans_crul_log.txt]
B --> E[SSL/TLS]
B --> F[HTTP/HTTPS协议]
C --> G[文件系统]
C --> H[网络接口]
I[checkupdate.cpp] --> A
J[LicenseUpgrade.cpp] --> A

图示来源

• FileTransfer_crul.h
• FileTransfer_crul.cpp

本节来源

• FileTransfer_crul.h
• checkupdate.cpp
• LicenseUpgrade.cpp

性能考虑

该实现采用了流式写入方式，避免了内存中缓存整个文件，从而提高了大文件下载的性能。同时，通过设置合理的超时值和重试机制，增强了网络不稳定环境下的可靠性。

故障排除指南

当文件下载出现问题时，可以检查以下方面：

1. 查看LOG\filetrans_crul_log.txt中的详细日志
2. 确认URL格式正确且资源可用
3. 检查保存路径是否有写入权限
4. 验证网络连接是否正常
5. 检查超时设置是否合理

本节来源

• FileTransfer_crul.cpp
• FileTransfer_crul.cpp

结论

CFileTransfer_crul类提供了一个完整、可靠的基于libcurl的文件传输解决方案。它封装了复杂的libcurl API，提供了简洁易用的接口，同时具备完善的错误处理和日志记录功能。该实现支持HTTP/HTTPS协议，采用流式写入方式，适合大文件下载场景。通过HEAD请求预验证资源可用性，提高了下载成功率。日志系统详细记录了所有操作，便于问题排查和系统维护。