The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

OLE::Storage - An Interface to Structured Storage Documents.

$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 Structured Storage files. Alas, the current release allows more or less read access, only. You can modify document contents (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 Property.

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::Property for more information.

Note: As of now, only directory properties have filetime 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 information.

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 Property.

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 additionally 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 explanation 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.

SEE ALSO

OLE::Storage::Property, Startup, OLE::Storage::Var

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 documents. 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>.