summaryrefslogtreecommitdiff
path: root/frontends/riscos/distribution/3rdParty/Iconv/doc/API
diff options
context:
space:
mode:
Diffstat (limited to 'frontends/riscos/distribution/3rdParty/Iconv/doc/API')
-rw-r--r--frontends/riscos/distribution/3rdParty/Iconv/doc/API132
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.