Open Chinese Convert: OpenCCPlugin.h Source File

Open Chinese Convert 1.3.0.dirty A project for conversion between Traditional and Simplified Chinese

Loading...
Searching...
No Matches
OpenCCPlugin.h
1#pragma once
2
3#include <stddef.h>
4#include <stdint.h>
5
6#if defined(_WIN32) && defined(OPENCC_PLUGIN_BUILD)
7#define OPENCC_PLUGIN_EXPORT __declspec(dllexport)
8#elif !defined(_WIN32)
9#define OPENCC_PLUGIN_EXPORT __attribute__((visibility("default")))
10#else
11#define OPENCC_PLUGIN_EXPORT
12#endif
13
14#ifdef __cplusplus
15extern "C" {
16#endif
17
18/*
19 * struct_size rules:
20 *
21 * - Caller must initialize struct_size to sizeof(struct) before passing
22 * any structure across the ABI boundary.
23 *
24 * - Callee must validate struct_size is sufficient for fields it reads.
25 *
26 * - Future ABI-compatible extensions may append fields to the end.
27 * Implementations must ignore unknown trailing fields.
28 */
29
30#define OPENCC_SEGMENTATION_PLUGIN_ABI_MAJOR 2
31#define OPENCC_SEGMENTATION_PLUGIN_ABI_MINOR 0
32
33enum {
34 OPENCC_ERROR_UNKNOWN = 1,
35 OPENCC_ERROR_INVALID_ARGUMENT = 2,
36 OPENCC_ERROR_PLUGIN_NOT_FOUND = 3,
37 OPENCC_ERROR_PLUGIN_LOAD_FAILED = 4,
38 OPENCC_ERROR_PLUGIN_SYMBOL_MISSING = 5,
39 OPENCC_ERROR_PLUGIN_ABI_MISMATCH = 6,
40 OPENCC_ERROR_PLUGIN_TYPE_MISMATCH = 7,
41 OPENCC_ERROR_PLUGIN_DESCRIPTOR_INVALID = 8,
42 OPENCC_ERROR_PLUGIN_RESOURCE_MISSING = 9,
43 OPENCC_ERROR_PLUGIN_RUNTIME_FAILURE = 10,
44};
45
46 typedef struct {
47 size_t struct_size;
48 const char* key;
49 const char* value;
50} opencc_kv_pair_t;
51
52typedef struct opencc_segmentation_handle opencc_segmentation_handle_t;
53
54 typedef struct {
55 size_t struct_size;
56 int code;
57 /*
58 * On return, error->message may point either to:
59 * - a static constant string, or
60 * - plugin-owned dynamically allocated memory.
61 * free_error(error) must release any plugin-owned resources associated with
62 * the error object and leave it in a safely destructible state.
63 */
64 const char* message;
65} opencc_error_t;
66
67 typedef struct {
68 size_t struct_size;
69 /*
70 * One positive length per segment, measured in Unicode code points.
71 * The sequence must cover the full input text in order.
72 */
73 uint32_t* codepoint_lengths;
74 size_t segment_count;
75} opencc_segment_length_array_t;
76
77 typedef struct {
78 size_t struct_size;
79 const opencc_kv_pair_t* config;
80 size_t config_size;
81 opencc_segmentation_handle_t** out;
82 opencc_error_t* error;
83} opencc_segmentation_create_args_t;
84
85 typedef struct {
86 size_t struct_size;
87 opencc_segmentation_handle_t* handle;
88 const char* utf8_text;
89 opencc_segment_length_array_t* segment_lengths;
90 opencc_error_t* error;
91} opencc_segmentation_segment_args_t;
92
93/*
94 * ABI Layout & Alignment Rules:
95 * 1. Uses natural C struct alignment (no #pragma pack).
96 * 2. Field order must not be altered in future versions.
97 * 3. Extensions must strictly append fields to the end.
98 */
99 typedef struct {
100 size_t struct_size;
101
102 /*
103 * Versioning semantics:
104 * - abi_major:
105 * Breaking ABI changes increment this value.
106 * Host must require exact major match.
107 *
108 * - abi_minor:
109 * Backward-compatible ABI additions increment this value.
110 * Host may require plugin->abi_minor >= minimum_supported_minor.
111 * Host should not reject a plugin solely because plugin->abi_minor is
112 * newer.
113 */
114 uint16_t abi_major;
115 uint16_t abi_minor;
116
117 /*
118 * Must point to static, null-terminated constant strings.
119 * Host will not attempt to free() or delete[] these pointers.
120 */
121 const char* plugin_name;
122 const char* segmentation_type;
123
124 /*
125 * [ABI CONTRACT]
126 * create(args):
127 * On success:
128 * - returns 0
129 * - *args->out must be set to a valid handle
130 * - args->error->code should be 0 (or unchanged)
131 * - args->error->message may be NULL
132 *
133 * On failure:
134 * - returns non-zero
135 * - *args->out must be NULL
136 * - args->error must remain in a state safe for free_error()
137 */
138 int (*create)(opencc_segmentation_create_args_t* args);
139
140 /*
141 * [ABI CONTRACT]
142 * segment(args):
143 * On success:
144 * - returns 0
145 * - args->utf8_text is interpreted as null-terminated UTF-8 input
146 * - segment_lengths contains plugin-owned segment length storage until
147 * free_segment_lengths() is called.
148 * - each returned length must be > 0 and measured in Unicode code points
149 * - the returned length sequence must cover the full input in order
150 *
151 * On failure:
152 * - returns non-zero
153 * - segment_lengths may be partially populated, but must remain safe for
154 * free_segment_lengths().
155 */
156 int (*segment)(opencc_segmentation_segment_args_t* args);
157
158 /*
159 * Cleanup Functions:
160 * 1. Must gracefully handle null pointers
161 * (segment_count = 0, codepoint_lengths = null).
162 * 2. Host promises to call these at most once per returned object.
163 * 3. free_segment_lengths() must also accept segment length array
164 * structures that were
165 * partially initialized by segment() on failure.
166 */
167 void (*free_segment_lengths)(opencc_segment_length_array_t* segment_lengths);
168 void (*destroy)(opencc_segmentation_handle_t* handle);
169 void (*free_error)(opencc_error_t* error);
170} opencc_segmentation_plugin_v2;
171
172OPENCC_PLUGIN_EXPORT const opencc_segmentation_plugin_v2*
173opencc_get_segmentation_plugin_v2(void);
174
175#ifdef __cplusplus
176}
177#endif
opencc_error_t
Definition OpenCCPlugin.h:54
opencc_kv_pair_t
Definition OpenCCPlugin.h:46
opencc_segment_length_array_t
Definition OpenCCPlugin.h:67
opencc_segmentation_create_args_t
Definition OpenCCPlugin.h:77
opencc_segmentation_plugin_v2
Definition OpenCCPlugin.h:99
opencc_segmentation_segment_args_t
Definition OpenCCPlugin.h:85