ICU 74.1 74.1
Macros | Typedefs | Enumerations | Functions
icuplug.h File Reference

C API: ICU Plugin API. More...

#include "unicode/utypes.h"

Go to the source code of this file.

Macros

#define UPLUG_TOKEN   0x54762486
 Random Token to identify a valid ICU plugin. More...
 
#define UPLUG_NAME_MAX   100
 Max width of names, symbols, and configuration strings. More...
 

Typedefs

typedef uint32_t UPlugTokenReturn
 Return value from a plugin entrypoint. More...
 
typedef UPlugTokenReturn() UPlugEntrypoint(UPlugData *plug, UPlugReason reason, UErrorCode *status)
 Entrypoint for an ICU plugin. More...
 
typedef struct UPlugData UPlugData
 Typedef for opaque structure passed to/from a plugin. More...
 

Enumerations

enum  UPlugReason { UPLUG_REASON_QUERY = 0 , UPLUG_REASON_LOAD = 1 , UPLUG_REASON_UNLOAD = 2 , UPLUG_REASON_COUNT }
 Reason code for the entrypoint's call. More...
 
enum  UPlugLevel {
  UPLUG_LEVEL_INVALID = 0 , UPLUG_LEVEL_UNKNOWN = 1 , UPLUG_LEVEL_LOW = 2 , UPLUG_LEVEL_HIGH = 3 ,
  UPLUG_LEVEL_COUNT
}
 Level of plugin loading INITIAL: UNKNOWN QUERY: INVALID -> { LOW | HIGH } ERR -> INVALID. More...
 

Functions

U_CAPI void uplug_setPlugNoUnload (UPlugData *plug, UBool dontUnload)
 Request that this plugin not be unloaded at cleanup time. More...
 
U_CAPI void uplug_setPlugLevel (UPlugData *plug, UPlugLevel level)
 Set the level of this plugin. More...
 
U_CAPI UPlugLevel uplug_getPlugLevel (UPlugData *plug)
 Get the level of this plugin. More...
 
U_CAPI UPlugLevel uplug_getCurrentLevel (void)
 Get the lowest level of plug which can currently load. More...
 
U_CAPI UErrorCode uplug_getPlugLoadStatus (UPlugData *plug)
 Get plug load status. More...
 
U_CAPI void uplug_setPlugName (UPlugData *plug, const char *name)
 Set the human-readable name of this plugin. More...
 
U_CAPI const char * uplug_getPlugName (UPlugData *plug)
 Get the human-readable name of this plugin. More...
 
U_CAPI const char * uplug_getSymbolName (UPlugData *plug)
 Return the symbol name for this plugin, if known. More...
 
U_CAPI const char * uplug_getLibraryName (UPlugData *plug, UErrorCode *status)
 Return the library name for this plugin, if known. More...
 
U_CAPI void * uplug_getLibrary (UPlugData *plug)
 Return the library used for this plugin, if known. More...
 
U_CAPI void * uplug_getContext (UPlugData *plug)
 Return the plugin-specific context data. More...
 
U_CAPI void uplug_setContext (UPlugData *plug, void *context)
 Set the plugin-specific context data. More...
 
U_CAPI const char * uplug_getConfiguration (UPlugData *plug)
 Get the configuration string, if available. More...
 
U_CAPI UPlugDatauplug_nextPlug (UPlugData *prior)
 Return all currently installed plugins, from newest to oldest Usage Example: More...
 
U_CAPI UPlugDatauplug_loadPlugFromEntrypoint (UPlugEntrypoint *entrypoint, const char *config, UErrorCode *status)
 Inject a plugin as if it were loaded from a library. More...
 
U_CAPI UPlugDatauplug_loadPlugFromLibrary (const char *libName, const char *sym, const char *config, UErrorCode *status)
 Inject a plugin from a library, as if the information came from a config file. More...
 
U_CAPI void uplug_removePlug (UPlugData *plug, UErrorCode *status)
 Remove a plugin. More...
 

Detailed Description

C API: ICU Plugin API.

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:

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

