Skip to content
Office Oxide

C / FFI Office-Bibliothek — Schnellstart

Das C-API von office_oxide ist eine stabile, dünne ABI über dem Rust-Kern. Alle höheren Bindings (Go, C#, natives Node.js) rufen exakt dieselben Einstiegspunkte. Wenn dein Ökosystem keinen fertigen Wrapper hat, kannst du die C-Library jederzeit direkt linken.

Die maßgebliche Schnittstelle liegt in include/office_oxide_c/office_oxide.h; dieser Guide beschreibt dieselbe API.

Installation

Option 1 — aus dem Rust-Source bauen

git clone https://github.com/yfedoseev/office_oxide
cd office_oxide
cargo build --release --lib

Die Shared Library landet unter target/release/:

OS Datei
Linux liboffice_oxide.so
macOS liboffice_oxide.dylib
Windows office_oxide.dll (+ .lib-Importdatei)

Der Header liegt in include/office_oxide_c/office_oxide.h.

Option 2 — Prebuild installieren

install -Dm644 include/office_oxide_c/office_oxide.h /usr/local/include/office_oxide.h
install -Dm755 target/release/liboffice_oxide.so     /usr/local/lib/liboffice_oxide.so

Ein Dokument lesen

#include <stdio.h>
#include <stdlib.h>
#include "office_oxide.h"

int main(void) {
    int err = 0;
    char *text = office_extract_text("report.docx", &err);
    if (!text) {
        fprintf(stderr, "office_oxide failed: code=%d\n", err);
        return 1;
    }
    printf("%s\n", text);
    office_oxide_free_string(text);
    return 0;
}

Bauen und ausführen:

cc quickstart.c -I/usr/local/include -L/usr/local/lib -loffice_oxide -o quickstart
LD_LIBRARY_PATH=/usr/local/lib ./quickstart

Kern-API

Library-Info

const char *version = office_oxide_version();          // "0.1.0" — nicht freigeben
const char *fmt     = office_oxide_detect_format("f"); // "docx"/... oder NULL

Document (read-only)

int err = 0;
OfficeDocumentHandle *doc = office_document_open("file.xlsx", &err);
if (!doc) { /* err behandeln */ }

const char *fmt = office_document_format(doc);         // "xlsx" — nicht freigeben

char *text = office_document_plain_text(doc, &err);
char *md   = office_document_to_markdown(doc, &err);
char *html = office_document_to_html(doc, &err);
char *ir   = office_document_to_ir_json(doc, &err);

if (office_document_save_as(doc, "file.docx", &err) != 0) { /* err behandeln */ }

office_oxide_free_string(text);
office_oxide_free_string(md);
office_oxide_free_string(html);
office_oxide_free_string(ir);

office_document_free(doc);

Aus einem In-Memory-Buffer öffnen:

uint8_t *data = ...;
size_t   len  = ...;
OfficeDocumentHandle *doc =
    office_document_open_from_bytes(data, len, "docx", &err);

format muss eine der sechs Strings sein: "docx" | "xlsx" | "pptx" | "doc" | "xls" | "ppt".

EditableDocument

Bearbeiten bewahrt alle unveränderten OPC-Teile. Nur DOCX, XLSX und PPTX.

int err = 0;
OfficeEditableHandle *ed = office_editable_open("template.docx", &err);
if (!ed) { /* err behandeln */ }

int64_t n = office_editable_replace_text(ed, "{{name}}", "Alice", &err);
if (n < 0) { /* err behandeln */ }
printf("%lld Ersetzungen\n", (long long)n);

if (office_editable_save(ed, "out.docx", &err) != 0) { /* err behandeln */ }

office_editable_free(ed);

XLSX-Zellen setzen:

OfficeEditableHandle *wb = office_editable_open("budget.xlsx", &err);

office_editable_set_cell(wb, 0, "A1", OFFICE_CELL_STRING, "Total", 0.0,  &err);
office_editable_set_cell(wb, 0, "B1", OFFICE_CELL_NUMBER,  NULL,   42.5, &err);
office_editable_set_cell(wb, 0, "C1", OFFICE_CELL_BOOLEAN, NULL,   1.0,  &err);
office_editable_set_cell(wb, 0, "D1", OFFICE_CELL_EMPTY,   NULL,   0.0,  &err);

office_editable_save(wb, "budget.xlsx", &err);
office_editable_free(wb);

Für Booleans: value_num ungleich null bedeutet true.

In einen Heap-Buffer serialisieren:

size_t   out_len = 0;
uint8_t *buf     = office_editable_save_to_bytes(ed, &out_len, &err);
if (!buf) { /* err behandeln */ }
/* buf[0..out_len] hochladen oder streamen */
office_oxide_free_bytes(buf, out_len);

Einzelaufruf-Helfer

char *text = office_extract_text("file.docx", &err);
char *md   = office_to_markdown("file.pptx", &err);
char *html = office_to_html("file.xlsx", &err);
/* jedes mit office_oxide_free_string freigeben */

Speicherregeln

  • char* aus office_document_*, office_editable_* und den Einzelaufruf-Helfern müssen mit office_oxide_free_string(ptr) freigegeben werden.
  • uint8_t* (mit Out-Parameter out_len) müssen mit office_oxide_free_bytes(ptr, len) freigegeben werden. len muss zu dem Wert passen, den die API in out_len geschrieben hat.
  • Opake Handles werden mit dem zugehörigen *_free() freigegeben.
  • const char* aus office_oxide_version, office_oxide_detect_format, office_document_format sind statisch — nicht freigeben.

Fehler

Jeder fehlbare Aufruf nimmt einen int *error_code-Out-Parameter:

int err = 0;
OfficeDocumentHandle *doc = office_document_open("missing.docx", &err);
if (!doc) {
    switch (err) {
        case OFFICE_ERR_IO:    fputs("io-Fehler\n", stderr); break;
        case OFFICE_ERR_PARSE: fputs("Parsing-Fehler\n", stderr); break;
        /* ... */
    }
}
Makro Wert Bedeutung
OFFICE_OK 0 Erfolg
OFFICE_ERR_INVALID_ARG 1 nil-Pointer / unbekannter Format-String
OFFICE_ERR_IO 2 Dateisystem-Fehler
OFFICE_ERR_PARSE 3 beschädigtes Dokument
OFFICE_ERR_EXTRACTION 4 Parsing OK, aber Rendering scheiterte
OFFICE_ERR_INTERNAL 5 Bug — bitte Issue eröffnen
OFFICE_ERR_UNSUPPORTED 6 Erweiterung/Feature nicht unterstützt

Zellwert-Konstanten

Makro Wert
OFFICE_CELL_EMPTY 0
OFFICE_CELL_STRING 1
OFFICE_CELL_NUMBER 2
OFFICE_CELL_BOOLEAN 3

Altformate

Mit office_document_open öffnen — Format wird über die Erweiterung erkannt und über Magic-Bytes verifiziert. office_document_save_as konvertiert Legacy → OOXML transparent:

OfficeDocumentHandle *doc = office_document_open("old.xls", &err);
office_document_save_as(doc, "modern.xlsx", &err);
office_document_free(doc);

Thread-Sicherheit

Jeder Handle gehört dem Aufrufer — teile keinen Handle zwischen Threads. Verschiedene Handles dürfen parallel genutzt werden; die Library selbst ist reentrant.

C++

Der Header ist mit extern "C"-Guards umschlossen, also passt er direkt in eine C+±Übersetzungseinheit:

#include "office_oxide.h"

Mit RAII-Wrappern (std::unique_ptr<OfficeDocumentHandle, decltype(&office_document_free)>) kombinieren, damit das Cleanup exception-safe ist.

Fehlersuche

Symptom Lösung
Linker: undefined reference to office_document_open -loffice_oxide und passendes -L ergänzen; sicherstellen, dass die Library mit --release --lib gebaut wurde.
Laufzeit: error while loading shared libraries: liboffice_oxide.so Lib-Verzeichnis in LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH (macOS) ergänzen oder neben die EXE legen (Windows).
OFFICE_ERR_INVALID_ARG bei open_from_bytes format muss exakt `“docx”
Double-free oder Heap-Korruption Jeder char* mit office_oxide_free_string, jeder Byte-Buffer mit office_oxide_free_bytes(ptr, len) (mit dem Original-out_len).
office_editable_replace_text liefert auf XLSX 0 Erwartet — für Spreadsheet-Edits office_editable_set_cell benutzen.

Siehe auch