cole-manual.sgml-old

excel to html

<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
  <!ENTITY author-name-full     "Roberto Arturo Tena S&aacute;nchez">
  <!ENTITY author-email         "<email>&lt;[e-mail]&gt;</email>">
  <!ENTITY author-email-address "<address>&author-email;</address>">

  <!ENTITY maintainer-name-full "Roberto Arturo Tena S&aacute;nchez">
  <!ENTITY maintainer-email-ulink "<ulink URL=&#34;mailto:[e-mail]&#34;>&lt;[e-mail]&gt;</ulink>">

  <!-- this-release entity must have majorversion.minorversion.microversion
       format -->
  <!ENTITY this-release "2.0.0">

  <!ENTITY deffree-link         "<link linkend=&#34;deffree&#34;>free</link>">

  <!ENTITY cf			"Compound Files">
  <!ENTITY ss			"Structured Storage">
  <!ENTITY ssf			"Structured Storage file">
  <!ENTITY license		"
      This document is copyright 1999 by &author-name-full;. This document is
      free software; you can redistribute it and/or modify it under the terms
      of the <link linkend=&#34;gpl&#34;>GNU General Public License</link>
      as published by the Free Software Foundation; either version 2 of the
      License, or (at your option) any later version.
				">
]>


<!--
  NOTES:
  end tag for screen should be written immediately after the last character
  in this element is written, to avoid an extra line be added.
  The same goes for programlisting.
  -->



<!-- I have to put index as main book's id in order to generate index.html as
     the main html page! -->
<!-- Any body know how to do it cleaner? -->
<book id="index">



<bookinfo>
  <title>cole Programmer Reference</title>
  <subtitle>cole &this-release;</subtitle>
  <authorgroup>
    <author>
      <firstname>Arturo</firstname>
      <surname>Tena</surname>
      <affiliation>
        &author-email-address;
      </affiliation>
    </author>
  </authorgroup>
  <copyright>
    <year>1999</year>
    <holder>&author-name-full;</holder>
  </copyright>
  <legalnotice>
    <para>
      &license;
    </para>
  </legalnotice>
</bookinfo>



<toc></toc>



<chapter id="what-is-cole">
  <title>What is cole?</title>
    <para>
      cole is a free C OLE library.
    </para>
    <para>
      cole is distributed under the terms of the
      <link linkend="gpl">GNU General Public License</link>
      (GPL) to give an impulse to the Free Software.
    </para>
    <para>
      Using cole, you can access Microsoft' `Structured Storage' files.
      The most popular Microsoft's programs generate `Structured Storage' files,
      incluiding the Microsoft' suite for offices. StarDivision' suite
      (StarOffice) generate `Structured Storage' files too. FlashPix file
      format is `Structured Storage' too.
    </para>
    <para>
      What is a `Structured Storage' file?
      Inside a `Structured Storage' file there is a filesystem, with
      directories and files, which Microsoft calls `containers' and `streams'.
      Using cole you can travel through that filesystem and read the files.
    </para>
    <para>
      cole doesn't know about internal structure of a stream, it only reads the
      raw data. You can use then the Microsoft's documentation available at
      <ulink URL="http://msdn.microsoft.com">http://msdn.microsoft.com</ulink>
      or the information available at <ulink URL="http://www.wotsit.org"
      >http://www.wotsit.org</ulink> to read that structure. If you know
      anything in the side of StarDivision email me. FlashPix is well
      documented.
    </para>
    <para>
      cole was developed using the information available at <ulink
      URL="http://wwwwbs.cs.tu-berlin.de/~schwartz/pmh/guide.html"
      >http://wwwwbs.cs.tu-berlin.de/~schwartz/pmh/guide.html</ulink>, and no
      information from any other source (incluiding Microsoft) has been used.
    </para>
</chapter> <!-- what-is-cole -->



<chapter id="source-code">
  <title>Where to get cole source code</title>
  <para>
    You can get the most recent stable release of cole from the <ulink
    URL="http://arturo.directmail.org/filtersweb/"
    >Filters Project</ulink> home page or from <ulink
    URL="ftp://ftp.metalab.unc.edu/pub/Linux/libs/"
    >Metalab</ulink> (former SunSite) archive.
  </para>
</chapter> <!-- source-code -->



<chapter id="compiling">
  <title>Compiling</title>
  <sect1 id="how-to-compile">
    <title>How to compile</title>
    <para>
      A standard <filename>configure</filename> script is provided. You can
      read the instructions in the file <filename>INSTALL</filename>.
      A typical configuration/compilation/installation session is shown next.
    </para>
    <screen>
