cFileIO Class

Advanced file operations class based on Win32 API, supports large files (>2GB) and streaming read/write.

Description

cFileIO uses CreateFile API for file operations, with the following advantages over VB native Open statement:

• Supports large files (>2GB)
• Supports streaming chunked read/write
• Unified buffer operation mode
• Supports method chaining

Features:

• One instance can only operate on one file at a time
• Read content first enters internal buffer, then extracted via ReturnXXX methods
• Supports UTF-8, ANSI, UTF-16LE encodings

---

Properties

Property Name	Type	Description
IsOpen	Boolean	Whether file is open (read-only)
FilePath	String	Currently opened file path (read-only)
LastError	String	Last error message (read-only)
FileSize	Currency	File size (bytes, supports large files)
BufferSize	Long	Current buffer byte count

---

Methods

OpenFile

Opens a file, returns Me to support method chaining.

Syntax:

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

Parameters:

Parameter	Type	Description
FilePath	String	File path to open
AccessMode	String	Optional. Access mode: R=read-only, W=write-only, RW=read-write (default)

Returns:

• Returns self instance, supports method chaining

Exceptions:

• Throws error when file cannot be opened

Example:

Dim File As New cFileIO

' Basic open
File.OpenFile "C:\\data\\file.txt", "R"

' Method chaining
Dim Content As String
Content = File.OpenFile("C:\\data\\file.txt", "R").ReadData().ReturnText()

---

CloseFile

Closes the currently opened file.

Syntax:

Public Sub CloseFile()

Description:

• Automatically flushes buffer
• Automatically called when class terminates

Example:

Dim File As New cFileIO
File.OpenFile "C:\\data\\file.txt"
' ... operate on file ...
File.CloseFile

---

ClearBuffer

Clears the internal buffer.

Syntax:

Public Function ClearBuffer() As cFileIO

Returns:

• Returns self instance, supports method chaining

Example:

File.ClearBuffer()

---

SetBuffer

Fills the buffer with external byte array.

Syntax:

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

Parameters:

Parameter	Type	Description
Data	Byte()	Byte array to set

Returns:

• Returns self instance, supports method chaining

Example:

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

---

AppendBuffer

Appends bytes to the buffer.

Syntax:

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

Parameters:

Parameter	Type	Description
Data	Byte()	Byte array to append

Returns:

• Returns self instance, supports method chaining

Example:

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

---

SetBufferText

Fills the buffer with string (default UTF-8 encoding).

Syntax:

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

Parameters:

Parameter	Type	Description
Text	String	Text to set
CharSet	String	Optional. Encoding: UTF-8(default), ANSI, UTF-16LE

Returns:

• Returns self instance, supports method chaining

Example:

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

' ANSI encoding
File.SetBufferText "Hello World", "ANSI"

---

ReadData

Reads specified range of file into internal buffer.

Syntax:

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

Parameters:

Parameter	Type	Description
StartPos	Long	Optional. Start position (0-based, -1 means from beginning)
EndPos	Long	Optional. End position (0-based, -1 means to end)

Returns:

• Returns self instance, supports method chaining

Description:

• Position parameters are 0-based byte offsets
• Supports large files, but single read cannot exceed 2GB

Example:

Dim File As New cFileIO

' Read entire file
File.OpenFile("C:\\data\\file.txt", "R").ReadData()

' Read first 1000 bytes
File.ReadData(0, 999)

' Read from byte 1000 to end
File.ReadData(1000, -1)

---

ReturnText

Returns text from buffer.

Syntax:

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

Parameters:

Parameter	Type	Description
CharSet	String	Optional. Encoding: UTF-8(default), ANSI, UTF-16LE

Returns:

• String content

Example:

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

---

ReturnBytes

Returns byte array from buffer (copy).

Syntax:

Public Function ReturnBytes() As Byte()

Returns:

• Byte array

Example:

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

---

ReturnBase64

Returns Base64-encoded string from buffer.

Syntax:

Public Function ReturnBase64() As String

Returns:

• Base64-encoded string

Example:

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

---

SaveData

Writes internal buffer to file.

Syntax:

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

Parameters:

Parameter	Type	Description
FilePath	String	Optional. Target path, uses path from OpenFile if not provided
IsAppend	Boolean	Optional. False=overwrite (default), True=append to end of file

Returns:

• Returns self instance, supports method chaining

Example:

' Overwrite
File.SetBufferText("Hello World").SaveData("C:\\data\\output.txt")

' Append
File.SetBufferText("\nNew line").SaveData("C:\\data\\log.txt", True)

---

Usage Examples

Example 1: Read Text File

Sub ReadTextFileExample()
    Dim File As New cFileIO
    Dim Content As String
    
    On Error GoTo ErrorHandler
    
    ' Open and read file
    Content = File.OpenFile("C:\\data\\readme.txt", "R") _
                  .ReadData() _
                  .ReturnText("UTF-8")
    
    Debug.Print "File content:"
    Debug.Print Content
    
    File.CloseFile
    Exit Sub
    
ErrorHandler:
    Debug.Print "Error: " & File.LastError
    File.CloseFile
End Sub

Example 2: Write Text File

Sub WriteTextFileExample()
    Dim File As New cFileIO
    
    ' Create and write file
    File.SetBufferText("This is the first line", "UTF-8") _
        .SaveData("C:\\data\\output.txt")
    
    ' Append content
    File.SetBufferText("\nThis is an appended line", "UTF-8") _
        .SaveData("C:\\data\\output.txt", True)
    
    Debug.Print "File write completed"
End Sub

Example 3: Copy File (Chunked Reading)

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
    
    ' Open source file
    SrcFile.OpenFile "C:\\source\\largefile.zip", "R"
    FileSize = SrcFile.FileSize
    
    ' Read chunks and write
    Offset = 0
    Do While Offset < FileSize
        Dim EndPos As Long
        EndPos = Offset + ChunkSize - 1
        If EndPos >= FileSize Then EndPos = -1
        
        ' Read a chunk
        SrcFile.ReadData CLng(Offset), EndPos
        
        ' Write to destination file
        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 "File copy completed"
End Sub

Example 4: Encoding Conversion

Sub ConvertEncodingExample()
    Dim File As New cFileIO
    Dim Content As String
    
    ' Read ANSI file
    Content = File.OpenFile("C:\\data\\ansi.txt", "R") _
                  .ReadData() _
                  .ReturnText("ANSI")
    
    ' Convert to UTF-8 and save
    File.SetBufferText(Content, "UTF-8") _
        .SaveData "C:\\data\\utf8.txt"
    
    Debug.Print "Encoding conversion completed"
End Sub

---

Notes

1. Memory Limit: Single read cannot exceed 2GB
2. Encoding Detection: Automatically skips UTF-8 BOM and UTF-16 BOM when reading
3. Resource Release: File is automatically closed when class terminates, but explicit CloseFile is recommended
4. Thread Safety: Each instance can only operate on one file, multiple instances needed for multi-threading