used to specify which charset the application uses. More...

#include <arm4.h>

Data Fields
arm_subbuffer_t	header
arm_charset_t	charset
arm_int32_t	flags

Detailed Description

used to specify which charset the application uses.

Applications may specify on arm_register_application() the character set encoding for all strings passed by the application. An ARM library must support certain encodings, depending on the platform. The application may always use one of the mandatory encodings. The <arm4.h> file defines names of the form ARM_CHARSET_* for all the mandatory encodings. The application may optionally ask the ARM library if another encoding is supported using arm_is_charset_supported().

When the application registers with arm_register_application(), it may optionally provide the Character Set Encoding sub-buffer. In the sub-buffer, the application specifies the MIBenum value of a character set encoding that has been assigned by the IANA (Internet Assigned Numbers Authority - see www.iana.org). The MIBenum value in the sub-buffer should only be either a mandatory encoding for the platform or a MIBenum value for which support has been verified using arm_is_charset_supported().

The encoding must comply with the following constraints:

The character set must not contain any embedded null bytes. Exceptions are permitted for character sets that have fixed-length characters (e.g., two bytes) and that do not allow a character of all zeros (e.g., 0x0000). These include UTF-16LE, UTF-16BE, and UTF-16 (MIBenum values 1013, 1014, 1015). For these encodings, there will be a convention that a character of all zeros is the null-termination character.
No more than three bytes may be used to encode each character.

For any encodings that are of a fixed size greater than one byte, such as UTF-16 (all characters are two bytes in length), the characters must be aligned on the natural boundary for the system (e.g., two-byte characters on a 16-bit boundary, etc.).

If an ARM implementation supports characters that are longer than one byte, the application and implementation are both responsible to cast (virtually, at least) the characters to wide characters, but the function signature does not change. For example, if UTF-16 is supported, the application must write pairs of characters into the arm_char_t* array (there would always be an even number of characters), and the implementation must process the data in pairs (looking for 0x0000 as a termination character rather than 0x00, for example).