C API: ICU Plugin API. More...

#include "unicode/utypes.h"

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

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
void	uplug_setPlugNoUnload (UPlugData *plug, UBool dontUnload)
	Request that this plugin not be unloaded at cleanup time. More...

void	uplug_setPlugLevel (UPlugData *plug, UPlugLevel level)
	Set the level of this plugin. More...

UPlugLevel	uplug_getPlugLevel (UPlugData *plug)
	Get the level of this plugin. More...

UPlugLevel	uplug_getCurrentLevel (void)
	Get the lowest level of plug which can currently load. More...

UErrorCode	uplug_getPlugLoadStatus (UPlugData *plug)
	Get plug load status. More...

void	uplug_setPlugName (UPlugData plug, const char name)
	Set the human-readable name of this plugin. More...

const char *	uplug_getPlugName (UPlugData *plug)
	Get the human-readable name of this plugin. More...

const char *	uplug_getSymbolName (UPlugData *plug)
	Return the symbol name for this plugin, if known. More...

const char *	uplug_getLibraryName (UPlugData plug, UErrorCode status)
	Return the library name for this plugin, if known. More...

void *	uplug_getLibrary (UPlugData *plug)
	Return the library used for this plugin, if known. More...

void *	uplug_getContext (UPlugData *plug)
	Return the plugin-specific context data. More...

void	uplug_setContext (UPlugData plug, void context)
	Set the plugin-specific context data. More...

const char *	uplug_getConfiguration (UPlugData *plug)
	Get the configuration string, if available. More...

UPlugData *	uplug_nextPlug (UPlugData *prior)
	Return all currently installed plugins, from newest to oldest Usage Example: More...

UPlugData *	uplug_loadPlugFromEntrypoint (UPlugEntrypoint entrypoint, const char config, UErrorCode *status)
	Inject a plugin as if it were loaded from a library. More...

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. More...

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:

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:

The plugin MUST always return UPLUG_TOKEN as a return value- to indicate that it is a valid plugin.
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.
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 143 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 137 of file icuplug.h.

Typedef Documentation

◆ UPlugEntrypoint

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

Entrypoint for an ICU plugin.

Parameters

plug	the UPlugData handle.
status	the plugin's extended status code.

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 196 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 152 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 177 of file icuplug.h.

◆ UPlugReason

enum 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 158 of file icuplug.h.

Function Documentation

◆ uplug_getConfiguration()

const char* uplug_getConfiguration ( UPlugData * plug )

Get the configuration string, if available.

The string is in the platform default codepage.

Parameters

plug	plugin 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()

void* uplug_getContext ( UPlugData * plug )

Return the plugin-specific context data.

Parameters

plug	plugin 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()

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()

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

plug	plugin 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()

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

Return the library name for this plugin, if known.

Parameters

plug	plugin data handle
status	error 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()

UPlugLevel uplug_getPlugLevel ( UPlugData * plug )

Get the level of this plugin.

Parameters

plug	plugin 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()

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()

const char* uplug_getPlugName ( UPlugData * plug )

Get the human-readable name of this plugin.

Parameters

plug	plugin 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()

const char* uplug_getSymbolName ( UPlugData * plug )

Return the symbol name for this plugin, if known.

Parameters

plug	plugin 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()

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

entrypoint	entrypoint to install
config	user specified configuration string, if available, or NULL.
status	error 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()

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

libName	DLL name to load
sym	symbol of plugin (UPlugEntrypoint function)
config	configuration string, or NULL
status	error 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()

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' ...
}

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

Parameters

prior pass 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()

void uplug_removePlug	(	UPlugData *	plug,
		UErrorCode *	status
	)

Remove a plugin.

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

Parameters

plug	plugin handle to close
status	error result

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

◆ uplug_setContext()

void uplug_setContext	(	UPlugData *	plug,
		void *	context
	)

Set the plugin-specific context data.

Parameters

plug	plugin data handle
context	new context to set

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

◆ uplug_setPlugLevel()

void uplug_setPlugLevel	(	UPlugData *	plug,
		UPlugLevel	level
	)

Set the level of this plugin.

Parameters

plug	plugin data handle
level	the level of this plugin

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

◆ uplug_setPlugName()

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

Set the human-readable name of this plugin.

Parameters

plug	plugin data handle
name	the 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()

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

plug	plugin
dontUnload	set true if this plugin can't be unloaded

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

Macros

Typedefs

Enumerations

Functions

Detailed Description

C API: ICU Plugin API

Loading and Configuration

Implementing a Plugin

Macro Definition Documentation

◆ UPLUG_NAME_MAX

◆ UPLUG_TOKEN

Typedef Documentation

◆ UPlugEntrypoint

◆ UPlugTokenReturn

Enumeration Type Documentation

◆ UPlugLevel

◆ UPlugReason

Function Documentation

◆ uplug_getConfiguration()

◆ uplug_getContext()

◆ uplug_getCurrentLevel()

◆ uplug_getLibrary()

◆ uplug_getLibraryName()

◆ uplug_getPlugLevel()

◆ uplug_getPlugLoadStatus()

◆ uplug_getPlugName()

◆ uplug_getSymbolName()

◆ uplug_loadPlugFromEntrypoint()

◆ uplug_loadPlugFromLibrary()

◆ uplug_nextPlug()

◆ uplug_removePlug()

◆ uplug_setContext()

◆ uplug_setPlugLevel()

◆ uplug_setPlugName()

◆ uplug_setPlugNoUnload()