<header>
<title>HPSF HOW-TO</title>
<authors>
- <person name="Rainer Klute" email="klute@rainer-klute.de"/>
+ <person name="Rainer Klute" email="klute@apache.org"/>
</authors>
</header>
<body>
<section title="How To Use the HPSF APIs">
- <p>This HOW-TO is organized in three section. You should read them
+ <p>This HOW-TO is organized in three sections. You should read them
sequentially because the later sections build upon the earlier ones.</p>
<ol>
</li>
</ol>
- <p>Please note that there is separate document on <link
- href="thumbnails.html">thumbnails</link>!</p>
-
- <anchor id="sec1" />
+ <anchor id="sec1"/>
<section title="Reading Standard Properties">
<note>This section explains how to read
<p>The first thing you should understand is that properties are stored in
separate documents inside the POI filesystem. (If you don't know what a
- POI filesystem is, read its <link
- href="../poifs/index.html">documentation</link>.) A document in a POI
- filesystem is also called a <strong>stream</strong>.</p>
+ POI filesystem is, read the <link href="../poifs/index.html">POIFS
+ documentation</link>.) A document in a POI filesystem is also called a
+ <strong>stream</strong>.</p>
<p>The following example shows how to read a POI filesystem's
"title" property. Reading other properties is similar. Consider the API
- documentation of <code>org.apache.poi.hpsf.SummaryInformation</code>.</p>
+ documentation of <code>org.apache.poi.hpsf.SummaryInformation</code> to
+ learn which methods are available!</p>
- <p>The standard properties this section focusses on can be
- found in a document called <em>\005SummaryInformation</em> in the root of
- the POI filesystem. The notation <em>\005</em> in the document's name
- means the character with the decimal value of 5. In order to read the
- title, an application has to perform the following steps:</p>
+ <p>The standard properties this section focusses on can be found in a
+ document called <em>\005SummaryInformation</em> located in the root of the
+ POI filesystem. The notation <em>\005</em> in the document's name means
+ the character with the decimal value of 5. In order to read the title, an
+ application has to perform the following steps:</p>
<ol>
<li>
of the POI filesystem.</p>
</li>
<li>
- <p>Create an instance of the class
- <code>SummaryInformation</code> from that
- document.</p>
+ <p>Create an instance of the class <code>SummaryInformation</code> from
+ that document.</p>
</li>
<li>
<p>Call the <code>SummaryInformation</code> instance's
(POIFS) proceeds as shown by the following code fragment. (The full
source code of the sample application is available in the
<em>examples</em> section of the POI source tree as
- <em>ReadTitle.java</em>.)</p>
+ <em>ReadTitle.java</em>.</p>
+
+ <fixme>I just found out that <em>ReadTitle.java</em> is no longer there! I
+ shall look it up in the CVS and try to restore it.</fixme>
<source>
import java.io.*;
<code>processPOIFSReaderEvent</code> method. The eventing POI filesystem
calls this method when it finds the <em>\005SummaryInformation</em>
document. In the sample application <code>MyPOIFSReaderListener</code> is
- a static class in the <em>ReadTitle.java</em> source file.)</p>
+ a static class in the <em>ReadTitle.java</em> source file.</p>
<p>Now everything is prepared and reading the POI filesystem can
start:</p>
case that the POI filesystem does not have a title.</p>
<source>final String title = si.getTitle();
- if (title != null)
- System.out.println("Title: \"" + title + "\"");
- else
- System.out.println("Document has no title.");</source>
+if (title != null)
+ System.out.println("Title: \"" + title + "\"");
+else
+ System.out.println("Document has no title.");</source>
<p>Please note that a Microsoft Office document does not necessarily
contain the <em>\005SummaryInformation</em> stream. The documents created
<p>And of course you cannot call <code>getTitle()</code> because
<code>DocumentSummaryInformation</code> has different query methods. See
- the API documentation for the details!</p>
+ the Javadoc API documentation for the details!</p>
<p>In the previous section the application simply caught all
<strong>exceptions</strong> and was in no way interested in any
<dl>
<dt><code>NoPropertySetStreamException</code>:</dt>
- <dd><p>This exception is thrown if the application tries to create a
- <code>PropertySet</code> or one of its subclasses
- <code>SummaryInformation</code> and
- <code>DocumentSummaryInformation</code> from a stream that is not a
- property set stream. A faulty property set stream counts as not being a
- property set stream at all. An application should be prepared to deal
- with this case even if opens streams named
+ <dd>
+ <p>This exception is thrown if the application tries to create a
+ <code>PropertySet</code> instance from a stream that is not a
+ property set stream. (<code>SummaryInformation</code> and
+ <code>DocumentSummaryInformation</code> are subclasses of
+ <code>PropertySet</code>.) A faulty property set stream counts as not
+ being a property set stream at all. An application should be prepared to
+ deal with this case even if it opens streams named
<em>\005SummaryInformation</em> or
<em>\005DocumentSummaryInformation</em> only. These are just names. A
stream's name by itself does not ensure that the stream contains the
- expected contents and that this contents is correct.</p></dd>
+ expected contents and that this contents is correct.</p>
+ </dd>
<dt><code>UnexpectedPropertySetTypeException</code></dt>
<dd><p>This exception is thrown if a certain type of property set is
document. Embedded objects may have property sets of their own. An
application can open these property set streams as described above. The
only difference is that they are not located in the POI filesystem's root
- but in a nested directory instead. Just register a
+ but in a <strong>nested directory</strong> instead. Just register a
<code>POIFSReaderListener</code> for the property set streams you are
interested in. For example, the <em>POIBrowser</em> application in the
contrib section tries to open each and every document in a POI filesystem
<anchor id="sec3"/>
<section title="Reading Non-Standard Properties">
- <note>This section tells how to read
- non-standard properties. Non-standard properties are application-specific
- name/value/type triples.</note>
-
- <fixme author="Rainer Klute">Write this section!</fixme>
+ <note>This section tells how to read non-standard properties. Non-standard
+ properties are application-specific name/type/value triples.</note>
+
+ <p>Now comes the really hardcode stuff. As mentioned above,
+ <code>SummaryInformation</code> and
+ <code>DocumentSummaryInformation</code> are just special cases of the
+ general concept of a property set. The general concept says that a
+ property set consists of <strong>properties</strong>. Each property is an
+ entity that has a <strong>name</strong>, a <strong>type</strong>, and a
+ <strong>value</strong>.</p>
+
+ <p>Okay, that was still rather easy. However, to make things more
+ complicated Microsoft in its infinite wisdom decided that a property set
+ shalt be broken into <strong>sections</strong>. Each section holds a bunch
+ of properties. But since that's still not complicated enough: a section
+ can optionally have a dictionary that maps property IDs to property
+ names - we'll explain later what that means.</p>
+
+ <note>[To be continued.]</note>
+
+ <fixme>Let's consider a Java application that wants to read a stream
+ containing a general property set. It is modelled by the class
+ <code>PropertySet</code> in the <code>org.apache.poi.hpsf</code>
+ package.</fixme>
</section>
</section>
</body>
</document>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: xml
+sgml-omittag:nil
+sgml-shorttag:nil
+sgml-namecase-general:nil
+sgml-general-insert-case:lower
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->
<title>HPSF (Horrible Property Set Format)</title>
<subtitle>Overview</subtitle>
<authors>
- <person name="Rainer Klute" email="klute@rainer-klute.de"/>
+ <person name="Rainer Klute" email="klute@apache.org"/>
</authors>
</header>
<body>
<section title="Overview">
- <p>Microsoft applications like "Word" or "Excel" let the user describe his
- document by properties like "title", "category" and so on. The application
- itself adds further information: last author, creation date etc. These
- properties are stored in so-called <strong>property set streams</strong>. A
- property set stream is a separate document within a <link
- href="../poifs/index.html">POI filesystem</link>. HPSF is POI's pure-Java
- implementation to read (and in future to write) property set streams.</p>
+ <p>Microsoft applications like "Word", "Excel" or "Powerpoint" let the user
+ describe his document by properties like "title", "category" and so on. The
+ application itself adds further information: last author, creation date
+ etc. These document properties are stored in so-called <strong>property set
+ streams</strong>. A property set stream is a separate document within a
+ <link href="../poifs/index.html">POI filesystem</link>. We'll call property
+ set streams mostly just "property sets". HPSF is POI's pure-Java
+ implementation to read (and in future to write) property sets.</p>
<p>The <link href="how-to.html">HPSF HOWTO</link> describes what a Java
application should do to read a property set using HPSF and to retrieve the
information it needs.</p>
- <p>HPSF supports OLE2 property set streams in general, not only the special
- case of document properties mentioned above. The <link
- href="internals.html">HPSF description</link> describes the internal
- structure of property set streams.</p>
+ <p>HPSF supports OLE2 property set streams in general, and is not limited to
+ the special case of document properties in the Microsoft Office files
+ mentioned above. The <link href="internals.html">HPSF description</link>
+ describes the internal structure of property set streams. A separate
+ document explains the internal of <link href="thumbnails.html">thumbnail
+ images</link>.</p>
</section>
</body>
</document>
<body>
<section title="The VT_CF Format">
- <p>
- Thumbnail information is stored as a VT_CF, or Thumbnail Variant.
- The Thumbnail Variant is used to store various types of information
- in a clipboard. The VT_CF can store information in formats for the
- Macintosh or Windows clipboard.
- </p>
-
- <p>
- There are many types of data that can be copied to the clipboard,
- but the only types of information needed for thumbnail manipulation are
- the image formats.
- </p>
-
+ <p>Thumbnail information is stored as a VT_CF, or Thumbnail Variant. The
+ Thumbnail Variant is used to store various types of information in a
+ clipboard. The VT_CF can store information in formats for the Macintosh or
+ Windows clipboard.</p>
+
+ <p>There are many types of data that can be copied to the clipboard, but the
+ only types of information needed for thumbnail manipulation are the image
+ formats.</p>
+
<p>The <code>VT_CF</code> structure looks like this:</p>
-
+
<table>
<tr>
<th>Element:</th>
</tr>
</table>
- <p>
- The Clipboard Size refers to the size (in bytes) of Clipboard Data
- (variable size) plus the Clipboard Format (four bytes).
- </p>
-
+ <p>The Clipboard Size refers to the size (in bytes) of Clipboard Data
+ (variable size) plus the Clipboard Format (four bytes).</p>
+
<p>Clipboard Format Tag has four possible values:</p>
<table>
<section title="Windows Clipboard Data">
- <p>
- Windows clipboard data has four image formats for thumbnails:
- </p>
-
+ <p>Windows clipboard data has four image formats for thumbnails:</p>
+
<table>
<tr>
<th>Value</th>
<th>Identifier</th>
<th>Description</th>
- </tr>
+ </tr>
<tr>
<td>3</td>
<td><code>CF_METAFILEPICT</code></td>
<td>8</td>
<td><code>CF_DIB</code></td>
<td>Device Independent Bitmap</td>
- </tr>
+ </tr>
<tr>
<td>14</td>
<td><code>CF_ENHMETAFILE</code></td>
<td>Enhanced Windows metafile format</td>
- </tr>
+ </tr>
<tr>
<td>2</td>
<td><code>CF_BITMAP</code></td>
<td>Bitmap - Obsolete - Use <code>CF_DIB</code> instead</td>
- </tr>
+ </tr>
+ </table>
+ </section>
+
+ <section title="Windows Metafile Format">
+
+ <p>The most common format for thumbnails on the Windows platform is the
+ Windows metafile format. The Clipboard places and extra header in front of
+ a the standard Windows Metafile Format data.</p>
+
+ <p>The Clipboard Data byte array looks like this when an image is stored in
+ Windows' Clipboard WMF format.</p>
+
+ <table>
+ <tr>
+ <th>Identifier</th>
+ <td>CF_METAFILEPICT</td>
+ <td>mm</td>
+ <td>width</td>
+ <td>height</td>
+ <td>handle</td>
+ <td>WMF data</td>
+ </tr>
+ <tr>
+ <th>Size</th>
+ <td>32 bit unsigned int</td>
+ <td>16 bit unsigned(?) int</td>
+ <td>16 bit unsigned(?) int</td>
+ <td>16 bit unsigned(?) int</td>
+ <td>16 bit unsigned(?) int</td>
+ <td>byte array - variable length</td>
+ </tr>
+ <tr>
+ <th>Description</th>
+ <td>Clipboard WMF</td>
+ <td>Mapping Mode</td>
+ <td>Image Width</td>
+ <td>Image Height</td>
+ <td>handle to the WMF data array in memory, or 0</td>
+ <td>standard WMF byte stream</td>
+ </tr>
</table>
+ </section>
- <section title="Windows Metafile Format">
-
- <p>
- The most common format for thumbnails on the Windows platform
- is the Windows metafile format. The Clipboard places and extra
- header in front of a the standard Windows Metafile Format data.
- </p>
-
- <p>
- The Clipboard Data byte array looks like this when an image is
- stored in Windows' Clipboard WMF format.
- </p>
-
- <table>
- <tr>
- <th>Identifier</th>
- <td>CF_METAFILEPICT</td>
- <td>mm</td>
- <td>width</td>
- <td>height</td>
- <td>handle</td>
- <td>WMF data</td>
- </tr>
- <tr>
- <th>Size</th>
- <td>32 bit unsigned int</td>
- <td>16 bit unsigned(?) int</td>
- <td>16 bit unsigned(?) int</td>
- <td>16 bit unsigned(?) int</td>
- <td>16 bit unsigned(?) int</td>
- <td>byte array - variable length</td>
- </tr>
- <tr>
- <th>Description</th>
- <td>Clipboard WMF</td>
- <td>Mapping Mode</td>
- <td>Image Width</td>
- <td>Image Height</td>
- <td>handle to the WMF data array in memory, or 0</td>
- <td>standard WMF byte stream</td>
- </tr>
- </table>
- </section>
-
-
-
- <section title="Device Independent Bitmap">
- <p><strong>FIXME:</strong> Document Device Independent Bitmap format</p>
- </section>
+
+ <section title="Device Independent Bitmap">
+ <p><strong>FIXME:</strong> Describe the Device Independent Bitmap
+ format!</p>
</section>
-
+
<section title="Macintosh Clipboard Data">
- <p><strong>FIXME:</strong> Document Macintosh clipboard formats.</p>
+ <p><strong>FIXME:</strong> Describe the Macintosh clipboard formats!</p>
</section>
</body>
</document>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: xml
+sgml-omittag:nil
+sgml-shorttag:nil
+sgml-namecase-general:nil
+sgml-general-insert-case:lower
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->
projects / poi.git / commitdiff