cFileIO 类

基于 Win32 API 的高级文件操作类，支持大文件（>2GB）和流式读写。

说明

cFileIO 使用 CreateFile API 实现文件操作，相比 VB 原生 Open 语句具有以下优势：

支持大文件（>2GB）
支持流式分块读写
统一的缓冲区操作模式
支持链式调用

特点：

一个实例同一时间只能操作一个文件
读取内容先进入内部缓冲区，再通过 ReturnXXX 方法提取
支持 UTF-8、ANSI、UTF-16LE 编码

属性

属性名	类型	说明
`IsOpen`	`Boolean`	文件是否已打开（只读）
`FilePath`	`String`	当前打开的文件路径（只读）
`LastError`	`String`	最后一次错误信息（只读）
`FileSize`	`Currency`	文件大小（字节，支持大文件）
`BufferSize`	`Long`	当前缓冲区字节数

方法

OpenFile

打开文件，返回 Me 支持链式调用。

语法：

Public Function OpenFile(ByVal FilePath As String, Optional ByVal AccessMode As String = "RW") As cFileIO

参数：

参数	类型	说明
`FilePath`	`String`	要打开的文件路径
`AccessMode`	`String`	可选。访问模式：`R`=只读, `W`=只写, `RW`=读写(默认)

返回值：

返回自身实例，支持链式调用

异常：

文件无法打开时抛出错误

示例：

Dim File As New cFileIO

' 基本打开
File.OpenFile "C:\\data\\file.txt", "R"

' 链式调用
Dim Content As String
Content = File.OpenFile("C:\\data\\file.txt", "R").ReadData().ReturnText()

CloseFile

关闭当前打开的文件。

语法：

Public Sub CloseFile()

说明：

自动刷新缓冲区
类终止时会自动调用

示例：

Dim File As New cFileIO
File.OpenFile "C:\\data\\file.txt"
' ... 操作文件 ...
File.CloseFile

ClearBuffer

清空内部缓冲区。

语法：

Public Function ClearBuffer() As cFileIO

返回值：

返回自身实例，支持链式调用

示例：

File.ClearBuffer()

SetBuffer

用外部字节数组填充缓冲区。

语法：

Public Function SetBuffer(Data() As Byte) As cFileIO

参数：

参数	类型	说明
`Data`	`Byte()`	要设置的字节数组

返回值：

返回自身实例，支持链式调用

示例：

Dim Bytes() As Byte
Bytes = StrConv("Hello World", vbFromUnicode)
File.SetBuffer Bytes

AppendBuffer

追加字节到缓冲区。

语法：

Public Function AppendBuffer(Data() As Byte) As cFileIO

参数：

参数	类型	说明
`Data`	`Byte()`	要追加的字节数组

返回值：

返回自身实例，支持链式调用

示例：

Dim Part1() As Byte, Part2() As Byte
Part1 = StrConv("Hello ", vbFromUnicode)
Part2 = StrConv("World", vbFromUnicode)
File.SetBuffer(Part1).AppendBuffer(Part2)

SetBufferText

用字符串填充缓冲区（默认 UTF-8 编码）。

语法：

Public Function SetBufferText(ByVal Text As String, Optional ByVal CharSet As String = "UTF-8") As cFileIO

参数：

参数	类型	说明
`Text`	`String`	要设置的文本
`CharSet`	`String`	可选。编码：`UTF-8`(默认)、`ANSI`、`UTF-16LE`

返回值：

返回自身实例，支持链式调用

示例：

' UTF-8 编码
File.SetBufferText "Hello World 你好世界"

' ANSI 编码
File.SetBufferText "Hello World", "ANSI"

ReadData

将文件指定范围读入内部缓冲区。

语法：

Public Function ReadData(Optional ByVal StartPos As Long = -1, Optional ByVal EndPos As Long = -1) As cFileIO

参数：

参数	类型	说明
`StartPos`	`Long`	可选。起始位置（0-based，-1 表示从开头）
`EndPos`	`Long`	可选。结束位置（0-based，-1 表示到末尾）

返回值：

返回自身实例，支持链式调用

说明：

位置参数为 0-based 字节偏移
支持大文件，但单次读取不能超过 2GB

示例：

Dim File As New cFileIO

' 读取整个文件
File.OpenFile("C:\\data\\file.txt", "R").ReadData()

' 读取前 1000 字节
File.ReadData(0, 999)

' 从第 1000 字节读到末尾
File.ReadData(1000, -1)

ReturnText

从缓冲区返回文本。

语法：

Public Function ReturnText(Optional ByVal CharSet As String = "UTF-8") As String

参数：

参数	类型	说明
`CharSet`	`String`	可选。编码：`UTF-8`(默认)、`ANSI`、`UTF-16LE`

返回值：

字符串内容

示例：

Dim Content As String
Content = File.OpenFile("C:\\data\\file.txt", "R") _
              .ReadData() _
              .ReturnText("UTF-8")
Debug.Print Content

ReturnBytes

从缓冲区返回字节数组（副本）。

语法：

Public Function ReturnBytes() As Byte()

返回值：

字节数组

示例：

Dim Bytes() As Byte
Bytes = File.OpenFile("C:\\data\\file.bin", "R").ReadData().ReturnBytes()

ReturnBase64

从缓冲区返回 Base64 编码字符串。

