1/*
2******************************************************************************
3*
4*   Copyright (C) 2009-2012, 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#ifndef U_HIDE_INTERNAL_API
114/**
115 * @{
116 * Opaque structure passed to/from a plugin.
117 * use the APIs to access it.
118 * @internal ICU 4.4 Technology Preview
119 */
120
121struct UPlugData;
122typedef struct UPlugData UPlugData;
123
124/** @} */
125
126/**
127 * Random Token to identify a valid ICU plugin. Plugins must return this
128 * from the entrypoint.
129 * @internal ICU 4.4 Technology Preview
130 */
131#define UPLUG_TOKEN 0x54762486
132
133/**
134 * Max width of names, symbols, and configuration strings
135 * @internal ICU 4.4 Technology Preview
136 */
137#define UPLUG_NAME_MAX              100
138
139
140/**
141 * Return value from a plugin entrypoint.
142 * Must always be set to UPLUG_TOKEN
143 * @see UPLUG_TOKEN
144 * @internal ICU 4.4 Technology Preview
145 */
146typedef uint32_t UPlugTokenReturn;
147
148/**
149 * Reason code for the entrypoint's call
150 * @internal ICU 4.4 Technology Preview
151 */
152typedef enum {
153    UPLUG_REASON_QUERY = 0,     /**< The plugin is being queried for info. **/
154    UPLUG_REASON_LOAD = 1,     /**< The plugin is being loaded. **/
155    UPLUG_REASON_UNLOAD = 2,   /**< The plugin is being unloaded. **/
156    UPLUG_REASON_COUNT         /**< count of known reasons **/
157} UPlugReason;
158
159
160/**
161 * Level of plugin loading
162 *     INITIAL:  UNKNOWN
163 *       QUERY:   INVALID ->  { LOW | HIGH }
164 *     ERR -> INVALID
165 * @internal ICU 4.4 Technology Preview
166 */
167typedef enum {
168    UPLUG_LEVEL_INVALID = 0,     /**< The plugin is invalid, hasn't called uplug_setLevel, or can't load. **/
169    UPLUG_LEVEL_UNKNOWN = 1,     /**< The plugin is waiting to be installed. **/
170    UPLUG_LEVEL_LOW     = 2,     /**< The plugin must be called before u_init completes **/
171    UPLUG_LEVEL_HIGH    = 3,     /**< The plugin can run at any time. **/
172    UPLUG_LEVEL_COUNT         /**< count of known reasons **/
173} UPlugLevel;
174
175/**
176 * Entrypoint for an ICU plugin.
177 * @param plug the UPlugData handle.
178 * @param status the plugin's extended status code.
179 * @return A valid plugin must return UPLUG_TOKEN
180 * @internal ICU 4.4 Technology Preview
181 */
182typedef UPlugTokenReturn (U_EXPORT2 UPlugEntrypoint) (
183                  UPlugData *plug,
184                  UPlugReason reason,
185                  UErrorCode *status);
186
187/* === Needed for Implementing === */
188
189/**
190 * Request that this plugin not be unloaded at cleanup time.
191 * This is appropriate for plugins which cannot be cleaned up.
192 * @see u_cleanup()
193 * @param plug plugin
194 * @param dontUnload  set true if this plugin can't be unloaded
195 * @internal ICU 4.4 Technology Preview
196 */
197U_INTERNAL void U_EXPORT2
198uplug_setPlugNoUnload(UPlugData *plug, UBool dontUnload);
199
200/**
201 * Set the level of this plugin.
202 * @param plug plugin data handle
203 * @param level the level of this plugin
204 * @internal ICU 4.4 Technology Preview
205 */
206U_INTERNAL void U_EXPORT2
207uplug_setPlugLevel(UPlugData *plug, UPlugLevel level);
208
209/**
210 * Get the level of this plugin.
211 * @param plug plugin data handle
212 * @return the level of this plugin
213 * @internal ICU 4.4 Technology Preview
214 */
215U_INTERNAL UPlugLevel U_EXPORT2
216uplug_getPlugLevel(UPlugData *plug);
217
218/**
219 * Get the lowest level of plug which can currently load.
220 * For example, if UPLUG_LEVEL_LOW is returned, then low level plugins may load
221 * if UPLUG_LEVEL_HIGH is returned, then only high level plugins may load.
222 * @return the lowest level of plug which can currently load
223 * @internal ICU 4.4 Technology Preview
224 */
225U_INTERNAL UPlugLevel U_EXPORT2
226uplug_getCurrentLevel(void);
227
228
229/**
230 * Get plug load status
231 * @return The error code of this plugin's load attempt.
232 * @internal ICU 4.4 Technology Preview
233 */
234U_INTERNAL UErrorCode U_EXPORT2
235uplug_getPlugLoadStatus(UPlugData *plug);
236
237/**
238 * Set the human-readable name of this plugin.
239 * @param plug plugin data handle
240 * @param name the name of this plugin. The first UPLUG_NAME_MAX characters willi be copied into a new buffer.
241 * @internal ICU 4.4 Technology Preview
242 */
243U_INTERNAL void U_EXPORT2
244uplug_setPlugName(UPlugData *plug, const char *name);
245
246/**
247 * Get the human-readable name of this plugin.
248 * @param plug plugin data handle
249 * @return the name of this plugin
250 * @internal ICU 4.4 Technology Preview
251 */
252U_INTERNAL const char * U_EXPORT2
253uplug_getPlugName(UPlugData *plug);
254
255/**
256 * Return the symbol name for this plugin, if known.
257 * @param plug plugin data handle
258 * @return the symbol name, or NULL
259 * @internal ICU 4.4 Technology Preview
260 */
261U_INTERNAL const char * U_EXPORT2
262uplug_getSymbolName(UPlugData *plug);
263
264/**
265 * Return the library name for this plugin, if known.
266 * @param plug plugin data handle
267 * @param status error code
268 * @return the library name, or NULL
269 * @internal ICU 4.4 Technology Preview
270 */
271U_INTERNAL const char * U_EXPORT2
272uplug_getLibraryName(UPlugData *plug, UErrorCode *status);
273
274/**
275 * Return the library used for this plugin, if known.
276 * Plugins could use this to load data out of their
277 * @param plug plugin data handle
278 * @return the library, or NULL
279 * @internal ICU 4.4 Technology Preview
280 */
281U_INTERNAL void * U_EXPORT2
282uplug_getLibrary(UPlugData *plug);
283
284/**
285 * Return the plugin-specific context data.
286 * @param plug plugin data handle
287 * @return the context, or NULL if not set
288 * @internal ICU 4.4 Technology Preview
289 */
290U_INTERNAL void * U_EXPORT2
291uplug_getContext(UPlugData *plug);
292
293/**
294 * Set the plugin-specific context data.
295 * @param plug plugin data handle
296 * @param context new context to set
297 * @internal ICU 4.4 Technology Preview
298 */
299U_INTERNAL void U_EXPORT2
300uplug_setContext(UPlugData *plug, void *context);
301
302
303/**
304 * Get the configuration string, if available.
305 * The string is in the platform default codepage.
306 * @param plug plugin data handle
307 * @return configuration string, or else null.
308 * @internal ICU 4.4 Technology Preview
309 */
310U_INTERNAL const char * U_EXPORT2
311uplug_getConfiguration(UPlugData *plug);
312
313/**
314 * Return all currently installed plugins, from newest to oldest
315 * Usage Example:
316 * \code
317 *    UPlugData *plug = NULL;
318 *    while(plug=uplug_nextPlug(plug)) {
319 *        ... do something with 'plug' ...
320 *    }
321 * \endcode
322 * Not thread safe- do not call while plugs are added or removed.
323 * @param prior pass in 'NULL' to get the first (most recent) plug,
324 *  otherwise pass the value returned on a prior call to uplug_nextPlug
325 * @return the next oldest plugin, or NULL if no more.
326 * @internal ICU 4.4 Technology Preview
327 */
328U_INTERNAL UPlugData* U_EXPORT2
329uplug_nextPlug(UPlugData *prior);
330
331/**
332 * Inject a plugin as if it were loaded from a library.
333 * This is useful for testing plugins.
334 * Note that it will have a 'NULL' library pointer associated
335 * with it, and therefore no llibrary will be closed at cleanup time.
336 * Low level plugins may not be able to load, as ordering can't be enforced.
337 * @param entrypoint entrypoint to install
338 * @param config user specified configuration string, if available, or NULL.
339 * @param status error result
340 * @return the new UPlugData associated with this plugin, or NULL if error.
341 * @internal ICU 4.4 Technology Preview
342 */
343U_INTERNAL UPlugData* U_EXPORT2
344uplug_loadPlugFromEntrypoint(UPlugEntrypoint *entrypoint, const char *config, UErrorCode *status);
345
346
347/**
348 * Inject a plugin from a library, as if the information came from a config file.
349 * Low level plugins may not be able to load, and ordering can't be enforced.
350 * @param libName DLL name to load
351 * @param sym symbol of plugin (UPlugEntrypoint function)
352 * @param config configuration string, or NULL
353 * @param status error result
354 * @return the new UPlugData associated with this plugin, or NULL if error.
355 * @internal ICU 4.4 Technology Preview
356 */
357U_INTERNAL UPlugData* U_EXPORT2
358uplug_loadPlugFromLibrary(const char *libName, const char *sym, const char *config, UErrorCode *status);
359
360/**
361 * Remove a plugin.
362 * Will request the plugin to be unloaded, and close the library if needed
363 * @param plug plugin handle to close
364 * @param status error result
365 * @internal ICU 4.4 Technology Preview
366 */
367U_INTERNAL void U_EXPORT2
368uplug_removePlug(UPlugData *plug, UErrorCode *status);
369#endif  /* U_HIDE_INTERNAL_API */
370
371#endif
372