cole-manual.sgml-old

excel to html

      <member>
        7. Error creating temporal files.
      </member>
      <member>
        10. Error allocating memory, there's no more memory.
      </member>
    </simplelist>
    <screen>
#include &lt;stdio.h&gt;
#include &lt;cole/cole.h&gt;

struct pps_block {
char name[0x20];          /* name of the stream */
U8 type;                  /* type of this pps: 5 == root of stream_list,
                             1 == dir, 2 == stream */
char filename[L_tmpnam];  /* temporal file name where the stream were written,
                             valid only if type == 2 */
U32 size;                 /* the size of the temporal file,
                             valid only if type == 2 */
U32 next;                 /* next pps_entry in this directory, brother pps */
U32 dir;                  /* pps_entry children, valid only if type != 2 */
U16 level;                /* level of the pps in the tree */
U32 seconds1;             /* time creation */
U32 seconds2;             /* time creation */
U32 days1;                /* date creation */
U32 days2;                /* date creation */
/* ... */
};
typedef struct pps_block pps_entry;
    </screen>
    <para>
      pps_entry structure describes one extrated stream.
    </para>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;cole/cole.h&gt;</funcsynopsisinfo>
      <funcdef>int <function>OLEcode</function></funcdef>
      <paramdef>const char *<parameter>OLEfilename</parameter></paramdef>
      <paramdef>int <parameter>trunc</parameter></paramdef>
      <paramdef>pps_entry *<parameter>stream_list</parameter></paramdef>
      <paramdef>U32 <parameter>root</parameter></paramdef>
    </funcsynopsis>
    <para>
      This function takes the <parameter>stream_list</parameter> tree
      (which have a root pps_entry <parameter>root</parameter> and
      describes some existing valid streams) and generate a &ssf;
      named <parameter>OLEfilename</parameter>. If <parameter>trunc</parameter>
      is zero and <parameter>OLEfilename</parameter> exists, returns 2
      (see below), in any other case <parameter>OLEfilename</parameter>
      will be created or recreated as needed.
    </para>
    <para>
      OLEcode returns one of the following numbers:
    </para>
    <simplelist>
      <member>
        0. All goes OK.
      </member>
      <member>
        1. Error writting in <parameter>OLEfilename</parameter>
           (can use <function>perror</function>(3)).
      </member>
      <member>
        2. trunc is zero and <parameter>OLEfilename</parameter> exist.
      </member>
      <member>
        3. Can't create <parameter>OLEfilename</parameter>
           (can use <function>perror</function>(3)).
      </member>
      <member>
        10. Error allocating memory, there's no more memory.
      </member>
      <member>
        11. Error reading stream's temporal files.
      </member>
      <member>
        12. Error reading <parameter>stream_list</parameter>, it's broken.
      </member>
    </simplelist>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;cole/cole.h&gt;</funcsynopsisinfo>
      <funcdef>int <function>freeOLEtree</function></funcdef>
      <paramdef>pps_entry *<parameter>stream_list</parameter></paramdef>
    </funcsynopsis>
    <para>
      You must call this function at the end of processing the streams, to
      free memory and remove the stream files.
    </para>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;cole/cole.h&gt;</funcsynopsisinfo>
      <funcdef>void <function>verbosePPSTree</function></funcdef>
      <paramdef>pps_entry *<parameter>stream_list</parameter></paramdef>
      <paramdef>U32 <parameter>root</parameter></paramdef>
      <paramdef>int <parameter>level</parameter></paramdef>
    </funcsynopsis>
    <para>
      You can use this function to display the tree of a &ssf;.
    </para>
  </sect1> <!-- api -->
  <sect1 id="linking">
    <title>Linking</title>
    <para>
      You need link your program against <filename>libcole.a</filename>.
      This means is ok:
    </para>
    <screen>
<prompt>$</prompt> <userinput>cc yourprogram.o libcole.a -o yourprogram</userinput></screen>
    <para>
      If you use threads, take in count that cole is not reentrant safe
      (cole 2.0.0 will be reentrant safe).
    </para>
  </sect1> <!-- linking -->
  <sect1 id="examples-an-example">
    <title>An example</title>
    <para>
      The following example is similar to the included file
      <filename>demo.c</filename>.
      It opens, display the tree and closes a &ssf;:
    </para>
    <screen>
#include &lt;stdio.h&gt;
#include &lt;cole/cole.h&gt;</screen>
    <para>
      You need to include <filename>cole/cole.h</filename> header to
      use the cole functions.
    </para>
    <screen>
