NAME
Mac::Finder::DSStore - Read and write Macintosh Finder DS_Store files
DESCRIPTION
Mac::Finder::DSStore provides a handful of functions for reading and writing the desktop database files created by the Macintosh Finder.
FUNCTIONS
Many functions take a $store argument which is the opened file as an instance of Mac::Finder::DSStore::BuddyAllocator, or a $block argument which is a specific block of the file as an instance of Mac::Finder::DSStore::BuddyAllocator::Block.
@records = &Mac::Finder::DSStore::getDSDBEntries($store[, $callback])
Retrieves the "superblock" pointed to by the DSDB entry in the store's table of contents, and traverses the B-tree it points to, returning a list of the records in the tree. Alternately, you can supply a callback which will be invoked for each record, and getDSDBEntries will return an empty list.
&Mac::Finder::DSStore::putDSDBEntries($store, $arrayref)
$arrayref must contain a correctly ordered list of Mac::Finder::DSStore::Entry objects. They will be evenly organized into a B-tree structure and written to the $store. If there is an existing tree of records in the file already, it will be deallocated.
This function does not flush the allocator's information back to the file.
&Mac::Finder::DSStore::writeDSDBEntries($file, @entries)
A convenience function which sorts a list of entries and writes them to the specified file using putDSDBEntries, then flushes the allocator's data structures to disk. $file may be a filename or an open file handle. The store object is returned, but you don't need to do anything else with it.
&Mac::Finder::DSStore::makeEntries($filename, [ what => value ... ])
makeEntries encapsulates some information about the format of individual records in the DS_Store file. It returns a list of records constructed with the given filename and with the information specified in the rest of its args. Most args come in pairs, a name and a value, so makeEntries kind of looks like it takes a hash. Some names take no value and some could take several. Some produce more than one record as a result.
See the output of the examples/dsstore_dump.pl script for an example of how to use this, and check the source code for a list of the formats it accepts.
This function might change in the future.
Mac::Finder::DSStore::Entry
This class holds the individual records from the database. Each record contains a filename (in some cases, "." to refer to the containing directory), a 4-character record type, and a value. The value is one of a few concrete types, according to the record type.
$entry = ...::Entry->new($filename, $typecode)
Creates a new entry with no value. The concrete type is inferred from the record type code.
$entry->filename
Gets the filename of an entry.
$entry->strucId
Gets the record type of this entry, as a four-character string, indicating what aspect of the file the entry describes.
$entry->value([$value])
Gets or sets the value of an entry.
If the concrete type is blob or type, the value is interpreted as a byte string; if it is ustr, as a character string. If the concrete type is long, shor, or bool, then the value should be an integer.
$entry->cmp($other)
Returns -1, 0, or 1 depending on the relative ordering of the two entries, according to (a guess at) the record ordering used by the store's B-tree.
SEE ALSO
See Mac::Finder::DSStore::Format for more detailed information on the record types found in a DS_Store file.
See Mac::Finder::DSStore::BuddyAllocator for the low-level organization of the DS_Store file.
AUTHOR
Copyright 2008 by Wim Lewis <wiml@hhhh.org>.
Some information is from Mark Mentovai via the Mozilla project. Thanks also to Martin Baker for bug reports.