Intlize C runtime interface

General

The functions described here are provided by the libintlize library, version 0 of the interface.

Type definitions

i5e_catalog_t

Actually, this is a pointer to a struct containing all information about the message catalog. This type should never be addressed directly, but only through the libintlize interface described here.

Functions

i5e_catalog_t i5e_create_catalog ( )

Description:

Use this function to obtain a libintlize catalog.

return value:

A valid catalog on successfull completion, NULL otherwise.

void i5e_free_catalog ( i5e_catalog_t catalog )

Description:

This function frees all memory associated with catalog.

catalog:

The catalog obtained with i5e_create_catalog.

int i5e_open( i5e_catalog_t *catalog, const char *lang, const char *path, const char *charset)

Description:

The file containing the requested translation is opened and copied into the catalog. If charset is not NULL, the messages will be converted to charset when accessed.

return value:

0 on successful completion, error code otherwise.

catalog:

The catalog obtained with i5e_create_catalog.

lang:

The language code of the translation.

path:

The colon separated search path to the message catalogs. A placeholder "%L" is replaced with lang, then the first 5 characters of lang, then the first 2 characters of lang.

charset:

The target charset of the catalog, or NULL if no conversion should be performed. If libintlize was built without iconv support, charset must be NULL.

void i5e_close ( i5e_catalog_t *catalog )

Description:

All memory associated with catalog is freed, but not catalog itself. To free the catalog call i5e_free_catalog.

catalog:

The catalog obtained with i5e_create_catalog.

const char * i5e_error_text ( int errnum )

Description:

Use this function to retrieve a descriptive message for errnum.

return value:

A descriptive message for errnum.

errnum:

The error code returned by i5e_open

const char * i5e_getid ( i5e_catalog_t catalog )

Description:

This is an access function for the ID of the catalog.

return value:

The ID of the catalog.

catalog:

The catalog obtained with i5e_create_catalog.

const char* i5e_getmsg(i5e_catalog_t catalog, int msgnum)

Description:

This function retrieves the translated messages for msgnum.

Return value:

The translated message.

catalog:

The catalog obtained with i5e_create_catalog.

msgnum:

The message number of the message as assigned by intlize.

Error codes

General

0: (Success)

No error occurred.

3: (Out of memory)

Allocating a chunk of memory failed.

6: (Argument error)

The arguments given to i5e_open failed a logical check due to one or more of the following:
Catalog is NULL.
Lang or path is NULL or an empty string.

File I/O

1: (File not found)

The file requested by lang and path does not exist or is not accessible.

2: (File could not be opened)

The file is not accessible.

4: (Wrong file type)

The file exists and is accessible, but it is not an intlize file.

5: (Unexpected end of file)

The file ended prematurely.

Charset conversion

7: (Unknown encoding)

The encoding of the catalog is not known to intlize.

8: (No suitable converter found)

Libiconv cannot convert to the charset requested by charset.

9: (Charset conversion not implemented)

A conversion to charset is requested, but libintlize was built without libiconv support.