PxTranslateSet()

Install a new character set translation

Synopsis:

#include <photon/PxProto.h>

struct PxTransCtrl *PxTranslateSet( 
                        struct PxTransCtrl *ctrl, 
                        const char *charset);

Library:

phexlib

Description:

PxTranslateSet() installs a new character set translation. The ctrl argument, if non-NULL, is a pointer to the control structure for a character set translation returned from a previous call to PxTranslateSet(). The translation it specifies is disabled, and any resources it uses are released.

PxTranslateSet() searches the /usr/photon/translations/charsets configuration file for the translation specified by charset; it may be an entry section name, one of the Alias entries or the Description entry. The charset name is usually selected by the user (see PxTranslateList()) or from an external specification (for example, the charset= field of the Content-type MIME / HTTP header).

If the specified charset is found, resources are allocated as required, and any necessary data files are loaded into memory. The following special values of charset are recognized:

• NULL — release any resources used by the existing encoding scheme without installing a new translation
• an empty string ("") — install a simple byte-copy scheme

The translation routines are provided in the Photon library phexlib, with prototypes in <photon/PxProto.h>.

Returns:

A pointer to a translation control structure, which should be passed to subsequent translation routines and to future calls to PxTranslateSet()

Examples:

This sample program converts characters from stdin (encoded in a character set specified to the program as its only argument) to stdout (in UTF-8). Note that a 256-byte buffer is allocated for input and a MB_LEN_MAX * 256 bytes (the worst-case UTF-8 encoding for that number of input bytes) created for output. Alternatively, a call to PxTranslateToUTF() with a NULL source buffer could be used to work out the bytes-per-character requirements (we exploit the fact that we already know this number for UTF-8 encoding).

#include <stdio.h>
#include <stdlib.h>
#include <photon/PxProto.h>

#define BUFFER 256

int main(int argc, char *argv[])
{
    struct PxTransCtrl *trans;
    char   *code, *utf;
    int    srclen, dstlen;

    if (argc < 2) {
        fprintf(stderr, "specify translation charset\n");
        return(1);
    }
    if ((trans = PxTranslateSet(NULL, argv[1])) == NULL) {
        fprintf(stderr, "unknown translation charset '%s'\n",
                argv[1]);
        return(1);
    }
    if ((code = malloc(BUFFER)) == NULL || 
        (utf = malloc(BUFFER * MB_LEN_MAX)) == NULL) {
        fprintf(stderr, 
            "unable to allocate %d-byte translation buffers\n", 
            BUFFER);
        return(1);
    }
    
    while ((srclen = fread(code, sizeof(char), BUFFER, 
                           stdin))) {
        if ((dstlen = PxTranslateStateToUTF(trans, code,
                          srclen, NULL, utf,
                          BUFFER * MB_LEN_MAX)) == -1) {
            fprintf(stderr, "invalid encoding sequence\n");
            return(1);
        }
        fwrite(utf, dstlen, sizeof(char), stdout);
    }

    return EXIT_SUCCESS;
}

Classification:

Photon

See also:

PxTranslateList(), PxTranslateFromUTF(), PxTranslateStateFromUTF(), PxTranslateStateToUTF(), PxTranslateToUTF(), PxTranslateUnknown()

Unicode Multilingual Support in the Photon Programmer's Guide