# csv.dll 使用教程
## 1.创建DLL工具实例
### 加载DLL文件
```gotemplate
// CsvDLL CSV文件工具DLL结构
type csvDLL struct {
	dll           *syscall.DLL
	openCSVFile   *syscall.Proc // 打开/创建CSV文件
	readRows      *syscall.Proc // 读取多行数据
	writeRows     *syscall.Proc // 写入/覆盖行数据
	appendRows    *syscall.Proc // 追加行数据
	getRowCount   *syscall.Proc // 获取总行数
	findRows      *syscall.Proc // 搜索行
	closeCSVFile  *syscall.Proc // 关闭CSV文件
	mergeCSVFiles *syscall.Proc // 合并多个CSV文件
	getError      *syscall.Proc // 获取错误信息
	freeCString   *syscall.Proc // 释放C字符串
}

// 初始化csvDLL
func InitCsvDLL() (*csvDLL, error) {
	dllPath := filepath.Join("dll", "csv.dll")
	if _, err := os.Stat(dllPath); os.IsNotExist(err) {
		return nil, fmt.Errorf("csv DLL 不存在: %s", dllPath)
	}
	if dll, err := syscall.LoadDLL(dllPath); err != nil {
		return nil, fmt.Errorf("加载csv DLL 失败: %s", err)
	} else {
		return &csvDLL{
			dll:           dll,
			openCSVFile:   dll.MustFindProc("OpenCSVFile"),
			readRows:      dll.MustFindProc("ReadRows"),
			writeRows:     dll.MustFindProc("WriteRows"),
			appendRows:    dll.MustFindProc("AppendRows"),
			getRowCount:   dll.MustFindProc("GetRowCount"),
			findRows:      dll.MustFindProc("FindRows"),
			closeCSVFile:  dll.MustFindProc("CloseCSVFile"),
			mergeCSVFiles: dll.MustFindProc("MergeCSVFiles"),
			getError:      dll.MustFindProc("GetError"),
			freeCString:   dll.MustFindProc("FreeCString"),
		}, nil
	}
}

dll,err := InitCsvDLL()
```

### 获取C字符串
```gotemplate
// cStr 获取C字符串
func (m *csvDLL) cStr(p uintptr) string {
	if p == 0 {
		return ""
	}
	b := []byte{}
	for i := uintptr(0); ; i++ {
		c := *(*byte)(unsafe.Pointer(p + i))
		if c == 0 {
			break
		}
		b = append(b, c)
	}
	s := string(b)
	if m.freeCString != nil {
		m.freeCString.Call(p)
	}
	return s
}
```

## 2.使用dll函数示例
```gotemplate
// 打开/创建CSV文件
func (m *csvDLL) OpenCSVFile(filePath string, delimiter byte, hasHeader bool) (int64, error) {
	proc, err := m.dll.FindProc("OpenCSVFile")
	if err != nil {
		return -1, fmt.Errorf("找不到函数 OpenCSVFile: %v", err)
	}
	filePathPtr, _ := syscall.BytePtrFromString(filePath)
	hasHeaderInt := 0
	if hasHeader {
		hasHeaderInt = 1
	}
	info, _, _ := proc.Call(
		uintptr(unsafe.Pointer(filePathPtr)),
		uintptr(delimiter),
		uintptr(hasHeaderInt))
	return int64(info), nil
}
```

# 接口详情
## 1.打开/创建CSV文件(句柄)--OpenCSVFile
### 请求信息
```gotemplate
dll.OpenCSVFile(filename,delimiter,hasHeader)
```
### 请求参数
| 参数名 | 类型 | 必填 | 说明       |
|--|--|--|----------|
| filename | string | 是 | 文件名称(带路径) |
| delimiter | string | 是 | 分隔符(如 ',') |
| hasHeader | string | 是 | 是否有标题行   |
### 响应示例
```
句柄：int64
```

## 2.读取多行数据--ReadRows
### 请求信息
```gotemplate
dll.ReadRows(handle,startRow,count,buffer)
```
### 请求参数
| 参数名 | 类型     | 必填 | 说明            |
|--|--------|--|---------------|
| handle | int64  | 是 | 文件句柄          |
| startRow | int64  | 是 | 起始行           |
| count | int64  | 是 | 总数            |
| buffer | []byte | 是 | 返回的文件数据信息byte |
### 响应示例
```
句柄：int64
```

