Logo Search packages:      
Sourcecode: icu version File versions  Download package

icuplug.h File Reference

C API: ICU Plugin API. More...

#include "unicode/utypes.h"
Include dependency graph for icuplug.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.


#define UPLUG_NAME_MAX   100
#define UPLUG_TOKEN   0x54762486


typedef UPlugReason reason
typedef UPlugReason UErrorCodestatus
typedef uint32_t UPlugTokenReturn
typedef struct UPlugData UPlugData


enum  UPlugLevel {


U_CAPI const char *U_EXPORT2 uplug_getConfiguration (UPlugData *plug)
U_CAPI void *U_EXPORT2 uplug_getContext (UPlugData *plug)
U_CAPI UPlugLevel U_EXPORT2 uplug_getCurrentLevel (void)
U_CAPI void *U_EXPORT2 uplug_getLibrary (UPlugData *plug)
U_CAPI const char *U_EXPORT2 uplug_getLibraryName (UPlugData *plug, UErrorCode *status)
U_CAPI UPlugLevel U_EXPORT2 uplug_getPlugLevel (UPlugData *plug)
U_CAPI UErrorCode U_EXPORT2 uplug_getPlugLoadStatus (UPlugData *plug)
U_CAPI const char *U_EXPORT2 uplug_getPlugName (UPlugData *plug)
U_CAPI const char *U_EXPORT2 uplug_getSymbolName (UPlugData *plug)
U_CAPI UPlugData *U_EXPORT2 uplug_loadPlugFromEntrypoint (UPlugEntrypoint *entrypoint, const char *config, UErrorCode *status)
U_CAPI UPlugData *U_EXPORT2 uplug_loadPlugFromLibrary (const char *libName, const char *sym, const char *config, UErrorCode *status)
U_CAPI UPlugData *U_EXPORT2 uplug_nextPlug (UPlugData *prior)
U_CAPI void U_EXPORT2 uplug_removePlug (UPlugData *plug, UErrorCode *status)
U_CAPI void U_EXPORT2 uplug_setContext (UPlugData *plug, void *context)
U_CAPI void U_EXPORT2 uplug_setPlugLevel (UPlugData *plug, UPlugLevel level)
U_CAPI void U_EXPORT2 uplug_setPlugName (UPlugData *plug, const char *name)
U_CAPI void U_EXPORT2 uplug_setPlugNoUnload (UPlugData *plug, UBool dontUnload)
typedef UPlugTokenReturn (U_EXPORT2 UPlugEntrypoint)(UPlugData *plug

Detailed Description

C API: ICU Plugin API.


C API allowing run-time loadable modules that extend or modify ICU functionality.

Loading and Configuration

At ICU startup time, the environment variable "ICU_PLUGINS" will be queried for a directory name. If it is not set, the preprocessor symbol "DEFAULT_ICU_PLUGINS" will be checked for a default value.

Within the above-named directory, the file "icuplugins##.txt" will be opened, if present, where ## is the major+minor number of the currently running ICU (such as, 44 for ICU 4.4, thus icuplugins44.txt)

The configuration file has this format:

  • Hash (#) begins a comment line

  • Non-comment lines have two or three components: LIBRARYNAME ENTRYPOINT [ CONFIGURATION .. ]

  • Tabs or spaces separate the three items.

  • LIBRARYNAME is the name of a shared library, either a short name if it is on the loader path, or a full pathname.

  • ENTRYPOINT is the short (undecorated) symbol name of the plugin's entrypoint, as above.

  • CONFIGURATION is the entire rest of the line . It's passed as-is to the plugin.

An example configuration file is, in its entirety:

 # this is icuplugins44.txt
 testplug.dll    myPlugin        hello=world

Plugins are categorized as "high" or "low" level. Low level are those which must be run BEFORE high level plugins, and before any operations which cause ICU to be 'initialized'. If a plugin is low level but causes ICU to allocate memory or become initialized, that plugin is said to cause a 'level change'.

At load time, ICU first queries all plugins to determine their level, then loads all 'low' plugins first, and then loads all 'high' plugins. Plugins are otherwise loaded in the order listed in the configuration file.

Implementing a Plugin

 U_CAPI UPlugTokenReturn U_EXPORT2 
 myPlugin (UPlugData *plug, UPlugReason reason, UErrorCode *status) {
   if(reason==UPLUG_REASON_QUERY) {
      uplug_setPlugName(plug, "Simple Plugin");
      uplug_setPlugLevel(plug, UPLUG_LEVEL_HIGH);
    } else if(reason==UPLUG_REASON_LOAD) {
       ... Set up some ICU things here.... 
    } else if(reason==UPLUG_REASON_UNLOAD) {
       ... unload, clean up ...
   return UPLUG_TOKEN;

The UPlugData* is an opaque pointer to the plugin-specific data, and is used in all other API calls.

The API contract is:

  1. The plugin MUST always return UPLUG_TOKEN as a return value- to indicate that it is a valid plugin.

  2. When the 'reason' parameter is set to UPLUG_REASON_QUERY, the plugin MUST call uplug_setPlugLevel() to indicate whether it is a high level or low level plugin.

  3. When the 'reason' parameter is UPLUG_REASON_QUERY, the plugin SHOULD call uplug_setPlugName to indicate a human readable plugin name.

ICU 4.4 Technology Preview

Definition in file icuplug.h.

Generated by  Doxygen 1.6.0   Back to index