int
main (int argc, char **argv)
{
  int result;
  pps_entry *stream_tree;
  U32 root_stream;
  U32 stream;

  if (argc != 3)
    {
      fprintf (stderr, "cole example 1. cole is a free C OLE library.\n");
      fprintf (stderr, "Usage: coleexample1 srcFILE destFILE.\n");
      fprintf (stderr,
  "Note: if srcFILE and destFILE are the same file, it will be overwritten.\n");
      return 1;
    }</screen>
    <para>Just argument checks.</para>
    <screen>
  verbose ("Decoding ************************************");
  result = OLEdecode (argv[1], &amp;stream_tree, &amp;root_stream, 0);</screen>
    <para>
      Here we call <function>OLEdecode</function> in order to extract the
      structure of the &ssf; which name is stored in
      <parameter>argv[1]</parameter>. The structure will be stored in
      <parameter>stream_tree</parameter>, and the root of the structure
      in <parameter>root_stream</parameter> (we will need the root later).
      The last argument indicate the level of the structure that
      <function>OLEdecode</function> will extract, if it's zero it will
      extract all the levels.
    </para>
    <screen>
  fprintf (stderr, "OLEdecode output = %d\n", result);
  if (result != 0)
    {
      fprintf (stderr, "Decoding: ");
      perror (argv[1]);
      return 1;
    }
  else
    verbose ("Success decoding");

  printf ("******* Stream tree:\n");
  verbosePPSTree (stream_tree, root_stream, 0);</screen>
    <para>
      <function>verbosePPSTree</function> is a cole function that prints
      to the standard output the complete tree of a &ssf;. With the last
      parameter equal to zero, we are printing all levels of the
      structure.
    </para>
    <screen>
  printf ("******* Top level no directory streams:\n");
  /* travel through the top level no directory streams,
     just follows next field and ignore type 1 fileds */
  for (stream = stream_tree[root_stream].dir;
       stream != 0xffffffff;
       stream = stream_tree[stream].next)
    {
      if (stream_tree[stream].type != 1 && stream_tree[stream].level == 1)
      if (!isprint(stream_tree[stream].name[0]))
	printf ("'\\x%02x%s'\n", stream_tree[stream].name[0],
		stream_tree[stream].name+1);
      else
	printf ("'%s'\n", stream_tree[stream].name);
    }</screen>
    <para>
      With this code, we are traveling in the structure, which is a
      tree in an array, this means it's a tree of structures with indexes
      for the brothers and the children (if any). As you can see,
      the actual names of the streams may begin with no printable characters.
    </para>
    <screen>
  verbose ("Coding **************************************");
  result = OLEcode (argv[2], 1, stream_tree, root_stream);</screen>
    <para>
      If you want to read the raw streams you only need
      <function>OLEdecode</function> function. But if you want to generate
      a &ssf;, you need to have the raw streams, the tree in an array
      structure and the root of such tree to use <function>OLEcode</function>.
      cole &this-release; doesn't provide functions to such tasks, wait
      for cole 2.0.0.
    </para>
    <screen>
  fprintf (stderr, "OLEcode output = %d\n", result);
  if (result != 0)
    {
      fprintf (stderr, "Coding ");
      perror (argv[2]);
      return 1;
    }
  else
    verbose ("Success coding\n");


  verbose ("Freeing *************************************");
  /* need to free all the allocated memory */
  result = freeOLEtree (stream_tree);</screen>
    <para>
      If you used <function>OLEdecode</function>, you must use
      <function>freeOLEtree</function> after process the raw stream.
    </para>
    <screen>
  fprintf (stderr, "freeOLEtree output = %d\n", result);

  return result;
}</screen>
    <para>When you run this example, the following output is produced:</para>
    <screen>
<prompt>$</prompt> <userinput>./coleexample1 examples/text.doc text2.doc</userinput>
OLEdecode output = 0
******* Stream tree:
DIR  00 'Root Entry'
   FILE 01      98 ' CompObj'
   FILE 03     312 ' SummaryInformation'
   FILE 04    2381 'WordDocument'
   FILE 02      20 ' Ole'
******* Top level no directory streams:
'\x01CompObj'
'\x05SummaryInformation'
'WordDocument'
'\x01Ole'
OLEcode output = 0
freeOLEtree output = 0</screen>
  </sect1> <!-- examples-an-example -->
  <sect1 id="examples-another-example">
    <title>Another example</title>
    <para>
      The next example opens a file, and guess what version of
      Microsoft Excel generated the file.
    </para>
    <screen>
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#include &lt;cole/cole.h&gt;

int
main (int argc, char **argv)
{
  pps_entry *stream_tree;
  U32 root_stream;
  U32 stream;
  FILE * f;
  unsigned char buff[6];

  if (argc != 2)
    {
      fprintf (stderr, "cole example 2. cole is a free C OLE library.\n");
      fprintf (stderr, "Usage: coleexample2 FILE.\n");
      return 1;
    }

  if (OLEdecode (argv[1], &amp;stream_tree, &amp;root_stream, 0)) {
      printf ("File is not a Microsoft Excel one.\n");
      return 1;
  }

  for (stream = stream_tree[root_stream].dir;
       stream != 0xffffffff;
       stream = stream_tree[stream].next) {
      if (stream_tree[stream].type != 1 &amp;&amp; stream_tree[stream].level == 1)
	  if (!strcmp(stream_tree[stream].name, "Workbook") ||
	      !strcmp(stream_tree[stream].name, "Book")) {
	     /* Book stream found */