Proposal for iconv implementation using UnicodeLib:
===================================================

The UnicodeLib library provided with Acorn/Castle C/C++ tools appears to
implement most of what is required for a sensible iconv implementation.
Therefore, it makes sense to produce a wrapper around this functionality
which exposes the iconv API.


Format of distribution:
=======================

As this functionality is of likely use to a number of applications, a RISC OS
module seems a sensible option. The advantages of this approach are clear - 
the ability to share the resource among many clients which leads to reduced 
binary size and memory usage.


Why not use GNU libiconv?
=========================

GNU iconv, once compiled to a library (including all default encodings)
amounts to approximately 1MB of data. Linking such a large library into an
application simply to provide character set conversion seems like overkill.
Obviously this issue would be irrelevant were there a workable shared library
solution for RISC OS.

By implementing iconv in a module, all a client application need do is link 
against a thin stubs veneer. Also, all static data (encoding tables etc) is
stored in the !Unicode resource, thus making the module size minimal also.


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
  
  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 = buffer length
            r3 -> currently selected encoding name, or 0 if none selected
  
  On Exit:  r2 = required size of buffer if r1 = 0 on entry,
                 or length of data placed in buffer

  Menu titles are direct form text buffers. Menu entries are indirect text.
  Titles may be modified in place, as they are local to the current menu
  block. Entries make use of global string data stored within the Iconv
  module. Should you wish to modify any menu entry, you should create your
  own buffer and update the pointer to text in the menu appropriately.
  Under no circumstances should the textual content generated by the Iconv
  module be modified. Doing so will corrupt all subsequent uses of an
  encoding menu.


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.


Further Reading:
================

Uni->iconv - An overview of the differences between the data provided by the 
             !Unicode resource and that used in GNU libiconv.

Japanese Support in RISC OS (and an overview of UnicodeLib)
at http://www.iyonix.com/32bit