## 3.写入/覆盖行数据--WriteRows
### 请求信息
```gotemplate
dll.WriteRows(handle,rowsData,header)
```
### 请求参数
| 参数名 | 类型     | 必填 | 说明                    |
|--|--------|--|-----------------------|
| handle | int64  | 是 | 文件句柄                  |
| rowsData | string | 是 | 写入的数据，[][]string转换成字符串 |
| header | int    | 是 | 是否有文件头，0:有        |
### 响应示例
```
文件数据行数：int64
```

## 4.追加行数据--AppendRows
### 请求信息
```gotemplate
dll.AppendRows(handle,rowsData,rowCount)
```
### 请求参数
| 参数名 | 类型     | 必填 | 说明                         |
|--|--------|--|----------------------------|
| handle | int64  | 是 | 文件句柄                       |
| rowsData | []byte | 是 | 写入的数据，将[][]string转换成[]byte |
| rowCount | int    | 是 | 数据行数                       |
### 响应示例
```
文件数据行数：int64
```

## 5.获取总行数--GetRowCount
### 请求信息
```gotemplate
dll.GetRowCount(handle)
```
### 请求参数
| 参数名 | 类型     | 必填 | 说明                         |
|--|--------|--|----------------------------|
| handle | int64  | 是 | 文件句柄                       |
### 响应示例
```
文件总行数：int64
```

## 6.搜索行--FindRows
### 请求信息
```gotemplate
dll.FindRows(handle,searchText,columnIndex,resultBuffer,maxResults)
```
### 请求参数
| 参数名 | 类型     | 必填 | 说明                   |
|--|--------|--|----------------------|
| handle | int64  | 是 | 文件句柄                 |
| searchText | string | 是 | 要搜索的文本内容             |
| columnIndex | int64  | 是 | 指定搜索的列索引,索引从0开始 -1:表示搜索所有列 |
| resultBuffer | []byte | 是 | 结果缓冲区，用于存储找到的行索引 |
| maxResults | int64  | 是 | 限制最大返回结果数量 |
### 响应示例
```
实际找到的匹配行数：int64
```

## 7.合并多个CSV文件(线程安全)--MergeCSVFiles
### 请求信息
```gotemplate
dll.MergeCSVFiles(handlesPtr,handlesCount,outputFilename,delimiter,hasHeader)
```
### 请求参数
| 参数名 | 类型      | 必填 | 说明                         |
|--|---------|--|----------------------------|
| handlesPtr | []int64 | 是 | 文件句柄数组                     |
| handlesCount | string  | 是 | 文件句柄数组长度                   |
| columnIndex | int64   | 是 | 指定搜索的列索引,索引从0开始 -1:表示搜索所有列 |
| resultBuffer | []byte  | 是 | 结果缓冲区，用于存储找到的行索引           |
| maxResults | int64   | 是 | 限制最大返回结果数量                 |
### 响应示例
```
文件句柄：int64
```

## 8.关闭文件--CloseCSVFile
### 请求信息
```gotemplate
dll.MergeCSVFiles(handle)
```
### 请求参数
| 参数名 | 类型      | 必填 | 说明                      |
|--|---------|--|-------------------------|
| handle | []int64 | 是 | 文件句柄                 |
### 响应示例
```
结果：int64 0:表示成功
```

## 8.获取错误信息--GetError
### 请求信息
```gotemplate
dll.GetError(buffer)
```
### 请求参数
| 参数名 | 类型      | 必填 | 说明                      |
|--|---------|--|-------------------------|
| buffer | []byte  | 是 | 结果缓冲区，用于存储找到的行索引                 |
### 响应示例
```
结果:int
```

## 9.释放C字符串内存--FreeCString
### 请求信息
```gotemplate
dll.FreeCString(str)
```
### 请求参数
| 参数名 | 类型 | 必填 | 说明       |
|--|--|--|----------|
| str | string | 是 | 需要释放的字符串 |