The Ice run time includes a plug-in that supports conversion between UTF-8 and native encodings on Unix and Windows platforms. You can use this plug-in to install converters for narrow and wide strings into the communicator of an existing program. This feature is primarily intended for use in scripting language extensions such as Ice for Python; if you need to use string converters in your C++ application, we recommend using the technique described in Installing String Converters instead.

Note that an application must be designed to operate correctly in the presence of a string converter. A string converter assumes that it converts strings in the native encoding into the UTF-8 encoding, and vice versa. An application that performs its own conversions on strings that cross a Slice interface boundary can cause encoding errors when those strings are processed by a converter.

Configuring the Ice String Converter Plug-in

You can install the plug-in using a configuration property like the one shown below:

Ice.Plugin.Converter=Ice:createStringConverter iconv=encoding[,encoding] windows=code-page

You can use any name you wish for the plug-in; in this example, we used Converter. The first component of the property value represents the plug-in's entry point, which includes the abbreviated name of the shared library or DLL (Ice) and the name of a factory function (createStringConverter).

The plug-in accepts the following arguments:

• iconv=encoding[,encoding] 
  This argument is optional on Unix platforms and ignored on Windows platforms. If specified, it defines the iconv names of the narrow string encoding and the optional wide-string encoding. If this argument is not specified, the plug-in installs a narrow string converter that uses the default locale-dependent encoding.

• windows=code-page
  This argument is required on Windows platforms and ignored on Unix platforms. The code-page value represents a code page number, such as 1252.

The plug-in's argument semantics are designed so that the same configuration property can be used on both Windows and Unix platforms, as shown in the following example:

Ice.Plugin.Converter=Ice:createStringConverter iconv=ISO8859-1 windows=1252

If the configuration file containing this property is shared by programs in multiple implementation languages, you can use an alternate syntax that is loaded only by the Ice for C++ run time:

Ice.Plugin.Converter.cpp=Ice:createStringConverter iconv=ISO8859-1 windows=1252

See Also

• UTF-8 Conversion
• Installing String Converters
• Plug-in Configuration
• Ice Plug-In Properties