2.11 Unicode support

Starting with version 7.0, Unicode is now fully supported by Hollywood. By default, Hollywood always runs in Unicode mode now which means that all strings that your plugin gets from Hollywood or that your plugin passes to Hollywood must be in the UTF-8 encoding. This even applies to standard C functions in CRTBase like fopen(), stat(), rename(), remove(), etc. Normally, those functions from the C runtime library aren't UTF-8 compatible on all systems (most notably they aren't UTF-8 compatible on Windows and AmigaOS), but when calling those standard C runtime functions through Hollywood's CRTBase they will expect UTF-8 strings.

Note that scripts may explicitly request running in compatibility mode which puts Hollywood back into ISO 8859-1 mode which was used before Hollywood 7.0. In that case, all strings that your plugin gets from Hollywood or passes to Hollywood must be in ISO 8859-1 encoding. Supporting this compatibility mode can greatly increase the complexity of your plugin which is why you should think about whether your plugin really needs to support this mode or if you just make Hollywood running in Unicode mode a requirement for your plugin.

If you do decide to support compatibility mode in your plugin, the recommended way to detect the compatibility mode is to install a callback for the HWCB_ENCODINGCHANGE type in your InitPlugin() implementation using hw_RegisterCallback(). This callback will then be called if a script explicitly requests running in compatibility mode.

Note that if you want your plugin to be compatible with Hollywood versions older than 7.0, you have to support the ISO 8859-1 compatibility mode as well of course, because before Hollywood 7.0 all strings were in ISO 8859-1 encoding anyway.

Here's how you could deal with both cases in your InitPlugin() implementation. We first check the Hollywood version. If it is older than 7.0, we run in the ISO 8859-1 encoding. If it is at least 7.0, we install an encoding change callback to find out whether Hollywood is running in compatibility mode or UTF-8 mode. Here is the code:

 
// we store the encoding used by Hollywood here
static int useencoding;

// this callback will be run if the encoding changes; note that this
// will never be called more than once; the encoding can only change
// during Hollywood's program startup, not on the fly!
static SAVEDS void encodingchange(int encoding, APTR userdata)
{
    useencoding = encoding;
}

HW_EXPORT int InitPlugin(hwPluginBase *self, hwPluginAPI *cl, STRPTR
    path)
{
    // on Hollywood 7 or better, UTF-8 is the default encoding whereas
    // older version use ISO 8859-1 instead
    if(self->hw_Version > 6) {
        useencoding = HWOS_ENCODING_UTF8;
    } else {
        useencoding = HWOS_ENCODING_ISO8859_1;
    }

    // do initialization here
    ....

    // if we are on Hollywood 7 or better, let us know if the script
    // requests compatibility mode
    if(hwcl->hwVersion > 6) {
        hwcl->SysBase->hw_RegisterCallback(HWCB_ENCODINGCHANGE, (APTR)
            encodingchange, NULL);
    }

    return TRUE;
}

To convert between different encodings there is a convenience function named hw_ConvertString(). See hw_ConvertString for details.

Show TOC