diff options
Diffstat (limited to 'man/2/palmfile')
| -rw-r--r-- | man/2/palmfile | 542 |
1 files changed, 542 insertions, 0 deletions
diff --git a/man/2/palmfile b/man/2/palmfile new file mode 100644 index 00000000..81d62fc2 --- /dev/null +++ b/man/2/palmfile @@ -0,0 +1,542 @@ +.TH PALMFILE 2 +.SH NAME +Palmfile: Categories, DBInfo, Doc, Entry, Pfile, Record \- read Palm™ file formats +.SH SYNOPSIS +.EX +include "bufio.m"; +include "palmfile.m"; + +palmfile := load Palmfile Palmfile->PATH; + +Pfile: adt { + fname: string; + + appinfo: array of byte; + sortinfo: array of int; + + entries: array of ref Entry; + + open: fn(name: string, mode: int): (ref Pfile, string); +. # create: fn(nil: string, mode: int, perm: int, nil: ref DBInfo): ref Pfile; + close: fn(pf: self ref Pfile): int; + read: fn(pf: self ref Pfile, index: int): (ref Record, string); +. # append: fn(pf: self ref Pfile, r: ref Record): int; + stat: fn(pf: self ref Pfile): ref DBInfo; +. # wstat: fn(pf: self ref Pfile, nil: ref DBInfo): string; +. # readid: fn(pf: self ref Pfile, nil: int): (ref Record, string); +. # setappinfo: fn(pf: self ref Pfile, nil: array of byte); +. # setsortinfo: fn(pf: self ref Pfile, nil: array of int); +}; + +DBInfo: adt { + name: string; # database name on Palm + attr: int; # file attributes (defined below) + dtype: string; # database type (byte[4]) + version: int; # version of data layout, defined by application + creator: string; # creating application (byte[4]) + ctime: int; # creation time + mtime: int; # modification time + btime: int; # last backup + modno: int; # modification number + uidseed: int; # unique record ID seed + + new: fn(name: string, attr: int, dtype: string, + version: int, creator: string): ref DBInfo; +}; + +Entry: adt { + id: int; # resource: id; record: unique ID + offset: int; # offset in file + size: int; # size in bytes + name: int; # resource entry only + attr: int; # record entry only +}; + +Record: adt { + id: int; # resource: ID; data: unique record ID + index: int; # record index (origin 0) + name: int; # byte[4]: resource record only + attr: int; # attributes, defined below, data record only + cat: int; # category, data record only + data: array of byte; # content of record + +. # new: fn(size: int): ref Record; +}; + +Categories: adt { + renamed: int; # which categories have been renamed + labels: array of string; # category names + uids: array of int; # corresponding unique IDs + lastuid: int; # last unique ID assigned + appdata: array of byte; # remaining application-specific data + + new: fn(labels: array of string): ref Categories; + unpack: fn(a: array of byte): ref Categories; + pack: fn(c: self ref Categories): array of byte; +}; + +Doc: adt { + version: int; + length: int; # uncompressed + nrec: int; # text records only + recsize: int; # uncompressed + position: int; + sizes: array of int; # sizes of uncompressed records + + open: fn(file: ref Pfile): (ref Doc, string); + read: fn(doc: self ref Doc, i: int): (string, string); + iscompressed: fn(doc: self ref Doc): int; + unpacktext: fn(doc: self ref Doc, a: array of byte): + (string, string); + textlength: fn(doc: self ref Doc, a: array of byte): int; +}; + +init: fn(): string; + +filename: fn(s: string): string; +dbname: fn(s: string): string; + +gets: fn(a: array of byte): string; +puts: fn(a: array of byte, s: string); +get2: fn(a: array of byte): int; +get3: fn(a: array of byte): int; +get4: fn(a: array of byte): int; +put2: fn(a: array of byte, v: int); +put3: fn(a: array of byte, v: int); +put4: fn(a: array of byte, v: int); +.EE +.SH DESCRIPTION +.B Palmfile +provides read-only access to files in the Palm™ database and document formats. +It currently handles three types of files: +Palm Database +.RB ( .pdb ) +files, which store data for applications; +Palm Resource +.RB ( .prc ) +files, which store code resources and user interface resource elements; +and +Palm Doc +.RB ( .doc ) +files, which store compressed documents for the Palm document and e-book readers. +Database and resource files have a similar structure, with slight differences +in representation, and differing mainly in how the contents are used. +.PP +.B Init +must be called before any other function in the file. +It returns a diagnostic if it cannot initialise the module. +.PP +.B Pfile +represents an open Palm file of any type: +.TP +.B open() +Opens file +.I name +with the given +.I mode +(which must currently be +.BR Sys->OREAD ) +and returns a tuple +.RI ( pf , err ). +.I Pf +is a new +.B Pfile +instance giving access to the file, +or nil if the open failed, in which case the +.I err +string contains a diagnostic. +.TP +.IB pf .close() +Close the file (needed only when writing to a file is eventually supported). +.TP +.IB pf .read( index ) +Returns a tuple +.RI ( rec,\ err ) +where +.I rec +is a +.B Record +containing the data of the record +with the given +.I index +(origin 0), or +nil if no such record index exists or it cannot be read. +In the latter case, +.I err +is a diagnostic string. +.TP +.IB pf .stat() +Return the database information for +.IR pf . +.TP +.B entries +An array of +.B Entry +values (see below), one per record. +The length of the array is consequently the length of +the file in records. +It can be nil or empty. +.TP +.B appinfo +Optional application-specific data (see +.B Categories +below). +.TP +.B sortinfo +Optional application-specific data (typically +an array of record IDs in a chosen sorting order). +.TP +.B fname +File name given to +.BR Pfile.open . +.PP +.B DBInfo +gives the database information for a file: +.TF creator +.PD +.TP +.B name +Database name used on the Palm, maximum of 31 characters. +.TP +.B attr +A bit set of file attributes, containing the following values: +.RS +.TF Fappinfodirty +.PD +.TP +.B Fresource +File is a resource file +.RB ( .prc ) +not a database file +.RB ( .pdb ). +.TP +.B Fronly +File is read only. +.TP +.B Fappinfodirty +Application information has changed. +.TP +.B Fbackup +No conduit program exists (the whole file must be backed up). +.TP +.B Foverwrite +Overwrite older copy if present. +.TP +.B Freset +Reset PDA after installing this file. +.TP +.B Fprivate +Don't allow copy of this file to be beamed. +.RE +.TP +.B dtype +String identifying database type (up to 4 characters). +It is usually the string +\f5"appI"\fP for resource files. +.TP +.B version +Identifies the version of the data format (application specific). +.TP +.B creator +String identifying creating application (up to 4 characters). +.TP +.B ctime +File creation time, in seconds from the Inferno epoch (see +.IR daytime (2)). +.TP +.B mtime +Time file last modified, in seconds from the epoch. +.TP +.B btime +Time file last backed up, in seconds from the epoch. +.TP +.B uidseed +Seed for generating unique record IDs (typically set to 0 for database files, +always 0 for resource files). +.TP +.BI new( name,\ attr,\ dtype,\ creator ) +Return a new +.B DBInfo +with the given values. +.PP +In some applications, it is useful to use a data base name +(ie, +.BR DBInfo.name ) +as a component of an Inferno file name. +The device allows space and slash characters in names, though, +which makes it hard to use the name directly. +.B Filename +maps each space character +in +.I s +to U+00A0 (unpaddable space) +and each slash character to U+2215 (`division /'), +and returns the result. +.B Dbname +maps the other way. +.SS Entries and Records +Each record in the file is represented by an +.B Entry +in memory, which holds the record's essential attributes, +leaving the data on file. +The meaning of some of the elements depends on whether +the file is a data file or a resource file. +.TF offset +.PD +.TP +.B id +Resource ID, 16 bits (resource file); unique record ID, 24 bits (data file). +.TP +.B offset +Offset in file, in bytes. +.TP +.B size +Size of record in bytes. +.TP +.B name +Name of the resource (resource record only). +.TP +.B attrs +Record attributes (data record only): +.RS +.TF Rarchive +.PD +.TP +.B Rdelete +Delete the record when file next synchronised. +.TP +.B Rdirty +Record has been modified. +.TP +.B Rinuse +Record in use (not typically used in Inferno). +.TP +.B Rsecret +Record is secret (shown on the device only with use of a password). +.TP +.B Rarchive +Archive this record when file next synchronised. +.TP +.B Rmcat +Mask for the 4-bit category field (in +.B Entry.attrs +only). +.RE +.PP +Records read from the file are represented by a +.B Record +adt containing its data and associated values. +Some fields are valid only for particular classes of records. +.TF index +.PD +.TP +.B id +Resource or record ID, as for +.BR Entry . +.TP +.B index +Index (origin 0) of the record in the file. +.TP +.B name +Resource name (resource record only). +.TP +.B attr +Record attributes, as above (data record only). +.TP +.B cat +Record's category ID (data record only). +.TP +.B data +The actual data. +.SS Application data +The contents of both the ``application information'' and ``sort information'' sections of the file +are defined by an application in general. +Even so, both have conventional uses with many Palm applications. +The Palm software often assigns data records to particular categories (eg, ``Business'' or ``Personal''), +and stores up to 16 category names and IDs in the application data in a fixed format +(possibly followed by further data that is application specific). +This is represented by an instance of +.BR Categories , +which provides the following: +.TF renamed +.PD +.TP +.B renamed +Bit set indicating which categories have been renamed (for category 0, bit +.BR 1<<0 , +for 1, bit +.BR 1<<1 , +and so on). +.TP +.B labels +Array of 16 category labels. +.TP +.B uids +Array of 16 category IDs, each in the range 0 to 255. +(It is said that the Palm itself assigns 0 to 127 and desktop applications assign 128 to 255.) +.TP +.B lastuid +Last unique category ID assigned. +.TP +.B appdata +Any data that remained after unpacking the category data. +.TP +.BI new( labels ) +Return a new +.B Categories +value for the given array of +.IR labels , +assigning unique IDs to each in turn, starting from 128. +There can be at most 16 labels; if there are fewer, the remaining labels will be marked as unused +(empty strings). +.TP +.BI unpack( a ) +Unpack the application data in array +.I a +(typically +.IB pf .appinfo +for some +.B Pfile +.IR pf ), +returning a reference to a new +.B Categories +instance. +A nil value is returned if the array is too short to hold valid category data. +.TP +.IB c .pack() +Pack +.I c +into a form suitable for writing back to a file's application information area. +.PP +Binary data in Palm files is typically encoded in big-endian form. +.B Palmfile +functions account for that internally, but some Palm applications might use +big-endian data in their own data records. +Several functions are therefore provided to decode and encode big-endian data: +.BI get n +retrieves an integer from the first +.I n +bytes of array +.IR a ; +.BI put n +stores a big-endian representation of the value +.I v +in the first +.I n +bytes of array +.IR a . +.PP +Strings are stored in fixed-length arrays of bytes, always terminated by a zero byte. +The character encoding is (apparently) Latin-1 (ISO 8859-1), not UTF-8, +so functions +.B gets +and +.B puts +are provided to convert between that representation and a Limbo string. +.SS Documents +.B Doc +provides read-only access to Palm documents and (unencrypted) e-books: +.TF position +.PD +.TP +.BI open( file ) +Given a +.B Pfile +.IR file , +return a tuple +.RI ( doc,\ err ) +where +.I doc +is a new +.B Doc +instance giving access to the document contents in +.IR file . +If an error occurs, in particular if +.I file +does not appear to be a valid Palm document, +.I doc +is nil and the string +.I err +diagnoses the error. +.TP +.IB doc .iscompressed() +Returns true (non-zero) if the document is compressed; returns false (zero) otherwise. +.TP +.IB doc .read( i ) +Read text record with index +.I i +(origin 0), +returning a tuple +.RI ( s,\ err ) +where +.I s +is the uncompressed text for record +.IR i , +or nil if the record does not exist (or there is an error reading it). +On any error, +.I err +is a diagnostic string. +Note that +.I i +is an index into the set of text records, and is not an index into the set of all records. +It must be no greater than +.IB doc .nrec . +.IB doc .unpacktext( a ) +Returns a tuple +.RI ( s,\ err ) +where +.I s +is the text in array +.IR a , +after uncompressing if +.I doc +contains compressed records. +Following Palm conventions, the text is assumed to be written in the Latin-1 encoding (ISO-8859-1). +If it is compressed but the data in +.I a +is corrupt (cannot be uncompressed), +.I s +is nil and +.I err +diagnoses the problem. +.TP +.IB doc .textlength( a ) +Returns the number of bytes required to store the text in array +.I a +once it has been uncompressed (if necessary). +.TP +.B version +The document's version number. +.TP +.B length +The length of the whole document in bytes, when uncompressed. +.TP +.B nrec +Number of text records in the document. +.TP +.B recsize +Size of uncompressed text records. +.TP +.B position +Possibly records the position where reading last stopped. +.TP +.B sizes +Array giving sizes of all text records, once uncompressed. +.PP +Most document-reading applications require only +.B Doc.open +and +.BR Doc.read , +and perhaps +.BR Doc.length +to guide the construction of scroll bars (for instance). +.SH SOURCE +.B /appl/lib/palmfile.b +.SH SEE ALSO +.IR "Palm® File Format Specification" , +Gary Hillerson, Palm Inc., +Document Number 3008-004, +1 May 2001. +. br +.IR "[Palm®] standard text document file format" , +Paul Lucas, 18 August 1998. |