Document API Reference

Overview

The Document API provides functions for creating, loading, and managing Excel documents at the highest level, serving as the entry point for working with Excel files.

Document Operations

const char *get_version()

Get the library version information.

Returns:

Library version string.

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

Set the license key.

Parameters:

  • user – User name

  • key – License key

DocumentHandle doc_create()

Create a new Excel document.

Returns:

Handle to the newly created document.

DocumentHandle doc_load(const char *filename)

Load an existing Excel document from file.

Parameters:

  • filename – Path to the Excel file to load.

Returns:

Handle to the loaded document.

CSVPolicyHandle doc_create_csv_policy()

Create a policy for parsing a CSV file.

Returns:

Handle to the created CSV policy.

DocumentHandle doc_load_csv(const char *filename, CSVPolicyHandle policy)

Load an existing CSV file.

Parameters:

  • filename – Path to the CSV file to load.

  • policy – A CSV policy for parsing the CSV file.

Returns:

Handle to the loaded document.

WorkbookHandle doc_get_workbook(DocumentHandle doc)

Get the workbook from the document.

Parameters:

  • doc – Document handle.

Returns:

Workbook handle.

int doc_save(DocumentHandle doc, const char *filename)

Save the document to a file.

Parameters:

  • doc – Document handle.

  • filename – Path where to save the Excel file.

Returns:

1 on success, 0 on failure.

int doc_save_to_csv(DocumentHandle doc, const char *filename)

Save the current active worksheet to a csv file.

Parameters:

  • doc – Document handle.

  • filename – The path and file name where the file will be saved. If NULL, the worksheet name will be used as the csv file name and the csv file will be saved in the current working directory.

Returns:

1 on success, 0 on failure.

void doc_release(DocumentHandle doc)

Release document resources.

Parameters:

  • doc – Document handle to release.

Usage Workflow

Typical workflow for using the 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);

Error Handling

  • Always check the return value of doc_load() and doc_save()

  • A NULL handle indicates failure in creation or loading

  • Use doc_release() to free resources and prevent memory leaks

Precautions

  • After completing the document operation, be sure to call ‘doc_release()’``

  • Ensure that the target directory has write permission when saving documents

  • Loading non-existent or damaged files may cause the function to return NULL