src/documentation/content/xdocs/poifs/embeded.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3    ====================================================================
   4    Licensed to the Apache Software Foundation (ASF) under one or more
   5    contributor license agreements.  See the NOTICE file distributed with
   6    this work for additional information regarding copyright ownership.
   7    The ASF licenses this file to You under the Apache License, Version 2.0
   8    (the "License"); you may not use this file except in compliance with
   9    the License.  You may obtain a copy of the License at
  10
  11        http://www.apache.org/licenses/LICENSE-2.0
  12
  13    Unless required by applicable law or agreed to in writing, software
  14    distributed under the License is distributed on an "AS IS" BASIS,
  15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16    See the License for the specific language governing permissions and
  17    limitations under the License.
  18    ====================================================================
  19 -->
  20 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
  21 <document>
  22   <header>
  23     <title>Apache POI - POIFS - Documents embeded in other documents</title>
  24     <subtitle>Overview</subtitle>
  25     <authors>
  26       <person name="Nick Burch" email="nick@apache.org"/>
  27       <person name="Yegor Kozlov" email="yegor@apache.org"/>
  28     </authors>
  29   </header>
  30   <body>
  31     <section><title>Overview</title>
  32       <p>It is possible for one OLE 2 based document to have other
  33          OLE 2 documents embeded in it. For example, and Excel file
  34          may have a word document and a powerpoint slideshow
  35          embeded as part of it.</p>
  36       <p>Normally, these other documents are stored in subdirectories
  37          of the OLE 2 (POIFS) filesystem. The exact location of the
  38          embeded documents will vary depending on the type of the
  39          master document, and the exact directory names will differ
  40          each time. To figure out exactly which directory to look
  41          in, you will either need to process the appropriate OLE 2
  42          linking entry in the master document, or simple iterate
  43          over all the directories in the filesystem.</p>
  44       <p>As a general rule, you will find the same OLE 2 entries
  45          in the subdirectories, as you would've found at the root
  46          of the filesystem were a document to not be embeded.</p>
  47
  48        <section><title>Files embeded in Excel</title>
  49          <p>Excel normally stores embeded files in subdirectories
  50          of the filesystem root. Typically these subdirectories
  51          are named starting with MBD, with 8 hex characters following.</p>
  52        </section>
  53
  54        <section><title>Files embeded in Word</title>
  55          <p>Word normally stores embeded files in subdirectories
  56          of the ObjectPool directory, itself a subdirectory of the
  57          filesystem root. Typically these subdirectories and named
  58          starting with an underscore, followed by 10 numbers.</p>
  59        </section>
  60
  61        <section><title>Files embeded in PowerPoint</title>
  62          <p>PowerPoint does not normally store embeded files
  63          in the OLE2 layer. Instead, they are held within records
  64          of the main PowerPoint file.
  65          <br/>See the <link href="./../hslf/how-to-shapes.html#OLE">HSLF Tutorial</link>
  66          for how to retrieve embedded OLE objects from a presentation</p>
  67        </section>
  68     </section>
  69
  70     <section><title>Listing POIFS contents</title>
  71       <p>POIFS provides a simple tool for listing the contents of
  72          OLE2 files. This can allow you to see what your POIFS file
  73          contents, and hence if it has any embeded documents in it,
  74          and where.</p>
  75       <p>The tool to use is <em>org.apache.poi.poifs.dev.POIFSLister</em>.
  76          This tool may be run from the command line, and takes a filename
  77          as its parameter. It will print out all the directories and
  78          files contained within the POIFS file.</p>
  79     </section>
  80
  81     <section><title>Opening embeded files</title>
  82       <p>All of the POIDocument classes (HSSFWorkbook, HSLFSlideShow,
  83          HWPFDocument and HDGFDiagram) can either be opened from
  84          a POIFSFileSystem, or from a specific directory within a
  85          POIFSFileSystem. So, to open embeded files, simply locate the
  86          appropriate DirectoryNode that represents the subdirectory
  87          of interest, and pass this + the overall POIFSFileSystem to
  88          the constructor.</p>
  89       <p>I you want to extract the textual contents of the embeded file,
  90          then open the appropriate POIDocument, and then pass this to
  91          the extractor class, instead of simply passing the POIFSFilesystem
  92          to the extractor.</p>
  93     </section>
  94   </body>
  95 </document>