<prompt>$</prompt> <userinput>ls</userinput>
cole-&this-release;.tar.gz
<prompt>$</prompt> <userinput>gzip -d cole-&this-release;.tar.gz</userinput>
<prompt>$</prompt> <userinput>tar -xf cole-&this-release;.tar</userinput>
<prompt>$</prompt> <userinput>ls</userinput>
cole-&this-release;.tar.gz      cole-&this-release;/
<prompt>$</prompt> <userinput>cd cole-&this-release;</userinput>
<prompt>$</prompt> <userinput>./configure --prefix=/usr/local</userinput>
...
Configured cole release &this-release; 
<prompt>$</prompt> <userinput>make</userinput>
...
<prompt>$</prompt> <userinput>make install</userinput>
...
<prompt>$</prompt> <userinput>make clean</userinput>
...</screen>
    <para>
      You can add the following flags to <filename>configure</filename>:
    </para>
    <simplelist>
      <member>
        <userinput>--enable-cole-verbose</userinput>. To make cole verbose
        everything. Usefull when debugging cole.
      </member>
      <member>
        <userinput>--enable-osf-align-check</userinput>. If you have errors
        while compiling under OSF1, enable this flag.
      </member>
    </simplelist>
    <para>
      Please, if you have some error with cole, send the cole's output when
      compiled using <userinput>--enable-cole-verbose</userinput> to the 
      <link linkend="current-maintainer">maintainer</link>.
    </para>
    <para>
      For additional instructions, read the file <filename>INSTALL</filename>.
      If you have problems, you should read the <ulink
      URL="http://arturo.directmail.org/filtersweb/">Filters Project</ulink>
      FAQ and later email to the <link linkend="current-maintainer"
      >maintainer</link>.
    </para>
    <para>
      Only a static library is compiled by default. If you want compile a shared
      library too, you have to include the flag
      <userinput>--enable-shared</userinput> when
      running configure, and the program that dinamically links against cole
      shared library still needs to be under a license compatible with GPL.
      This is because cole is under GPL license, not LGPL license.
    </para>
  </sect1> <!-- how-to-compile -->
  <sect1 id="supported-plattforms">
    <title>Supported plattforms</title>
    <para>
      cole has been successfully tested under (as reported by
      <userinput>uname -mrsv</userinput> or with the system information):
    </para>
    <screen>
Linux 2.0.36 #1 Wed Feb 17 19:45:41 EST 1999 i586
Linux 2.0.35 #1 Thu Jul 23 14:01:04 EDT 1998 i586
OSF1 V5.0 564 alpha
OSF1 V4.0 564 alpha
Solaris in Ultra Sparc (sparc-sun-solaris2.5.1)
	Arturo Tena <ulink URL="mailto:[e-mail]">&lt;[e-mail]&gt;</ulink>
SunOS 5.6 Generic_105181-03 sun4u
	Matthew Evans <ulink URL="mailto:[e-mail]">&lt;[e-mail]&gt;</ulink>
Windows NT 4.0 SP4
	with Cygwin b20.1
	with CoolView DLL
	Martin Scharpf <ulink URL="mailto:[e-mail]">&lt;[e-mail]&gt;</ulink></screen>
    <para>
      If you have a different one, it will be useful to hear about you. Please,
      email to the <link linkend="current-maintainer">maintainer</link>.
    </para>
  </sect1> <!-- supported-plattforms -->    
</chapter> <!-- compiling -->



<chapter id="using">
  <title>Using</title>
  <para>
    cole is used to access Microsoft OLE's &ss; and &cf;.
    Specifically, cole extracts the structures named streams
    from a &ssf;. Each stream is written to a new file.
    A dynamic tree in memory is created to store the name of the streams and
    the name of the files where they are written, besides other information.
  </para>
  <para>
    cole doesn't know the structure of each stream, it only extract them to
    new files. If you want to know the structure of a particular stream,
    you can read the <ulink URL="http://msdn.microsoft.com/"
    >Microsoft's documentation</ulink>, or seach in <ulink
    URL="http://www.wotsit.org/">Wotsit</ulink>. Using that documentation, you
    can read the extracted streams searching for the actual information.
  </para>
  <sect1 id="api">
  <title>API</title>
    <para>
      cole has two major functions: OLEdecode and OLEcode.
      The first takes an &ssf; and divide it into streams.
      The last takes streams and generate an &ssf; (the
      <parameter>stream_list</parameter>
      structure and the streams itself must be valid, but cole doesn't provide
      functions to validate them by now).
    </para>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;cole/cole.h&gt;</funcsynopsisinfo>
      <funcdef>int <function>OLEdecode</function></funcdef>
      <paramdef>char *<parameter>OLEfilename</parameter></paramdef>
      <paramdef>pps_entry **<parameter>stream_list</parameter></paramdef>
      <paramdef>U32 *<parameter>root</parameter></paramdef>
      <paramdef>U16 <parameter>max_level</parameter></paramdef>
    </funcsynopsis>
    <para>
      This function extracts the streams of the file wich name is 
      <parameter>OLEfilename</parameter> and generate a array of
      pps_entry's named <parameter>stream_list</parameter>.
      The array make a tree (ie. each pps_entry have fields such as next
      for brothers and dir for children pps_entry's) with root pps_entry
      <parameter>root</parameter>, and this tree stores the stream's names,
      the names of the temporal files where the streams were written and other
      information. Only streams with level minor than or equal to
      <parameter>max_level</parameter> are extracted, but all streams are
      extracted if <parameter>max_level</parameter> is zero.
    </para>
    <para>
      OLEdecode returns one of the following numbers:
    </para>
    <simplelist>
      <member>
        0. Sucess.
      </member>
      <member>
        4. Couldn't open <parameter>OLEfilename</parameter> file
           (can use <function>perror</function>(3)).
      </member>
      <member>
        8. <parameter>OLEfilename</parameter> file seems to be a plain
           text file, not a &ssf;.
      </member>
      <member>
        9. <parameter>OLEfilename</parameter> is a binary file,
           but it's not a &ssf;.
      </member>
      <member>
        5. Error reading from file, means <parameter>OLEfilename</parameter>
           file has a faulty &ss; format.
      </member>
      <member>
        6. Error removing temporal files.
      </member>