语法：

Public Function ReturnBase64() As String

返回值：

Base64 编码字符串

示例：

Dim Base64 As String
Base64 = File.OpenFile("C:\\data\\image.png", "R").ReadData().ReturnBase64()
Debug.Print Base64

SaveData

将内部缓冲区写入文件。

语法：

Public Function SaveData(Optional ByVal FilePath As String, Optional ByVal IsAppend As Boolean = False) As cFileIO

参数：

参数	类型	说明
`FilePath`	`String`	可选。目标路径，未提供则使用 OpenFile 时的路径
`IsAppend`	`Boolean`	可选。`False`=覆盖(默认), `True`=追加到文件末尾

返回值：

返回自身实例，支持链式调用

示例：

' 覆盖写入
File.SetBufferText("Hello World").SaveData("C:\\data\\output.txt")

' 追加写入
File.SetBufferText("\nNew line").SaveData("C:\\data\\log.txt", True)

使用示例

示例 1：读取文本文件

Sub ReadTextFileExample()
    Dim File As New cFileIO
    Dim Content As String
    
    On Error GoTo ErrorHandler
    
    ' 打开并读取文件
    Content = File.OpenFile("C:\\data\\readme.txt", "R") _
                  .ReadData() _
                  .ReturnText("UTF-8")
    
    Debug.Print "文件内容:"
    Debug.Print Content
    
    File.CloseFile
    Exit Sub
    
ErrorHandler:
    Debug.Print "错误: " & File.LastError
    File.CloseFile
End Sub

示例 2：写入文本文件

Sub WriteTextFileExample()
    Dim File As New cFileIO
    
    ' 创建并写入文件
    File.SetBufferText("这是第一行", "UTF-8") _
        .SaveData("C:\\data\\output.txt")
    
    ' 追加内容
    File.SetBufferText("\n这是追加的行", "UTF-8") _
        .SaveData("C:\\data\\output.txt", True)
    
    Debug.Print "文件写入完成"
End Sub

示例 3：复制文件（分块读取）

Sub CopyFileExample()
    Dim SrcFile As New cFileIO
    Dim DstFile As New cFileIO
    Dim FileSize As Currency
    Dim Offset As Currency
    Const ChunkSize As Long = 1048576  ' 1MB
    
    ' 打开源文件
    SrcFile.OpenFile "C:\\source\\largefile.zip", "R"
    FileSize = SrcFile.FileSize
    
    ' 分块读取并写入
    Offset = 0
    Do While Offset < FileSize
        Dim EndPos As Long
        EndPos = Offset + ChunkSize - 1
        If EndPos >= FileSize Then EndPos = -1
        
        ' 读取一块数据
        SrcFile.ReadData CLng(Offset), EndPos
        
        ' 写入目标文件
        If Offset = 0 Then
            DstFile.SetBuffer(SrcFile.ReturnBytes()).SaveData "C:\\dest\\largefile.zip"
        Else
            DstFile.SetBuffer(SrcFile.ReturnBytes()).SaveData "C:\\dest\\largefile.zip", True
        End If
        
        Offset = Offset + ChunkSize
    Loop
    
    SrcFile.CloseFile
    Debug.Print "文件复制完成"
End Sub

示例 4：编码转换

Sub ConvertEncodingExample()
    Dim File As New cFileIO
    Dim Content As String
    
    ' 读取 ANSI 文件
    Content = File.OpenFile("C:\\data\\ansi.txt", "R") _
                  .ReadData() _
                  .ReturnText("ANSI")
    
    ' 转换为 UTF-8 保存
    File.SetBufferText(Content, "UTF-8") _
        .SaveData "C:\\data\\utf8.txt"
    
    Debug.Print "编码转换完成"
End Sub

注意事项

内存限制：单次读取不能超过 2GB
编码检测：读取时会自动跳过 UTF-8 BOM 和 UTF-16 BOM
资源释放：类终止时会自动关闭文件，但建议显式调用 CloseFile
线程安全：每个实例只能操作一个文件，多线程需要多个实例

AES

Hash

HMAC

cFileIO 类

说明

属性

方法

OpenFile

CloseFile

ClearBuffer

SetBuffer

AppendBuffer

SetBufferText

ReadData

ReturnText

ReturnBytes

ReturnBase64

SaveData

使用示例

示例 1：读取文本文件

示例 2：写入文本文件

示例 3：复制文件（分块读取）

示例 4：编码转换

注意事项

cFileIO 类 ​

说明 ​

属性 ​

方法 ​

OpenFile ​

CloseFile ​

ClearBuffer ​

SetBuffer ​

AppendBuffer ​

SetBufferText ​

ReadData ​

ReturnText ​

ReturnBytes ​

ReturnBase64 ​

SaveData ​

使用示例 ​

示例 1：读取文本文件 ​

示例 2：写入文本文件 ​

示例 3：复制文件（分块读取） ​

示例 4：编码转换 ​

注意事项 ​

cFileIO 类

说明

属性

方法

OpenFile

CloseFile

ClearBuffer

SetBuffer

AppendBuffer

SetBufferText

ReadData

ReturnText

ReturnBytes

ReturnBase64

SaveData

使用示例

示例 1：读取文本文件

示例 2：写入文本文件

示例 3：复制文件（分块读取）

示例 4：编码转换

注意事项