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.