NAME
OLE::Storage - An Interface to Structured Storage Documents.
$Revision: 0.3.8.6 $ $Date: 1997/10/28 00:01:53 $
SYNOPSIS
use OLE::Storage()
$Err = OLE::Storage->NewError ();
$Var = OLE::Storage->NewVar ();
$Doc = OLE::Storage->open ($Err, $Var, $file [,$m, \$buf])
$Doc -> directory ($pps, \%Names, "string")
$Doc -> read ($pps, \$buf [,$offset, $size])
$Doc -> close ()
$Err -> string ()
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.
- 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)
- Error
-
$Error == $D -> Error ([$NewError])
Gets the current $Error handler. If an optional argument $NewError 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.
- NewError
-
$Error == $D -> NewError ()
Creates a new Error handling object and returns it. (see also: open)
- NewVar
-
$Var == $D -> NewVar ()
Creates a new Variable handling object and returns it. (see also: open)
- open
-
$Doc||
O== Storage -> open ($Err, $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 Error object $Err.
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, OLE::Storage::Error, 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/pmhBUGS
None known. I'm waiting for your hints!
AUTHOR
Martin Schwartz <schwartz@cs.tu-berlin.de>.