1 | // © 2016 and later: Unicode, Inc. and others. |
2 | // License & terms of use: http://www.unicode.org/copyright.html |
3 | /* |
4 | ****************************************************************************** |
5 | * |
6 | * Copyright (C) 2009-2015, International Business Machines |
7 | * Corporation and others. All Rights Reserved. |
8 | * |
9 | ****************************************************************************** |
10 | * |
11 | * FILE NAME : icuplug.h |
12 | * |
13 | * Date Name Description |
14 | * 10/29/2009 sl New. |
15 | ****************************************************************************** |
16 | */ |
17 | |
18 | /** |
19 | * \file |
20 | * \brief C API: ICU Plugin API |
21 | * |
22 | * <h2>C API: ICU Plugin API</h2> |
23 | * |
24 | * <p>C API allowing run-time loadable modules that extend or modify ICU functionality.</p> |
25 | * |
26 | * <h3>Loading and Configuration</h3> |
27 | * |
28 | * <p>At ICU startup time, the environment variable "ICU_PLUGINS" will be |
29 | * queried for a directory name. If it is not set, the preprocessor symbol |
30 | * "DEFAULT_ICU_PLUGINS" will be checked for a default value.</p> |
31 | * |
32 | * <p>Within the above-named directory, the file "icuplugins##.txt" will be |
33 | * opened, if present, where ## is the major+minor number of the currently |
34 | * running ICU (such as, 44 for ICU 4.4, thus icuplugins44.txt)</p> |
35 | * |
36 | * <p>The configuration file has this format:</p> |
37 | * |
38 | * <ul> |
39 | * <li>Hash (#) begins a comment line</li> |
40 | * |
41 | * <li>Non-comment lines have two or three components: |
42 | * LIBRARYNAME ENTRYPOINT [ CONFIGURATION .. ]</li> |
43 | * |
44 | * <li>Tabs or spaces separate the three items.</li> |
45 | * |
46 | * <li>LIBRARYNAME is the name of a shared library, either a short name if |
47 | * it is on the loader path, or a full pathname.</li> |
48 | * |
49 | * <li>ENTRYPOINT is the short (undecorated) symbol name of the plugin's |
50 | * entrypoint, as above.</li> |
51 | * |
52 | * <li>CONFIGURATION is the entire rest of the line . It's passed as-is to |
53 | * the plugin.</li> |
54 | * </ul> |
55 | * |
56 | * <p>An example configuration file is, in its entirety:</p> |
57 | * |
58 | * \code |
59 | * # this is icuplugins44.txt |
60 | * testplug.dll myPlugin hello=world |
61 | * \endcode |
62 | * <p>Plugins are categorized as "high" or "low" level. Low level are those |
63 | * which must be run BEFORE high level plugins, and before any operations |
64 | * which cause ICU to be 'initialized'. If a plugin is low level but |
65 | * causes ICU to allocate memory or become initialized, that plugin is said |
66 | * to cause a 'level change'. </p> |
67 | * |
68 | * <p>At load time, ICU first queries all plugins to determine their level, |
69 | * then loads all 'low' plugins first, and then loads all 'high' plugins. |
70 | * Plugins are otherwise loaded in the order listed in the configuration file.</p> |
71 | * |
72 | * <h3>Implementing a Plugin</h3> |
73 | * \code |
74 | * U_CAPI UPlugTokenReturn U_EXPORT2 |
75 | * myPlugin (UPlugData *plug, UPlugReason reason, UErrorCode *status) { |
76 | * if(reason==UPLUG_REASON_QUERY) { |
77 | * uplug_setPlugName(plug, "Simple Plugin"); |
78 | * uplug_setPlugLevel(plug, UPLUG_LEVEL_HIGH); |
79 | * } else if(reason==UPLUG_REASON_LOAD) { |
80 | * ... Set up some ICU things here.... |
81 | * } else if(reason==UPLUG_REASON_UNLOAD) { |
82 | * ... unload, clean up ... |
83 | * } |
84 | * return UPLUG_TOKEN; |
85 | * } |
86 | * \endcode |
87 | * |
88 | * <p>The UPlugData* is an opaque pointer to the plugin-specific data, and is |
89 | * used in all other API calls.</p> |
90 | * |
91 | * <p>The API contract is:</p> |
92 | * <ol><li>The plugin MUST always return UPLUG_TOKEN as a return value- to |
93 | * indicate that it is a valid plugin.</li> |
94 | * |
95 | * <li>When the 'reason' parameter is set to UPLUG_REASON_QUERY, the |
96 | * plugin MUST call uplug_setPlugLevel() to indicate whether it is a high |
97 | * level or low level plugin.</li> |
98 | * |
99 | * <li>When the 'reason' parameter is UPLUG_REASON_QUERY, the plugin |
100 | * SHOULD call uplug_setPlugName to indicate a human readable plugin name.</li></ol> |
101 | * |
102 | * |
103 | * \internal ICU 4.4 Technology Preview |
104 | */ |
105 | |
106 | |
107 | #ifndef ICUPLUG_H |
108 | #define ICUPLUG_H |
109 | |
110 | #include "unicode/utypes.h" |
111 | |
112 | |
113 | #if UCONFIG_ENABLE_PLUGINS || defined(U_IN_DOXYGEN) |
114 | |
115 | |
116 | |
117 | /* === Basic types === */ |
118 | |
119 | #ifndef U_HIDE_INTERNAL_API |
120 | struct UPlugData; |
121 | /** |
122 | * @{ |
123 | * Typedef for opaque structure passed to/from a plugin. |
124 | * Use the APIs to access it. |
125 | * @internal ICU 4.4 Technology Preview |
126 | */ |
127 | typedef struct UPlugData UPlugData; |
128 | |
129 | /** @} */ |
130 | |
131 | /** |
132 | * Random Token to identify a valid ICU plugin. Plugins must return this |
133 | * from the entrypoint. |
134 | * @internal ICU 4.4 Technology Preview |
135 | */ |
136 | #define UPLUG_TOKEN 0x54762486 |
137 | |
138 | /** |
139 | * Max width of names, symbols, and configuration strings |
140 | * @internal ICU 4.4 Technology Preview |
141 | */ |
142 | #define UPLUG_NAME_MAX 100 |
143 | |
144 | |
145 | /** |
146 | * Return value from a plugin entrypoint. |
147 | * Must always be set to UPLUG_TOKEN |
148 | * @see UPLUG_TOKEN |
149 | * @internal ICU 4.4 Technology Preview |
150 | */ |
151 | typedef uint32_t UPlugTokenReturn; |
152 | |
153 | /** |
154 | * Reason code for the entrypoint's call |
155 | * @internal ICU 4.4 Technology Preview |
156 | */ |
157 | typedef enum { |
158 | UPLUG_REASON_QUERY = 0, /**< The plugin is being queried for info. **/ |
159 | UPLUG_REASON_LOAD = 1, /**< The plugin is being loaded. **/ |
160 | UPLUG_REASON_UNLOAD = 2, /**< The plugin is being unloaded. **/ |
161 | /** |
162 | * Number of known reasons. |
163 | * @internal The numeric value may change over time, see ICU ticket #12420. |
164 | */ |
165 | UPLUG_REASON_COUNT |
166 | } UPlugReason; |
167 | |
168 | |
169 | /** |
170 | * Level of plugin loading |
171 | * INITIAL: UNKNOWN |
172 | * QUERY: INVALID -> { LOW | HIGH } |
173 | * ERR -> INVALID |
174 | * @internal ICU 4.4 Technology Preview |
175 | */ |
176 | typedef enum { |
177 | UPLUG_LEVEL_INVALID = 0, /**< The plugin is invalid, hasn't called uplug_setLevel, or can't load. **/ |
178 | UPLUG_LEVEL_UNKNOWN = 1, /**< The plugin is waiting to be installed. **/ |
179 | UPLUG_LEVEL_LOW = 2, /**< The plugin must be called before u_init completes **/ |
180 | UPLUG_LEVEL_HIGH = 3, /**< The plugin can run at any time. **/ |
181 | /** |
182 | * Number of known levels. |
183 | * @internal The numeric value may change over time, see ICU ticket #12420. |
184 | */ |
185 | UPLUG_LEVEL_COUNT |
186 | } UPlugLevel; |
187 | |
188 | /** |
189 | * Entrypoint for an ICU plugin. |
190 | * @param plug the UPlugData handle. |
191 | * @param reason the reason code for the entrypoint's call. |
192 | * @param status Standard ICU error code. Its input value must |
193 | * pass the U_SUCCESS() test, or else the function returns |
194 | * immediately. Check for U_FAILURE() on output or use with |
195 | * function chaining. (See User Guide for details.) |
196 | * @return A valid plugin must return UPLUG_TOKEN |
197 | * @internal ICU 4.4 Technology Preview |
198 | */ |
199 | typedef UPlugTokenReturn (U_EXPORT2 UPlugEntrypoint) ( |
200 | UPlugData *plug, |
201 | UPlugReason reason, |
202 | UErrorCode *status); |
203 | |
204 | /* === Needed for Implementing === */ |
205 | |
206 | /** |
207 | * Request that this plugin not be unloaded at cleanup time. |
208 | * This is appropriate for plugins which cannot be cleaned up. |
209 | * @see u_cleanup() |
210 | * @param plug plugin |
211 | * @param dontUnload set true if this plugin can't be unloaded |
212 | * @internal ICU 4.4 Technology Preview |
213 | */ |
214 | U_CAPI void U_EXPORT2 |
215 | uplug_setPlugNoUnload(UPlugData *plug, UBool dontUnload); |
216 | |
217 | /** |
218 | * Set the level of this plugin. |
219 | * @param plug plugin data handle |
220 | * @param level the level of this plugin |
221 | * @internal ICU 4.4 Technology Preview |
222 | */ |
223 | U_CAPI void U_EXPORT2 |
224 | uplug_setPlugLevel(UPlugData *plug, UPlugLevel level); |
225 | |
226 | /** |
227 | * Get the level of this plugin. |
228 | * @param plug plugin data handle |
229 | * @return the level of this plugin |
230 | * @internal ICU 4.4 Technology Preview |
231 | */ |
232 | U_CAPI UPlugLevel U_EXPORT2 |
233 | uplug_getPlugLevel(UPlugData *plug); |
234 | |
235 | /** |
236 | * Get the lowest level of plug which can currently load. |
237 | * For example, if UPLUG_LEVEL_LOW is returned, then low level plugins may load |
238 | * if UPLUG_LEVEL_HIGH is returned, then only high level plugins may load. |
239 | * @return the lowest level of plug which can currently load |
240 | * @internal ICU 4.4 Technology Preview |
241 | */ |
242 | U_CAPI UPlugLevel U_EXPORT2 |
243 | uplug_getCurrentLevel(void); |
244 | |
245 | |
246 | /** |
247 | * Get plug load status |
248 | * @return The error code of this plugin's load attempt. |
249 | * @internal ICU 4.4 Technology Preview |
250 | */ |
251 | U_CAPI UErrorCode U_EXPORT2 |
252 | uplug_getPlugLoadStatus(UPlugData *plug); |
253 | |
254 | /** |
255 | * Set the human-readable name of this plugin. |
256 | * @param plug plugin data handle |
257 | * @param name the name of this plugin. The first UPLUG_NAME_MAX characters willi be copied into a new buffer. |
258 | * @internal ICU 4.4 Technology Preview |
259 | */ |
260 | U_CAPI void U_EXPORT2 |
261 | uplug_setPlugName(UPlugData *plug, const char *name); |
262 | |
263 | /** |
264 | * Get the human-readable name of this plugin. |
265 | * @param plug plugin data handle |
266 | * @return the name of this plugin |
267 | * @internal ICU 4.4 Technology Preview |
268 | */ |
269 | U_CAPI const char * U_EXPORT2 |
270 | uplug_getPlugName(UPlugData *plug); |
271 | |
272 | /** |
273 | * Return the symbol name for this plugin, if known. |
274 | * @param plug plugin data handle |
275 | * @return the symbol name, or NULL |
276 | * @internal ICU 4.4 Technology Preview |
277 | */ |
278 | U_CAPI const char * U_EXPORT2 |
279 | uplug_getSymbolName(UPlugData *plug); |
280 | |
281 | /** |
282 | * Return the library name for this plugin, if known. |
283 | * @param plug plugin data handle |
284 | * @param status error code |
285 | * @return the library name, or NULL |
286 | * @internal ICU 4.4 Technology Preview |
287 | */ |
288 | U_CAPI const char * U_EXPORT2 |
289 | uplug_getLibraryName(UPlugData *plug, UErrorCode *status); |
290 | |
291 | /** |
292 | * Return the library used for this plugin, if known. |
293 | * Plugins could use this to load data out of their |
294 | * @param plug plugin data handle |
295 | * @return the library, or NULL |
296 | * @internal ICU 4.4 Technology Preview |
297 | */ |
298 | U_CAPI void * U_EXPORT2 |
299 | uplug_getLibrary(UPlugData *plug); |
300 | |
301 | /** |
302 | * Return the plugin-specific context data. |
303 | * @param plug plugin data handle |
304 | * @return the context, or NULL if not set |
305 | * @internal ICU 4.4 Technology Preview |
306 | */ |
307 | U_CAPI void * U_EXPORT2 |
308 | uplug_getContext(UPlugData *plug); |
309 | |
310 | /** |
311 | * Set the plugin-specific context data. |
312 | * @param plug plugin data handle |
313 | * @param context new context to set |
314 | * @internal ICU 4.4 Technology Preview |
315 | */ |
316 | U_CAPI void U_EXPORT2 |
317 | uplug_setContext(UPlugData *plug, void *context); |
318 | |
319 | |
320 | /** |
321 | * Get the configuration string, if available. |
322 | * The string is in the platform default codepage. |
323 | * @param plug plugin data handle |
324 | * @return configuration string, or else null. |
325 | * @internal ICU 4.4 Technology Preview |
326 | */ |
327 | U_CAPI const char * U_EXPORT2 |
328 | uplug_getConfiguration(UPlugData *plug); |
329 | |
330 | /** |
331 | * Return all currently installed plugins, from newest to oldest |
332 | * Usage Example: |
333 | * \code |
334 | * UPlugData *plug = NULL; |
335 | * while(plug=uplug_nextPlug(plug)) { |
336 | * ... do something with 'plug' ... |
337 | * } |
338 | * \endcode |
339 | * Not thread safe- do not call while plugs are added or removed. |
340 | * @param prior pass in 'NULL' to get the first (most recent) plug, |
341 | * otherwise pass the value returned on a prior call to uplug_nextPlug |
342 | * @return the next oldest plugin, or NULL if no more. |
343 | * @internal ICU 4.4 Technology Preview |
344 | */ |
345 | U_CAPI UPlugData* U_EXPORT2 |
346 | uplug_nextPlug(UPlugData *prior); |
347 | |
348 | /** |
349 | * Inject a plugin as if it were loaded from a library. |
350 | * This is useful for testing plugins. |
351 | * Note that it will have a 'NULL' library pointer associated |
352 | * with it, and therefore no llibrary will be closed at cleanup time. |
353 | * Low level plugins may not be able to load, as ordering can't be enforced. |
354 | * @param entrypoint entrypoint to install |
355 | * @param config user specified configuration string, if available, or NULL. |
356 | * @param status error result |
357 | * @return the new UPlugData associated with this plugin, or NULL if error. |
358 | * @internal ICU 4.4 Technology Preview |
359 | */ |
360 | U_CAPI UPlugData* U_EXPORT2 |
361 | uplug_loadPlugFromEntrypoint(UPlugEntrypoint *entrypoint, const char *config, UErrorCode *status); |
362 | |
363 | |
364 | /** |
365 | * Inject a plugin from a library, as if the information came from a config file. |
366 | * Low level plugins may not be able to load, and ordering can't be enforced. |
367 | * @param libName DLL name to load |
368 | * @param sym symbol of plugin (UPlugEntrypoint function) |
369 | * @param config configuration string, or NULL |
370 | * @param status error result |
371 | * @return the new UPlugData associated with this plugin, or NULL if error. |
372 | * @internal ICU 4.4 Technology Preview |
373 | */ |
374 | U_CAPI UPlugData* U_EXPORT2 |
375 | uplug_loadPlugFromLibrary(const char *libName, const char *sym, const char *config, UErrorCode *status); |
376 | |
377 | /** |
378 | * Remove a plugin. |
379 | * Will request the plugin to be unloaded, and close the library if needed |
380 | * @param plug plugin handle to close |
381 | * @param status error result |
382 | * @internal ICU 4.4 Technology Preview |
383 | */ |
384 | U_CAPI void U_EXPORT2 |
385 | uplug_removePlug(UPlugData *plug, UErrorCode *status); |
386 | #endif /* U_HIDE_INTERNAL_API */ |
387 | |
388 | #endif /* UCONFIG_ENABLE_PLUGINS */ |
389 | |
390 | #endif /* _ICUPLUG */ |
391 | |
392 | |