Document API 参考 — oosxl 0.1.0 文档

# Document API 参考

## 概述

Document API 提供创建、加载和管理 Excel 文档的最高级别函数，作为处理 Excel 文件的入口点。

## 文档操作

const char *get_version()

  获取库版本信息。

  返回:

    库版本字符串。

void set_key(const char *username, const char *key)

  设置许可序列号。

  参数:

    - user -- 用户名称

    - key -- 许可序列号

DocumentHandle doc_create()

  创建新的 Excel 文档。

  返回:

    新创建文档的句柄。

DocumentHandle doc_load(const char *filename)

  从文件加载 Excel 文档。

  参数:

    - filename -- 要加载的 Excel 文件路径。

  返回:

    已加载文档的句柄。

CSVPolicyHandle doc_create_csv_policy()

  创建一个解析 CSV 文件的策略。

  返回:

    Handle to the created CSV policy.

DocumentHandle doc_load_csv(const char *filename, CSVPolicyHandle policy)

  Load an existing CSV file.

  参数:

    - filename -- Path to the CSV file to load.

    - policy -- 解析 CSV 文件的策略。

  返回:

    已加载文档的句柄。

WorkbookHandle doc_get_workbook(DocumentHandle doc)

  从文档获取工作簿。

  参数:

    - doc -- 文档句柄。

  返回:

    工作簿句柄。

int doc_save(DocumentHandle doc, const char *filename)

  将文档保存到文件。

  参数:

    - doc -- 文档句柄。

    - filename -- 保存 Excel 文件的路径。

  返回:

    成功返回 1，失败返回 0。

int doc_save_to_csv(DocumentHandle doc, const char *filename)

  Save the current active worksheet to a csv file.

  参数:

    - doc -- 文档句柄。

    - filename -- 要保存文件的路径和文件名。如果为NULL，则以工作表名称作为文件名，并保存到当前工作目录。

  返回:

    成功返回 1，失败返回 0。

void doc_release(DocumentHandle doc)

  释放文档资源。

  参数:

    - doc -- 要释放的文档句柄。

## 使用流程

使用 Document API 的典型工作流程：

    // Get library version
    const char* version = get_version();
    printf("Using library version: %s\n", version);

    // Create a new document
    DocumentHandle doc = doc_create();

    // Get the workbook to start adding content
    WorkbookHandle workbook = doc_get_workbook(doc);

    // ... Work with workbook, worksheets, cells, etc.

    // Save the document
    int result = doc_save(doc, "output.xlsx");
    if (!result)
        printf("Failed to save document: \s.\n", run_msg());

    // Release resources
    doc_release(doc);

## 错误处理

- 始终检查 `doc_load()` 和 `doc_save()` 的返回值

- NULL 句柄表示创建或加载失败

- 使用 `doc_release()` 释放资源，防止内存泄漏

## 注意事项

- 在完成文档操作后务必调用 `doc_release()`

- 保存文档时确保目标目录有写入权限

- 加载不存在的文件或损坏的文件可能导致函数返回 NULL

Styled using the Piccolo Theme