You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
133 lines
4.1 KiB
133 lines
4.1 KiB
Iconv Module API
|
|
================
|
|
|
|
If using C, then you really should be using the libiconv stubs provided
|
|
(or UnixLib, if appropriate). See the iconv.h header file for further
|
|
documentation of these calls.
|
|
|
|
Iconv_Open (&57540)
|
|
-------------------
|
|
|
|
Create a conversion descriptor
|
|
|
|
On Entry: r0 -> string containing name of destination encoding (eg "UTF-8")
|
|
r1 -> string containing name of source encoding (eg "CP1252")
|
|
|
|
On Exit: r0 = conversion descriptor
|
|
All others preserved
|
|
|
|
Either encoding name may have a number of parameters appended to them.
|
|
Parameters are separated by a pair of forward-slashes ("//").
|
|
Currently defined parameters are:
|
|
|
|
Parameter: Destination: Source:
|
|
|
|
TRANSLIT Transliterate unrepresentable None
|
|
output.
|
|
|
|
The conversion descriptor is an opaque value. The user should not,
|
|
therefore, assume anything about its meaning, nor modify it in any way.
|
|
Doing so is guaranteed to result in undefined behaviour.
|
|
|
|
|
|
Iconv_Iconv (&57541)
|
|
--------------------
|
|
|
|
This SWI is deprecated and Iconv_Convert should be used instead.
|
|
|
|
|
|
Iconv_Close (&57542)
|
|
--------------------
|
|
|
|
Destroy a conversion descriptor
|
|
|
|
On Entry: r0 = conversion descriptor to destroy
|
|
|
|
On Exit: r0 = 0
|
|
All others preserved
|
|
|
|
|
|
Iconv_Convert (&57543)
|
|
---------------------
|
|
|
|
Convert a byte sequence to another encoding
|
|
|
|
On Entry: r0 = conversion descriptor returned by Iconv_Open
|
|
r1 -> input buffer (or NULL to reset encoding context)
|
|
r2 = length of buffer pointed to by r1
|
|
r3 -> output buffer
|
|
r4 = length of buffer pointed to by r3
|
|
|
|
On Exit: r0 = number of non-reversible conversions performed (always 0)
|
|
r1 -> updated input buffer pointer (after last input read)
|
|
r2 = number of bytes remaining in input buffer
|
|
r3 -> updated output buffer pointer (i.e. end of output)
|
|
r4 = number of free bytes in the output buffer
|
|
All others preserved
|
|
|
|
Note that all strings should be NUL-terminated so, if calling from BASIC,
|
|
some terminating character munging may be needed.
|
|
|
|
|
|
Errors:
|
|
|
|
Should an error occur, the SWI will return with V set and r0 -> error buffer.
|
|
Note that only the error number will be filled in and may be one of:
|
|
|
|
ICONV_NOMEM (&81b900)
|
|
ICONV_INVAL (&81b901)
|
|
ICONV_2BIG (&81b902)
|
|
ICONV_ILSEQ (&81b903)
|
|
|
|
These map directly to the corresponding C errno values.
|
|
|
|
|
|
Iconv_CreateMenu (&57544)
|
|
-------------------------
|
|
|
|
Create a menu data structure containing all available encodings.
|
|
|
|
On Entry: r0 = flags. All bits reserved, must be 0
|
|
r1 -> buffer, or 0 to read required length
|
|
r2 = length of buffer in r1
|
|
r3 -> currently selected encoding name, or 0 if none selected
|
|
r4 -> buffer for indirected data, or 0 to read length
|
|
r5 = length of buffer in r4
|
|
|
|
On Exit: r2 = required size of buffer in r1 if r1 = 0 on entry,
|
|
or length of data placed in buffer
|
|
r5 = required size of buffer in r4 if r4 = 0 on entry,
|
|
or length of data placed in buffer
|
|
|
|
Menu titles are direct form text buffers. Menu entries are indirect text.
|
|
Entry text is stored in the buffer pointed to by R4 on entry to this call.
|
|
|
|
|
|
Iconv_DecodeMenu (&57545)
|
|
-------------------------
|
|
|
|
Decode a selection in a menu generated by Iconv_CreateMenu.
|
|
Places the corresponding encoding name in the result buffer.
|
|
|
|
On Entry: r0 = flags. All bits reserved, must be 0
|
|
r1 -> menu definition
|
|
r2 -> menu selections, as per Wimp_Poll
|
|
r3 -> buffer for result or 0 to read required length
|
|
r4 = buffer length
|
|
|
|
On Exit: r4 = required size of buffer if r3 = 0 on entry,
|
|
or length of data placed in buffer (0 if no selected
|
|
encoding)
|
|
|
|
The menu selections block pointed to by r2 on entry should be based at
|
|
the root of the encodings menu structure (i.e. index 0 in the block
|
|
should correspond to the selection in the main encoding menu).
|
|
|
|
This call will update the selection status of the menu(s) appropriately.
|
|
|
|
|
|
Example Code:
|
|
=============
|
|
|
|
Example code may be found in the IconvEg BASIC file.
|