storage(3)

NAME

OLE::Storage - An Interface to Structured Storage Docu ments.

$Revision: 1.8 $ $Date: 1998/04/28 00:39:43 $

SYNOPSIS

use OLE::Storage()
use Startup;
$Var = OLE::Storage->NewVar (); $Startup = new Startup;
$Doc = OLE::Storage->open ($Startup, $Var, $file [,$m,
_$buf])
$Doc -> directory ($pps, _%Names, "string")
$Doc -> read ($pps, _$buf [,$offset, $size])
$Doc -> close ()
Detailed syntax, descriptions and further methods:  below.

DESCRIPTION

Documents done at Microsoft Windows Systems are tending to
be stored in a persistant data format, that MS calls
"Structured Storage". This module gives access to Struc
tured Storage files. Alas, the current release allows more
or less read access, only. You can modify document con
tents (streams) with it, but you cannot create or delete
streams, nor rename them or change their size. Also a file
locking mechanism still is missing. I hope to offer write
support with next release.

close: 1||"O" == $D -> close (); Close the document.
clsid: $clsid == $D -> clsid ($pps); Returns the CLSID of the property $pps as CLSID Prop
erty.
color: 0||1 == $D -> color ($pps); Returns the "color" of the property $pps.
date: $Date == $D -> name ($pps); Returns a 0x40 Property (filetime) with the creation
date of property storage $pps. See OLE::Storage::Prop
erty for more information.; Note: As of now, only directory properties have file
time stamps.
directory: 1||"O" == $D -> directory ($pps, _%Names [,method]); Read the directory denoted by property handle $pps.
Fills the hash array %Names with the property names as keys and property handles as values. The property
names are Unicode Properties. To use the directory
hash easily you optionally can apply a Property
method. You will probably have to use "string" or
"wstring". See OLE::Storage::Property for more infor mation.; Note: To get the root directory, call directory (0,
_%Names).
dirhandles: @pps == $D -> dirhandles ($pps); Similar to directory (). Returns not the names, but
only the property handles of the directory denoted by
property handle $pps.; Note: Normally you will use directory () instead. To
get the root directory, call dirhandles(0)
Startup: $Startup == $D -> Startup ([$NewStartup]); Gets the current $Startup handler. If an optional
argument $NewStartup is given, this new handler will be installed and returned.
is_directory: 1||"O" == $D -> is_directory ($pps); Returns 1 if the property handle $pps is refering to a
directory, 0 otherwise.
is_file: 1||"O" == $D -> is_file ($pps); Returns 1 if the property handle $pps is refering to a
file, 0 otherwise.
is_root: 1||"O" == $D -> is_root ($pps); Returns 1 if the property handle $pps is refering to
the document root, 0 otherwise.
modify: 1||"O" == $D -> modify ($pps, _$buf, $offset, $size); Modifies the contents of the property file $pps. $size bytes of the file $pps starting at offset $offset will be replaced by $size bytes of the buf $buf starting at offset 0.; Note: This is still very restrictive, e.g. because the
size of a file cannot be changed. Also missing is a
possibility to give an offset to $buf.
modify_trash: 1||"O" == $D -> modify_trash ($type, _$buf, $offset, $size); Modifies the contents of the trash section $type.
$size bytes of the trash section $type starting at offset $offset will be replaced by $size bytes of the buf $buf starting at offset 0.
name: $Name == $D -> name ($pps); Returns the name of the property $pps as Unicode Prop
erty.
NewVar: $Var == $D -> NewVar (); Creates a new Variable handling object and returns it.
(see also: open)
open: $Doc||"O" == Storage -> open ($Startup, $Var, $file [,$mode, _$buf]); Constructor. Open the document with document path
$file. $mode can be read or read/write. If you addi tionally specify modus buffer, the document data will
be read from the buffer reference you specify with
$buf. Errors will be reported to Startup object
$Startup (if present).; Open modes:

Bit = 0 = 1
0 Read Only Read and Write
4 File Mode Buffer Mode; read
1||"O" == $D -> read ($pps, _$buf, [$offset, $size])

Read the file property $pps into buffer $buf. If there is an optional $offset and $size, only this part of the file will be read.; read_trash
1||"O" == $D -> read_trash ($type, _$buf [,$offset, $size])

Read the trash section $type into buffer $buf. If
there is an optional $offset and $size, only this part of the trash section will be read. Trash types can be
0, 1, 2, 4, 8 or a sum of this, like (1+2+8). 0 is
default and yields (1+2+4+8). You can find an explana
tion of these types in lclean.

Trash types:

# Type
------------------1 Big blocks
2 Small blocks
4 File end space
8 System space

size

$size||"undef" == $D -> size ($pps)

Returns the size of the file property $pps in terms of
bytes.

size_trash

$size == $D -> size_trash ($type)

Returns the byte size of the trash section $type.

Var $Var == $D -> Var ([$NewVar])

Gets the current $Var handler. If an optional argument
$NewVar is given, this new handler will be installed
and returned.

EXAMPLES

OLE::Storage demonstration programs, as there are:

lls Laola ls. Lists document structures.

ldat: Loala Display Authress Title. Displays content of property sets and shows, how by principle to fool
around with Excel documents.
lclean: Cleans and saves garbage in Structured Storage docu
ments. Can also store and retrieve a file at the
garbage sections.
lhalw: Have a look at Word. Draws the text out of Word 6 and Word 7 documents, supports a little bit Word 8.

WWW

Latest distribution of Laola and Elser at:: http://wwwwbs.cs.tu-berlin.de/~schwartz/pmh
or: http://www.cs.tu-berlin.de/~schwartz/pmh

BUGS

None known. I'm waiting for your hints!

AUTHOR

Martin Schwartz <schwartz@cs.tu-berlin.de>.

docs.sk

comprehensive documentation repository

Most Viewed