myPlugin (UPlugData *plug, UPlugReason reason, UErrorCode *status) {
if(reason==UPLUG_REASON_QUERY) {
uplug_setPlugName(plug, "Simple Plugin");
} else if(reason==UPLUG_REASON_LOAD) {
... Set up some ICU things here....
} else if(reason==UPLUG_REASON_UNLOAD) {
... unload, clean up ...
}
return UPLUG_TOKEN;
}
uint32_t UPlugTokenReturn
Return value from a plugin entrypoint.
Definition: icuplug.h:151
UPlugReason
Reason code for the entrypoint's call.
Definition: icuplug.h:157
@ UPLUG_REASON_LOAD
The plugin is being loaded.
Definition: icuplug.h:159
@ UPLUG_REASON_UNLOAD
The plugin is being unloaded.
Definition: icuplug.h:160
@ UPLUG_REASON_QUERY
The plugin is being queried for info.
Definition: icuplug.h:158
struct UPlugData UPlugData
Typedef for opaque structure passed to/from a plugin.
Definition: icuplug.h:127
U_CAPI void uplug_setPlugName(UPlugData *plug, const char *name)
Set the human-readable name of this plugin.
U_CAPI void uplug_setPlugLevel(UPlugData *plug, UPlugLevel level)
Set the level of this plugin.
#define UPLUG_TOKEN
Random Token to identify a valid ICU plugin.
Definition: icuplug.h:136
@ UPLUG_LEVEL_HIGH
The plugin can run at any time.
Definition: icuplug.h:180
#define U_CAPI
This is used to declare a function as a public ICU C API.
Definition: umachine.h:110
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415

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.
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

Definition in file icuplug.h.

Macro Definition Documentation

◆ UPLUG_NAME_MAX

#define UPLUG_NAME_MAX   100

Max width of names, symbols, and configuration strings.

Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

Definition at line 142 of file icuplug.h.

◆ UPLUG_TOKEN

#define UPLUG_TOKEN   0x54762486

Random Token to identify a valid ICU plugin.

Plugins must return this from the entrypoint.

Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

Definition at line 136 of file icuplug.h.

Typedef Documentation

◆ UPlugData

typedef struct UPlugData UPlugData

Typedef for opaque structure passed to/from a plugin.

Use the APIs to access it.

Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

Definition at line 127 of file icuplug.h.

◆ UPlugEntrypoint

typedef UPlugTokenReturn() UPlugEntrypoint(UPlugData *plug, UPlugReason reason, UErrorCode *status)

Entrypoint for an ICU plugin.

Parameters
plugthe UPlugData handle.
reasonthe reason code for the entrypoint's call.
statusStandard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)
Returns
A valid plugin must return UPLUG_TOKEN
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

Definition at line 199 of file icuplug.h.

◆ UPlugTokenReturn

typedef uint32_t UPlugTokenReturn

Return value from a plugin entrypoint.

Must always be set to UPLUG_TOKEN

See also
UPLUG_TOKEN
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

Definition at line 151 of file icuplug.h.

Enumeration Type Documentation

◆ UPlugLevel

enum UPlugLevel

Level of plugin loading INITIAL: UNKNOWN QUERY: INVALID -> { LOW | HIGH } ERR -> INVALID.

Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview
Enumerator
UPLUG_LEVEL_INVALID 

The plugin is invalid, hasn't called uplug_setLevel, or can't load.

UPLUG_LEVEL_UNKNOWN 

The plugin is waiting to be installed.

UPLUG_LEVEL_LOW 

The plugin must be called before u_init completes.

UPLUG_LEVEL_HIGH 

The plugin can run at any time.

UPLUG_LEVEL_COUNT 

Number of known levels.

Internal:
Do not use. This API is for internal use only. The numeric value may change over time, see ICU ticket #12420.

Definition at line 176 of file icuplug.h.

◆ UPlugReason

Reason code for the entrypoint's call.

Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview
Enumerator
UPLUG_REASON_QUERY 

The plugin is being queried for info.

UPLUG_REASON_LOAD 

The plugin is being loaded.

UPLUG_REASON_UNLOAD 

The plugin is being unloaded.

UPLUG_REASON_COUNT 

Number of known reasons.

Internal:
Do not use. This API is for internal use only. The numeric value may change over time, see ICU ticket #12420.

Definition at line 157 of file icuplug.h.

Function Documentation

◆ uplug_getConfiguration()

U_CAPI const char * uplug_getConfiguration ( UPlugData plug)

Get the configuration string, if available.

The string is in the platform default codepage.

Parameters
plugplugin data handle
Returns
configuration string, or else null.
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_getContext()

U_CAPI void * uplug_getContext ( UPlugData plug)

Return the plugin-specific context data.

Parameters
plugplugin data handle
Returns
the context, or NULL if not set
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_getCurrentLevel()

U_CAPI UPlugLevel uplug_getCurrentLevel ( void  )

Get the lowest level of plug which can currently load.

For example, if UPLUG_LEVEL_LOW is returned, then low level plugins may load if UPLUG_LEVEL_HIGH is returned, then only high level plugins may load.

Returns
the lowest level of plug which can currently load
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_getLibrary()

