include/unicode/icuplug.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 ******************************************************************************
0005 *
0006 *   Copyright (C) 2009-2015, International Business Machines
0007 *   Corporation and others.  All Rights Reserved.
0008 *
0009 ******************************************************************************
0010 *
0011 *  FILE NAME : icuplug.h
0012 *
0013 *   Date         Name        Description
0014 *   10/29/2009   sl          New.
0015 ******************************************************************************
0016 */
0017
0018 /**
0019  * \file
0020  * \brief C API: ICU Plugin API
0021  *
0022  * <h2>C API: ICU Plugin API</h2>
0023  *
0024  * <p>C API allowing run-time loadable modules that extend or modify ICU functionality.</p>
0025  *
0026  * <h3>Loading and Configuration</h3>
0027  *
0028  * <p>At ICU startup time, the environment variable "ICU_PLUGINS" will be
0029  * queried for a directory name.  If it is not set, the preprocessor symbol
0030  * "DEFAULT_ICU_PLUGINS" will be checked for a default value.</p>
0031  *
0032  * <p>Within the above-named directory, the file  "icuplugins##.txt" will be
0033  * opened, if present, where ## is the major+minor number of the currently
0034  * running ICU (such as, 44 for ICU 4.4, thus icuplugins44.txt)</p>
0035  *
0036  * <p>The configuration file has this format:</p>
0037  *
0038  * <ul>
0039  * <li>Hash (#) begins a comment line</li>
0040  *
0041  * <li>Non-comment lines have two or three components:
0042  * LIBRARYNAME     ENTRYPOINT     [ CONFIGURATION .. ]</li>
0043  *
0044  * <li>Tabs or spaces separate the three items.</li>
0045  *
0046  * <li>LIBRARYNAME is the name of a shared library, either a short name if
0047  * it is on the loader path,  or a full pathname.</li>
0048  *
0049  * <li>ENTRYPOINT is the short (undecorated) symbol name of the plugin's
0050  * entrypoint, as above.</li>
0051  *
0052  * <li>CONFIGURATION is the entire rest of the line . It's passed as-is to
0053  * the plugin.</li>
0054  * </ul>
0055  *
0056  * <p>An example configuration file is, in its entirety:</p>
0057  *
0058  * \code
0059  * # this is icuplugins44.txt
0060  * testplug.dll    myPlugin        hello=world
0061  * \endcode
0062  * <p>Plugins are categorized as "high" or "low" level.  Low level are those
0063  * which must be run BEFORE high level plugins, and before any operations
0064  * which cause ICU to be 'initialized'.  If a plugin is low level but
0065  * causes ICU to allocate memory or become initialized, that plugin is said
0066  * to cause a 'level change'. </p>
0067  *
0068  * <p>At load time, ICU first queries all plugins to determine their level,
0069  * then loads all 'low' plugins first, and then loads all 'high' plugins.
0070  * Plugins are otherwise loaded in the order listed in the configuration file.</p>
0071  *
0072  * <h3>Implementing a Plugin</h3>
0073  * \code
0074  * U_CAPI UPlugTokenReturn U_EXPORT2
0075  * myPlugin (UPlugData *plug, UPlugReason reason, UErrorCode *status) {
0076  *   if(reason==UPLUG_REASON_QUERY) {
0077  *      uplug_setPlugName(plug, "Simple Plugin");
0078  *      uplug_setPlugLevel(plug, UPLUG_LEVEL_HIGH);
0079  *    } else if(reason==UPLUG_REASON_LOAD) {
0080  *       ... Set up some ICU things here....
0081  *    } else if(reason==UPLUG_REASON_UNLOAD) {
0082  *       ... unload, clean up ...
0083  *    }
0084  *   return UPLUG_TOKEN;
0085  *  }
0086  * \endcode
0087  *
0088  * <p>The UPlugData*  is an opaque pointer to the plugin-specific data, and is
0089  * used in all other API calls.</p>
0090  *
0091  * <p>The API contract is:</p>
0092  * <ol><li>The plugin MUST always return UPLUG_TOKEN as a return value- to
0093  * indicate that it is a valid plugin.</li>
0094  *
0095  * <li>When the 'reason' parameter is set to UPLUG_REASON_QUERY,  the
0096  * plugin MUST call uplug_setPlugLevel() to indicate whether it is a high
0097  * level or low level plugin.</li>
0098  *
0099  * <li>When the 'reason' parameter is UPLUG_REASON_QUERY, the plugin
0100  * SHOULD call uplug_setPlugName to indicate a human readable plugin name.</li></ol>
0101  *
0102  *
0103  * \internal ICU 4.4 Technology Preview
0104  */
0105
0106
0107 #ifndef ICUPLUG_H
0108 #define ICUPLUG_H
0109
0110 #include "unicode/utypes.h"
0111
0112
0113 #if UCONFIG_ENABLE_PLUGINS || defined(U_IN_DOXYGEN)
0114
0115
0116
0117 /* === Basic types === */
0118
0119 #ifndef U_HIDE_INTERNAL_API
0120 struct UPlugData;
0121 /**
0122  * @{
0123  * Typedef for opaque structure passed to/from a plugin.
0124  * Use the APIs to access it.
0125  * @internal ICU 4.4 Technology Preview
0126  */
0127 typedef struct UPlugData UPlugData;
0128
0129 /** @} */
0130
0131 /**
0132  * Random Token to identify a valid ICU plugin. Plugins must return this
0133  * from the entrypoint.
0134  * @internal ICU 4.4 Technology Preview
0135  */
0136 #define UPLUG_TOKEN 0x54762486
0137
0138 /**
0139  * Max width of names, symbols, and configuration strings
0140  * @internal ICU 4.4 Technology Preview
0141  */
0142 #define UPLUG_NAME_MAX              100
0143
0144
0145 /**
0146  * Return value from a plugin entrypoint.
0147  * Must always be set to UPLUG_TOKEN
0148  * @see UPLUG_TOKEN
0149  * @internal ICU 4.4 Technology Preview
0150  */
0151 typedef uint32_t UPlugTokenReturn;
0152
0153 /**
0154  * Reason code for the entrypoint's call
0155  * @internal ICU 4.4 Technology Preview
0156  */
0157 typedef enum {
0158     UPLUG_REASON_QUERY = 0,     /**< The plugin is being queried for info. **/
0159     UPLUG_REASON_LOAD = 1,     /**< The plugin is being loaded. **/
0160     UPLUG_REASON_UNLOAD = 2,   /**< The plugin is being unloaded. **/
0161     /**
0162      * Number of known reasons.
0163      * @internal The numeric value may change over time, see ICU ticket #12420.
0164      */
0165     UPLUG_REASON_COUNT
0166 } UPlugReason;
0167
0168
0169 /**
0170  * Level of plugin loading
0171  *     INITIAL:  UNKNOWN
0172  *       QUERY:   INVALID ->  { LOW | HIGH }
0173  *     ERR -> INVALID
0174  * @internal ICU 4.4 Technology Preview
0175  */
0176 typedef enum {
0177     UPLUG_LEVEL_INVALID = 0,     /**< The plugin is invalid, hasn't called uplug_setLevel, or can't load. **/
0178     UPLUG_LEVEL_UNKNOWN = 1,     /**< The plugin is waiting to be installed. **/
0179     UPLUG_LEVEL_LOW     = 2,     /**< The plugin must be called before u_init completes **/
0180     UPLUG_LEVEL_HIGH    = 3,     /**< The plugin can run at any time. **/
0181     /**
0182      * Number of known levels.
0183      * @internal The numeric value may change over time, see ICU ticket #12420.
0184      */
0185     UPLUG_LEVEL_COUNT
0186 } UPlugLevel;
0187
0188 /**
0189  * Entrypoint for an ICU plugin.
0190  * @param plug the UPlugData handle.
0191  * @param reason the reason code for the entrypoint's call.
0192  * @param status Standard ICU error code. Its input value must
0193  *               pass the U_SUCCESS() test, or else the function returns
0194  *               immediately. Check for U_FAILURE() on output or use with
0195  *               function chaining. (See User Guide for details.)
0196  * @return A valid plugin must return UPLUG_TOKEN
0197  * @internal ICU 4.4 Technology Preview
0198  */
0199 typedef UPlugTokenReturn (U_EXPORT2 UPlugEntrypoint) (
0200                   UPlugData *plug,
0201                   UPlugReason reason,
0202                   UErrorCode *status);
0203
0204 /* === Needed for Implementing === */
0205
0206 /**
0207  * Request that this plugin not be unloaded at cleanup time.
0208  * This is appropriate for plugins which cannot be cleaned up.
0209  * @see u_cleanup()
0210  * @param plug plugin
0211  * @param dontUnload  set true if this plugin can't be unloaded
0212  * @internal ICU 4.4 Technology Preview
0213  */
0214 U_CAPI void U_EXPORT2
0215 uplug_setPlugNoUnload(UPlugData *plug, UBool dontUnload);
0216
0217 /**
0218  * Set the level of this plugin.
0219  * @param plug plugin data handle
0220  * @param level the level of this plugin
0221  * @internal ICU 4.4 Technology Preview
0222  */
0223 U_CAPI void U_EXPORT2
0224 uplug_setPlugLevel(UPlugData *plug, UPlugLevel level);
0225
0226 /**
0227  * Get the level of this plugin.
0228  * @param plug plugin data handle
0229  * @return the level of this plugin
0230  * @internal ICU 4.4 Technology Preview
0231  */
0232 U_CAPI UPlugLevel U_EXPORT2
0233 uplug_getPlugLevel(UPlugData *plug);
0234
0235 /**
0236  * Get the lowest level of plug which can currently load.
0237  * For example, if UPLUG_LEVEL_LOW is returned, then low level plugins may load
0238  * if UPLUG_LEVEL_HIGH is returned, then only high level plugins may load.
0239  * @return the lowest level of plug which can currently load
0240  * @internal ICU 4.4 Technology Preview
0241  */
0242 U_CAPI UPlugLevel U_EXPORT2
0243 uplug_getCurrentLevel(void);
0244
0245
0246 /**
0247  * Get plug load status
0248  * @return The error code of this plugin's load attempt.
0249  * @internal ICU 4.4 Technology Preview
0250  */
0251 U_CAPI UErrorCode U_EXPORT2
0252 uplug_getPlugLoadStatus(UPlugData *plug);
0253
0254 /**
0255  * Set the human-readable name of this plugin.
0256  * @param plug plugin data handle
0257  * @param name the name of this plugin. The first UPLUG_NAME_MAX characters willi be copied into a new buffer.
0258  * @internal ICU 4.4 Technology Preview
0259  */
0260 U_CAPI void U_EXPORT2
0261 uplug_setPlugName(UPlugData *plug, const char *name);
0262
0263 /**
0264  * Get the human-readable name of this plugin.
0265  * @param plug plugin data handle
0266  * @return the name of this plugin
0267  * @internal ICU 4.4 Technology Preview
0268  */
0269 U_CAPI const char * U_EXPORT2
0270 uplug_getPlugName(UPlugData *plug);
0271
0272 /**
0273  * Return the symbol name for this plugin, if known.
0274  * @param plug plugin data handle
0275  * @return the symbol name, or NULL
0276  * @internal ICU 4.4 Technology Preview
0277  */
0278 U_CAPI const char * U_EXPORT2
0279 uplug_getSymbolName(UPlugData *plug);
0280
0281 /**
0282  * Return the library name for this plugin, if known.
0283  * @param plug plugin data handle
0284  * @param status error code
0285  * @return the library name, or NULL
0286  * @internal ICU 4.4 Technology Preview
0287  */
0288 U_CAPI const char * U_EXPORT2
0289 uplug_getLibraryName(UPlugData *plug, UErrorCode *status);
0290
0291 /**
0292  * Return the library used for this plugin, if known.
0293  * Plugins could use this to load data out of their
0294  * @param plug plugin data handle
0295  * @return the library, or NULL
0296  * @internal ICU 4.4 Technology Preview
0297  */
0298 U_CAPI void * U_EXPORT2
0299 uplug_getLibrary(UPlugData *plug);
0300
0301 /**
0302  * Return the plugin-specific context data.
0303  * @param plug plugin data handle
0304  * @return the context, or NULL if not set
0305  * @internal ICU 4.4 Technology Preview
0306  */
0307 U_CAPI void * U_EXPORT2
0308 uplug_getContext(UPlugData *plug);
0309
0310 /**
0311  * Set the plugin-specific context data.
0312  * @param plug plugin data handle
0313  * @param context new context to set
0314  * @internal ICU 4.4 Technology Preview
0315  */
0316 U_CAPI void U_EXPORT2
0317 uplug_setContext(UPlugData *plug, void *context);
0318
0319
0320 /**
0321  * Get the configuration string, if available.
0322  * The string is in the platform default codepage.
0323  * @param plug plugin data handle
0324  * @return configuration string, or else null.
0325  * @internal ICU 4.4 Technology Preview
0326  */
0327 U_CAPI const char * U_EXPORT2
0328 uplug_getConfiguration(UPlugData *plug);
0329
0330 /**
0331  * Return all currently installed plugins, from newest to oldest
0332  * Usage Example:
0333  * \code
0334  *    UPlugData *plug = NULL;
0335  *    while(plug=uplug_nextPlug(plug)) {
0336  *        ... do something with 'plug' ...
0337  *    }
0338  * \endcode
0339  * Not thread safe- do not call while plugs are added or removed.
0340  * @param prior pass in 'NULL' to get the first (most recent) plug,
0341  *  otherwise pass the value returned on a prior call to uplug_nextPlug
0342  * @return the next oldest plugin, or NULL if no more.
0343  * @internal ICU 4.4 Technology Preview
0344  */
0345 U_CAPI UPlugData* U_EXPORT2
0346 uplug_nextPlug(UPlugData *prior);
0347
0348 /**
0349  * Inject a plugin as if it were loaded from a library.
0350  * This is useful for testing plugins.
0351  * Note that it will have a 'NULL' library pointer associated
0352  * with it, and therefore no llibrary will be closed at cleanup time.
0353  * Low level plugins may not be able to load, as ordering can't be enforced.
0354  * @param entrypoint entrypoint to install
0355  * @param config user specified configuration string, if available, or NULL.
0356  * @param status error result
0357  * @return the new UPlugData associated with this plugin, or NULL if error.
0358  * @internal ICU 4.4 Technology Preview
0359  */
0360 U_CAPI UPlugData* U_EXPORT2
0361 uplug_loadPlugFromEntrypoint(UPlugEntrypoint *entrypoint, const char *config, UErrorCode *status);
0362
0363
0364 /**
0365  * Inject a plugin from a library, as if the information came from a config file.
0366  * Low level plugins may not be able to load, and ordering can't be enforced.
0367  * @param libName DLL name to load
0368  * @param sym symbol of plugin (UPlugEntrypoint function)
0369  * @param config configuration string, or NULL
0370  * @param status error result
0371  * @return the new UPlugData associated with this plugin, or NULL if error.
0372  * @internal ICU 4.4 Technology Preview
0373  */
0374 U_CAPI UPlugData* U_EXPORT2
0375 uplug_loadPlugFromLibrary(const char *libName, const char *sym, const char *config, UErrorCode *status);
0376
0377 /**
0378  * Remove a plugin.
0379  * Will request the plugin to be unloaded, and close the library if needed
0380  * @param plug plugin handle to close
0381  * @param status error result
0382  * @internal ICU 4.4 Technology Preview
0383  */
0384 U_CAPI void U_EXPORT2
0385 uplug_removePlug(UPlugData *plug, UErrorCode *status);
0386 #endif  /* U_HIDE_INTERNAL_API */
0387
0388 #endif /* UCONFIG_ENABLE_PLUGINS */
0389
0390 #endif /* _ICUPLUG */
0391