
<sect1 id="api">
<title>API</title>
<para>
	The C library installed along with xls2xml have only one function: xls2xml:
</para>
<funcsynopsis>
	<funcsynopsisinfo>#include &lt;xmsfilters/xls2xml.h></funcsynopsisinfo>
	<funcdef>int <function>xls2xml</function></funcdef>
	<paramdef>COLEFILE *<parameter>colefile</parameter></paramdef>
	<paramdef>xmlDocPtr *<parameter>p_xml_doc</parameter></paramdef>
	<paramdef>int <parameter>extract_level</parameter></paramdef>
	<paramdef>int <parameter>refmode</parameter></paramdef>
</funcsynopsis>
<para>
	It reads the file <parameter>colefile</parameter>, which was generated by Microsoft Excel, and express its content in the XML tree <parameter>p_xml_doc</parameter>, using the reference mode <parameter>refmode</parameter> and extracting so much content as specified by <parameter>extract_level</parameter>.
</para>
<para>
	The <parameter>colefile</parameter> must be the file "/Workbook" or "/Book" in the file system which is in the file created by Microsoft Excel. It must be open (you can use cole functions to mount such file system and then open that file).
</para>
<para>
	The result is stored in a XML tree <parameter>p_xml_doc</parameter>. It can be manipulated with some libxml functions in order to generate an actual file or to browse through.
</para>
<para>
	The <parameter>extract_level</parameter> can be EXTRACT_ALL or EXTRACT_NORMAL, in order to extract all the content or just the normal content.
</para>
<para>
	The <parameter>refmode</parameter> can be one of REFMODE_A1, REFMODE_R1C1 or REFMODE_AS_IS. The first uses the most common cell reference method (the left top cell is A1), the second uses the method row/column (the left top cell is R1C1), the last uses the reference mode used in the original file.
</para>
<para>
	This function returns one of the following values:
</para>
<simplelist>
	<member>
		<userinput>0</userinput>. All went OK.
	</member>
	<member>
		<userinput>5</userinput>. Error reading from stream file, thus <parameter>colefile</parameter> has a faulty format.
	</member>
	<member>
		<userinput>10</userinput>. Error allocating memory, there's not enough memory.
	</member>
	<member>
		<userinput>11</userinput>. Error reading streams files, can use perror.
	</member>
	<member>
		<userinput>15</userinput>. Value readed from <parameter>colefile</parameter> file is unknown by now, thus cole file is more advanced or has a faulty format.
	</member>
	<member>
		<userinput>17</userinput>. <parameter>colefile</parameter> is a Excel file, but it's format is unknown or too old.
	</member>
	<member>
		<userinput>18</userinput>. <parameter>colefile</parameter> is password protected so xls2xml can't access it.
	</member>
	<member>
		<userinput>19</userinput>. Internal inconsistence between structures have been found, it's a xls2xml bug (please, <link linkend="bugs">report it</link>).
	</member>
</simplelist>
</sect1> 

