Installing String Converters

The default behavior of the run time can be changed by providing application-specific string converters. If you install such converters, all Slice strings will be passed to the appropriate converter when they are marshaled and unmarshaled. Therefore, the string converters allow you to convert all strings transparently into their native representation without having to insert explicit conversion calls whenever a string crosses a Slice interface boundary.

You can install string converters by calling IceUtil::setProcessStringConverter for the narrow string converter, and IceUtil::setProcessWstringConverter for the wide string converter. Any strings that use the default (std::string) mapping are passed through the specified narrow string converter and any strings that use the wide (std::wstring) mapping are passed through the specified wide string converter.

You can also retrieve the previously installed string converters (or default string converters) with IceUtil::getProcessStringConverter and  IceUtil::getProcessWstringConverter. The default narrow string converter is null, meaning all std::strings use the UTF-8 encoding.

The string converters are defined as follows:

namespace IceUtil {

class UTF8Buffer {
    virtual Byte* getMoreBytes(size_t howMany, Byte* firstUnused) = 0;
    virtual ~UTF8Buffer() {}

template<typename charT>
class BasicStringConverter : public IceUtil::Shared {
    virtual Byte* toUTF8(const charT* sourceStart, const charT* sourceEnd,
                         UTF8Buffer&) const = 0;

    virtual void fromUTF8(const Byte* sourceStart,
                          const Byte* sourceEnd,
                          std::basic_string<charT>& target) const;

typedef BasicStringConverter<char> StringConverter;
typedef IceUtil::Handle<StringConverter> StringConverterPtr;

typedef BasicStringConverter<wchar_t> WstringConverter;
typedef IceUtil::Handle<WstringConverter> WstringConverterPtr;
StringConverterPtr getProcessStringConverter();
void setProcessStringConverter(const StringConverterPtr&);

WstringConverterPtr getProcessWstringConverter();
void setProcessWstringConverter(const WstringConverterPtr&);

As you can see, both narrow and wide string converters are simply templates with either a narrow or a wide character (char or wchar_t) as the template parameter.

Each communicator caches the narrow string converter and wide string converter installed when this communicator is initialized.

You should always install your string converters before creating your communicator(s). When using a plugin to set your string converters, you need to set the string converters in the constructor of your plugin class (which is executed when the plugin is loaded) and not in the initialization function of the plugin class (which is executed after the communicator has read and cached the process-wide string converters).

See Also