U_CAPI void * uplug_getLibrary ( UPlugData plug)

Return the library used for this plugin, if known.

Plugins could use this to load data out of their

Parameters
plugplugin data handle
Returns
the library, or NULL
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_getLibraryName()

U_CAPI const char * uplug_getLibraryName ( UPlugData plug,
UErrorCode status 
)

Return the library name for this plugin, if known.

Parameters
plugplugin data handle
statuserror code
Returns
the library name, or NULL
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_getPlugLevel()

U_CAPI UPlugLevel uplug_getPlugLevel ( UPlugData plug)

Get the level of this plugin.

Parameters
plugplugin data handle
Returns
the level of this plugin
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_getPlugLoadStatus()

U_CAPI UErrorCode uplug_getPlugLoadStatus ( UPlugData plug)

Get plug load status.

Returns
The error code of this plugin's load attempt.
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_getPlugName()

U_CAPI const char * uplug_getPlugName ( UPlugData plug)

Get the human-readable name of this plugin.

Parameters
plugplugin data handle
Returns
the name of this plugin
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_getSymbolName()

U_CAPI const char * uplug_getSymbolName ( UPlugData plug)

Return the symbol name for this plugin, if known.

Parameters
plugplugin data handle
Returns
the symbol name, or NULL
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_loadPlugFromEntrypoint()

U_CAPI UPlugData * uplug_loadPlugFromEntrypoint ( UPlugEntrypoint entrypoint,
const char *  config,
UErrorCode status 
)

Inject a plugin as if it were loaded from a library.

This is useful for testing plugins. Note that it will have a 'NULL' library pointer associated with it, and therefore no llibrary will be closed at cleanup time. Low level plugins may not be able to load, as ordering can't be enforced.

Parameters
entrypointentrypoint to install
configuser specified configuration string, if available, or NULL.
statuserror result
Returns
the new UPlugData associated with this plugin, or NULL if error.
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_loadPlugFromLibrary()

U_CAPI UPlugData * uplug_loadPlugFromLibrary ( const char *  libName,
const char *  sym,
const char *  config,
UErrorCode status 
)

Inject a plugin from a library, as if the information came from a config file.

Low level plugins may not be able to load, and ordering can't be enforced.

Parameters
libNameDLL name to load
symsymbol of plugin (UPlugEntrypoint function)
configconfiguration string, or NULL
statuserror result
Returns
the new UPlugData associated with this plugin, or NULL if error.
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_nextPlug()

U_CAPI UPlugData * uplug_nextPlug ( UPlugData prior)

Return all currently installed plugins, from newest to oldest Usage Example:

UPlugData *plug = NULL;
while(plug=uplug_nextPlug(plug)) {
... do something with 'plug' ...
}
U_CAPI UPlugData * uplug_nextPlug(UPlugData *prior)
Return all currently installed plugins, from newest to oldest Usage Example:
#define NULL
Define NULL if necessary, to nullptr for C++ and to ((void *)0) for C.
Definition: utypes.h:188

Not thread safe- do not call while plugs are added or removed.

Parameters
priorpass in 'NULL' to get the first (most recent) plug, otherwise pass the value returned on a prior call to uplug_nextPlug
Returns
the next oldest plugin, or NULL if no more.
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_removePlug()

U_CAPI void uplug_removePlug ( UPlugData plug,
UErrorCode status 
)

Remove a plugin.

Will request the plugin to be unloaded, and close the library if needed

Parameters
plugplugin handle to close
statuserror result
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_setContext()

U_CAPI void uplug_setContext ( UPlugData plug,
void *  context 
)

Set the plugin-specific context data.

Parameters
plugplugin data handle
contextnew context to set
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_setPlugLevel()

U_CAPI void uplug_setPlugLevel ( UPlugData plug,
UPlugLevel  level 
)

Set the level of this plugin.

Parameters
plugplugin data handle
levelthe level of this plugin
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_setPlugName()

U_CAPI void uplug_setPlugName ( UPlugData plug,
const char *  name 
)

Set the human-readable name of this plugin.

Parameters
plugplugin data handle
namethe name of this plugin. The first UPLUG_NAME_MAX characters willi be copied into a new buffer.
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview

◆ uplug_setPlugNoUnload()

U_CAPI void uplug_setPlugNoUnload ( UPlugData plug,
UBool  dontUnload 
)

Request that this plugin not be unloaded at cleanup time.

This is appropriate for plugins which cannot be cleaned up.

See also
u_cleanup()
Parameters
plugplugin
dontUnloadset true if this plugin can't be unloaded
Internal:
Do not use. This API is for internal use only. ICU 4.4 Technology Preview