15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)****************************************************************************** 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)* 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)* Copyright (C) 2009-2012, International Business Machines 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)* Corporation and others. All Rights Reserved. 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)* 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)****************************************************************************** 8868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles)* 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)* FILE NAME : icuplug.h 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)* 117dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch* Date Name Description 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)* 10/29/2009 sl New. 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)****************************************************************************** 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)*/ 15c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 172a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * \file 182a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * \brief C API: ICU Plugin API 192a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <h2>C API: ICU Plugin API</h2> 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <p>C API allowing run-time loadable modules that extend or modify ICU functionality.</p> 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 24eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * <h3>Loading and Configuration</h3> 25eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <p>At ICU startup time, the environment variable "ICU_PLUGINS" will be 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * queried for a directory name. If it is not set, the preprocessor symbol 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * "DEFAULT_ICU_PLUGINS" will be checked for a default value.</p> 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <p>Within the above-named directory, the file "icuplugins##.txt" will be 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * opened, if present, where ## is the major+minor number of the currently 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * running ICU (such as, 44 for ICU 4.4, thus icuplugins44.txt)</p> 332a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <p>The configuration file has this format:</p> 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <ul> 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <li>Hash (#) begins a comment line</li> 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 392a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * <li>Non-comment lines have two or three components: 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * LIBRARYNAME ENTRYPOINT [ CONFIGURATION .. ]</li> 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <li>Tabs or spaces separate the three items.</li> 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <li>LIBRARYNAME is the name of a shared library, either a short name if 457d4cd473f85ac64c3747c96c277f9e506a0d2246Torne (Richard Coles) * it is on the loader path, or a full pathname.</li> 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <li>ENTRYPOINT is the short (undecorated) symbol name of the plugin's 48a93a17c8d99d686bd4a1511e5504e5e6cc9fcadfTorne (Richard Coles) * entrypoint, as above.</li> 49c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * 502a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * <li>CONFIGURATION is the entire rest of the line . It's passed as-is to 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the plugin.</li> 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * </ul> 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <p>An example configuration file is, in its entirety:</p> 55eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * \code 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * # this is icuplugins44.txt 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * testplug.dll myPlugin hello=world 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * \endcode 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <p>Plugins are categorized as "high" or "low" level. Low level are those 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * which must be run BEFORE high level plugins, and before any operations 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * which cause ICU to be 'initialized'. If a plugin is low level but 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * causes ICU to allocate memory or become initialized, that plugin is said 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * to cause a 'level change'. </p> 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <p>At load time, ICU first queries all plugins to determine their level, 672a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * then loads all 'low' plugins first, and then loads all 'high' plugins. 682a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * Plugins are otherwise loaded in the order listed in the configuration file.</p> 692a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * 702a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * <h3>Implementing a Plugin</h3> 712a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * \code 722a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * U_CAPI UPlugTokenReturn U_EXPORT2 732a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * myPlugin (UPlugData *plug, UPlugReason reason, UErrorCode *status) { 742a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * if(reason==UPLUG_REASON_QUERY) { 752a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * uplug_setPlugName(plug, "Simple Plugin"); 762a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * uplug_setPlugLevel(plug, UPLUG_LEVEL_HIGH); 772a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * } else if(reason==UPLUG_REASON_LOAD) { 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * ... Set up some ICU things here.... 792a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * } else if(reason==UPLUG_REASON_UNLOAD) { 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * ... unload, clean up ... 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * } 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * return UPLUG_TOKEN; 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * } 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * \endcode 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <p>The UPlugData* is an opaque pointer to the plugin-specific data, and is 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * used in all other API calls.</p> 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 8990dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * <p>The API contract is:</p> 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <ol><li>The plugin MUST always return UPLUG_TOKEN as a return value- to 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * indicate that it is a valid plugin.</li> 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <li>When the 'reason' parameter is set to UPLUG_REASON_QUERY, the 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * plugin MUST call uplug_setPlugLevel() to indicate whether it is a high 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * level or low level plugin.</li> 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <li>When the 'reason' parameter is UPLUG_REASON_QUERY, the plugin 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * SHOULD call uplug_setPlugName to indicate a human readable plugin name.</li></ol> 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * \internal ICU 4.4 Technology Preview 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef ICUPLUG_H 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define ICUPLUG_H 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "unicode/utypes.h" 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* === Basic types === */ 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef U_HIDE_INTERNAL_API 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @{ 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Opaque structure passed to/from a plugin. 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * use the APIs to access it. 1182a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * @internal ICU 4.4 Technology Preview 1192a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) */ 1202a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 1212a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)struct UPlugData; 1222a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)typedef struct UPlugData UPlugData; 1232a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 1242a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)/** @} */ 1252a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 1262a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)/** 1272a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * Random Token to identify a valid ICU plugin. Plugins must return this 1282a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * from the entrypoint. 1292a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * @internal ICU 4.4 Technology Preview 1302a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) */ 1312a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)#define UPLUG_TOKEN 0x54762486 1322a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 1342a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * Max width of names, symbols, and configuration strings 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define UPLUG_NAME_MAX 100 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 1412a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * Return value from a plugin entrypoint. 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Must always be set to UPLUG_TOKEN 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @see UPLUG_TOKEN 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef uint32_t UPlugTokenReturn; 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Reason code for the entrypoint's call 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef enum { 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) UPLUG_REASON_QUERY = 0, /**< The plugin is being queried for info. **/ 1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) UPLUG_REASON_LOAD = 1, /**< The plugin is being loaded. **/ 1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) UPLUG_REASON_UNLOAD = 2, /**< The plugin is being unloaded. **/ 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) UPLUG_REASON_COUNT /**< count of known reasons **/ 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} UPlugReason; 1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 16190dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * Level of plugin loading 16290dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * INITIAL: UNKNOWN 1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * QUERY: INVALID -> { LOW | HIGH } 1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * ERR -> INVALID 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef enum { 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) UPLUG_LEVEL_INVALID = 0, /**< The plugin is invalid, hasn't called uplug_setLevel, or can't load. **/ 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) UPLUG_LEVEL_UNKNOWN = 1, /**< The plugin is waiting to be installed. **/ 1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) UPLUG_LEVEL_LOW = 2, /**< The plugin must be called before u_init completes **/ 1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) UPLUG_LEVEL_HIGH = 3, /**< The plugin can run at any time. **/ 1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) UPLUG_LEVEL_COUNT /**< count of known reasons **/ 1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} UPlugLevel; 1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Entrypoint for an ICU plugin. 1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param plug the UPlugData handle. 1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param status the plugin's extended status code. 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return A valid plugin must return UPLUG_TOKEN 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef UPlugTokenReturn (U_EXPORT2 UPlugEntrypoint) ( 1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) UPlugData *plug, 1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) UPlugReason reason, 1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) UErrorCode *status); 1865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* === Needed for Implementing === */ 1885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 1905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Request that this plugin not be unloaded at cleanup time. 1915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * This is appropriate for plugins which cannot be cleaned up. 1925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @see u_cleanup() 1935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param plug plugin 1945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param dontUnload set true if this plugin can't be unloaded 1955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 1965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)U_INTERNAL void U_EXPORT2 1985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)uplug_setPlugNoUnload(UPlugData *plug, UBool dontUnload); 1997dbb3d5cf0c15f500944d211057644d6a2f37371Ben Murdoch 200c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)/** 2012a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * Set the level of this plugin. 20290dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * @param plug plugin data handle 203c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * @param level the level of this plugin 20490dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * @internal ICU 4.4 Technology Preview 205eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch */ 206eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen MurdochU_INTERNAL void U_EXPORT2 2072a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)uplug_setPlugLevel(UPlugData *plug, UPlugLevel level); 2082a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 2092a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)/** 2105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Get the level of this plugin. 2115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param plug plugin data handle 2125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return the level of this plugin 2135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 2145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)U_INTERNAL UPlugLevel U_EXPORT2 2165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)uplug_getPlugLevel(UPlugData *plug); 2175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 2195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Get the lowest level of plug which can currently load. 2205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * For example, if UPLUG_LEVEL_LOW is returned, then low level plugins may load 2215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * if UPLUG_LEVEL_HIGH is returned, then only high level plugins may load. 2225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return the lowest level of plug which can currently load 2235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 2245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)U_INTERNAL UPlugLevel U_EXPORT2 2265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)uplug_getCurrentLevel(void); 2275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 2305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Get plug load status 2315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return The error code of this plugin's load attempt. 2325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 2335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)U_INTERNAL UErrorCode U_EXPORT2 2355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)uplug_getPlugLoadStatus(UPlugData *plug); 2365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 2385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Set the human-readable name of this plugin. 2395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param plug plugin data handle 2405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param name the name of this plugin. The first UPLUG_NAME_MAX characters willi be copied into a new buffer. 2415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 2425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)U_INTERNAL void U_EXPORT2 2445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)uplug_setPlugName(UPlugData *plug, const char *name); 2455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 2475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Get the human-readable name of this plugin. 2485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param plug plugin data handle 2495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return the name of this plugin 2505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 2515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)U_INTERNAL const char * U_EXPORT2 2535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)uplug_getPlugName(UPlugData *plug); 2545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 2565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Return the symbol name for this plugin, if known. 2575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param plug plugin data handle 2585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return the symbol name, or NULL 2595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 2605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)U_INTERNAL const char * U_EXPORT2 2625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)uplug_getSymbolName(UPlugData *plug); 2635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 2655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Return the library name for this plugin, if known. 2665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param plug plugin data handle 2675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param status error code 2685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return the library name, or NULL 269a93a17c8d99d686bd4a1511e5504e5e6cc9fcadfTorne (Richard Coles) * @internal ICU 4.4 Technology Preview 2702a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) */ 2712a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)U_INTERNAL const char * U_EXPORT2 2722a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)uplug_getLibraryName(UPlugData *plug, UErrorCode *status); 2732a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 2742a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)/** 2752a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * Return the library used for this plugin, if known. 2762a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * Plugins could use this to load data out of their 2772a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * @param plug plugin data handle 2785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return the library, or NULL 2795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 2805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)U_INTERNAL void * U_EXPORT2 2825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)uplug_getLibrary(UPlugData *plug); 2835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 2855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Return the plugin-specific context data. 2865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param plug plugin data handle 2875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return the context, or NULL if not set 2885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 2895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 2905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)U_INTERNAL void * U_EXPORT2 2915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)uplug_getContext(UPlugData *plug); 2922a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 2935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 2945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Set the plugin-specific context data. 2955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param plug plugin data handle 296a93a17c8d99d686bd4a1511e5504e5e6cc9fcadfTorne (Richard Coles) * @param context new context to set 2972a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * @internal ICU 4.4 Technology Preview 2982a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) */ 2992a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)U_INTERNAL void U_EXPORT2 3002a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)uplug_setContext(UPlugData *plug, void *context); 3012a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3022a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3032a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)/** 3042a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * Get the configuration string, if available. 3055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The string is in the platform default codepage. 3062a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * @param plug plugin data handle 3072a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * @return configuration string, or else null. 3085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @internal ICU 4.4 Technology Preview 3095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 3105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)U_INTERNAL const char * U_EXPORT2 3115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)uplug_getConfiguration(UPlugData *plug); 3125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 3145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Return all currently installed plugins, from newest to oldest 3155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Usage Example: 3165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * \code 3175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * UPlugData *plug = NULL; 3182a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * while(plug=uplug_nextPlug(plug)) { 3192a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * ... do something with 'plug' ... 3205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * } 3215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * \endcode 3225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Not thread safe- do not call while plugs are added or removed. 323eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * @param prior pass in 'NULL' to get the first (most recent) plug, 324eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * otherwise pass the value returned on a prior call to uplug_nextPlug 325eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * @return the next oldest plugin, or NULL if no more. 326eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * @internal ICU 4.4 Technology Preview 327eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch */ 328eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen MurdochU_INTERNAL UPlugData* U_EXPORT2 329eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdochuplug_nextPlug(UPlugData *prior); 3302a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3312a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)/** 3322a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * Inject a plugin as if it were loaded from a library. 3332a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * This is useful for testing plugins. 334eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * Note that it will have a 'NULL' library pointer associated 335eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * with it, and therefore no llibrary will be closed at cleanup time. 336eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * Low level plugins may not be able to load, as ordering can't be enforced. 337eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * @param entrypoint entrypoint to install 338c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * @param config user specified configuration string, if available, or NULL. 339c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * @param status error result 340c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * @return the new UPlugData associated with this plugin, or NULL if error. 341c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) * @internal ICU 4.4 Technology Preview 342eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch */ 343eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen MurdochU_INTERNAL UPlugData* U_EXPORT2 344eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdochuplug_loadPlugFromEntrypoint(UPlugEntrypoint *entrypoint, const char *config, UErrorCode *status); 345eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 346eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 347eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch/** 348eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * Inject a plugin from a library, as if the information came from a config file. 349eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * Low level plugins may not be able to load, and ordering can't be enforced. 350eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * @param libName DLL name to load 351eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * @param sym symbol of plugin (UPlugEntrypoint function) 352eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * @param config configuration string, or NULL 353eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * @param status error result 35490dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * @return the new UPlugData associated with this plugin, or NULL if error. 35590dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * @internal ICU 4.4 Technology Preview 356eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch */ 357eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen MurdochU_INTERNAL UPlugData* U_EXPORT2 358eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdochuplug_loadPlugFromLibrary(const char *libName, const char *sym, const char *config, UErrorCode *status); 359eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch 360eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch/** 361eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * Remove a plugin. 362eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * Will request the plugin to be unloaded, and close the library if needed 363eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * @param plug plugin handle to close 364eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * @param status error result 365eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch * @internal ICU 4.4 Technology Preview 366eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch */ 367eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen MurdochU_INTERNAL void U_EXPORT2 368eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdochuplug_removePlug(UPlugData *plug, UErrorCode *status); 369eb525c5499e34cc9c4b825d6d9e75bb07cc06aceBen Murdoch#endif /* U_HIDE_INTERNAL_API */ 3705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif 3725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)