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