Skip to content
Office Oxide

C / FFI Office ライブラリ — クイックスタート

office_oxide の C API は Rust コア上の安定した薄い ABI です。Go、C#、Node.js（ネイティブ）など他のバインディングはすべて同じエントリポイントを呼んでいます。あなたの言語にラッパーがなければ、いつでも C ライブラリを直接リンクできます。

正規のサーフェスは include/office_oxide_c/office_oxide.h にあります。本ガイドは同じ API を解説します。

インストール

オプション 1 — Rust ソースからビルド

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

共有ライブラリは target/release/ に出力されます:

OS ファイル
Linux liboffice_oxide.so
macOS liboffice_oxide.dylib
Windows office_oxide.dll（+ .lib インポートライブラリ）

ヘッダは include/office_oxide_c/office_oxide.h。

オプション 2 — prebuilt をインストール

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

ドキュメントを読む

#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;
}

ビルドと実行:

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

コア API

ライブラリ情報

const char *version = office_oxide_version();          // "0.1.0" — free しない
const char *fmt     = office_oxide_detect_format("f"); // "docx"/... または NULL

Document（読み取り専用）

int err = 0;
OfficeDocumentHandle *doc = office_document_open("file.xlsx", &err);
if (!doc) { /* エラー処理 */ }

const char *fmt = office_document_format(doc);         // "xlsx" — free しない

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) { /* エラー処理 */ }

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

office_document_free(doc);

メモリバッファから開く:

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

format は "docx" | "xlsx" | "pptx" | "doc" | "xls" | "ppt" の 6 文字列のいずれか。

EditableDocument

編集は変更されていない OPC パーツをすべて温存します。DOCX、XLSX、PPTX のみ。

int err = 0;
OfficeEditableHandle *ed = office_editable_open("template.docx", &err);
if (!ed) { /* エラー処理 */ }

int64_t n = office_editable_replace_text(ed, "{{name}}", "Alice", &err);
if (n < 0) { /* エラー処理 */ }
printf("%lld 件置換\n", (long long)n);

if (office_editable_save(ed, "out.docx", &err) != 0) { /* エラー処理 */ }

office_editable_free(ed);

XLSX セルの設定:

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);

ブール値は value_num が非ゼロで true。

ヒープバッファへシリアライズ:

size_t   out_len = 0;
uint8_t *buf     = office_editable_save_to_bytes(ed, &out_len, &err);
if (!buf) { /* エラー処理 */ }
/* buf[0..out_len] をアップロード/ストリーム */
office_oxide_free_bytes(buf, out_len);

ワンショットヘルパー

char *text = office_extract_text("file.docx", &err);
char *md   = office_to_markdown("file.pptx", &err);
char *html = office_to_html("file.xlsx", &err);
/* 各々を office_oxide_free_string で解放 */

メモリのルール

  • office_document_*、office_editable_*、ワンショットヘルパーが返す char* は office_oxide_free_string(ptr) で解放。
  • out_len 出力パラメータと共に返される uint8_t* は office_oxide_free_bytes(ptr, len) で解放。len は API が out_len に書き込んだ値と一致させること。
  • 不透明ハンドルは対応する *_free() 呼び出しで解放。
  • office_oxide_version、office_oxide_detect_format、office_document_format の const char* は静的 — 解放しない。

エラー

失敗可能な呼び出しはすべて int *error_code 出力パラメータを取ります:

int err = 0;
OfficeDocumentHandle *doc = office_document_open("missing.docx", &err);
if (!doc) {
    switch (err) {
        case OFFICE_ERR_IO:    fputs("io エラー\n", stderr); break;
        case OFFICE_ERR_PARSE: fputs("パースエラー\n", stderr); break;
        /* ... */
    }
}
マクロ 値 意味
OFFICE_OK 0 成功
OFFICE_ERR_INVALID_ARG 1 nil ポインタ / 不明なフォーマット文字列
OFFICE_ERR_IO 2 ファイルシステムエラー
OFFICE_ERR_PARSE 3 壊れたドキュメント
OFFICE_ERR_EXTRACTION 4 パースは成功したがレンダリング失敗
OFFICE_ERR_INTERNAL 5 バグ — issue を上げてください
OFFICE_ERR_UNSUPPORTED 6 拡張子/機能が未対応

セル値定数

マクロ 値
OFFICE_CELL_EMPTY 0
OFFICE_CELL_STRING 1
OFFICE_CELL_NUMBER 2
OFFICE_CELL_BOOLEAN 3

レガシーフォーマット

office_document_open で開きます — 拡張子で判定し、マジックバイトで検証。office_document_save_as がレガシー → OOXML を透過的に変換:

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

スレッドセーフティ

各ハンドルは呼び出し側が所有します — 単一ハンドルをスレッド間で共有しないでください。異なるハンドルなら並列で使えます。ライブラリ自体はリエントラント。

C++

ヘッダは extern "C" ガードで囲まれているので C++ でもそのまま使えます:

#include "office_oxide.h"

例外安全のクリーンアップには RAII ラッパー（std::unique_ptr<OfficeDocumentHandle, decltype(&office_document_free)> など）と組み合わせてください。

トラブルシューティング

症状 対処
リンカ: undefined reference to office_document_open -loffice_oxide と適切な -L フラグを追加。ライブラリは --release --lib でビルドされていますか。
実行時: error while loading shared libraries: liboffice_oxide.so ライブラリディレクトリを LD_LIBRARY_PATH（Linux）、DYLD_LIBRARY_PATH（macOS）に追加するか EXE の隣に配置（Windows）。
open_from_bytes で OFFICE_ERR_INVALID_ARG format は厳密に `“docx”
二重解放やヒープ破壊 各 char* は office_oxide_free_string、各バイトバッファは office_oxide_free_bytes(ptr, len) で（元の out_len を使って）解放を確認。
XLSX で office_editable_replace_text が 0 を返す 想定どおり — スプレッドシート編集には office_editable_set_cell を使ってください。

関連項目