diff options
Diffstat (limited to 'frontends/riscos/distribution/3rdParty/Iconv/doc/API')
-rw-r--r-- | frontends/riscos/distribution/3rdParty/Iconv/doc/API | 132 |
1 files changed, 132 insertions, 0 deletions
diff --git a/frontends/riscos/distribution/3rdParty/Iconv/doc/API b/frontends/riscos/distribution/3rdParty/Iconv/doc/API new file mode 100644 index 000000000..13fa22fce --- /dev/null +++ b/frontends/riscos/distribution/3rdParty/Iconv/doc/API @@ -0,0 +1,132 @@ +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. |