.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Palm::StdAppInfo 3pm" .TH Palm::StdAppInfo 3pm "2016-04-23" "perl v5.22.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Palm::StdAppInfo \- Handle standard AppInfo blocks in Palm OS PDBs .SH "VERSION" .IX Header "VERSION" This document describes version 1.400 of Palm::StdAppInfo, released March 14, 2015 as part of Palm version 1.400. .SH "SYNOPSIS" .IX Header "SYNOPSIS" Usually: .PP .Vb 2 \& package MyPDBHandler; \& use Palm::StdAppInfo(); # Note the parentheses \& \& @ISA = qw( Palm::StdAppInfo ); \& \& use constant APPINFO_PADDING = 1; \& \& sub ParseAppInfoBlock { \& my $self = shift; \& my $data = shift; \& my $appinfo = {}; \& \& &Palm::StdAppInfo::parse_StdAppInfo($appinfo, $data); \& \& $app_specific_data = $appinfo\->{other}; \& } \& \& sub PackAppInfoBlock { \& my $self = shift; \& my $retval; \& \& $self\->{appinfo}{other} = ; \& $retval = &Palm::StdAppInfo::pack_StdAppInfo($self\->{appinfo}); \& return $retval; \& } .Ve .PP Or as a standalone \f(CW\*(C`PDB\*(C'\fR helper class: .PP .Vb 1 \& use Palm::StdAppInfo; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Many Palm applications use a common format for keeping track of categories. The \f(CW\*(C`Palm::StdAppInfo\*(C'\fR class deals with this common format: .PP .Vb 2 \& $pdb = new Palm::PDB; \& $pdb\->Load("myfile.pdb"); \& \& @categories = @{ $pdb\->{appinfo}{categories} }; \& $lastUniqueID = $pdb\->{appinfo}{lastUniqueID}; \& $other = $pdb\->{appinfo}{other}; .Ve .PP where: .PP \&\f(CW@categories\fR is an array of references-to-hash: .ie n .IP """$cat = $categories[0];""" 4 .el .IP "\f(CW$cat = $categories[0];\fR" 4 .IX Item "$cat = $categories[0];" .PD 0 .ie n .IP """$cat\->{name}""" 4 .el .IP "\f(CW$cat\->{name}\fR" 4 .IX Item "$cat->{name}" .PD The name of the category, a string of at most 16 characters. .ie n .IP """$cat\->{id}""" 4 .el .IP "\f(CW$cat\->{id}\fR" 4 .IX Item "$cat->{id}" The category \s-1ID,\s0 an integer in the range 0\-255. Each category has a unique \s-1ID.\s0 By convention, 0 is reserved for the \*(L"Unfiled\*(R" category; IDs assigned by the Palm are in the range 1\-127, and IDs assigned by the desktop are in the range 128\-255. .ie n .IP """$cat\->{renamed}""" 4 .el .IP "\f(CW$cat\->{renamed}\fR" 4 .IX Item "$cat->{renamed}" A boolean. This field is true iff the category has been renamed since the last sync. .PP \&\f(CW$lastUniqueID\fR is (I think) the last category \s-1ID\s0 that was assigned. .PP \&\f(CW$other\fR is any data that follows the category list in the AppInfo block. If you're writing a helper class for a \s-1PDB\s0 that includes a category list, you should parse this field to get any data that follows the category list; you should also make sure that this field is initialized before you call \f(CW&Palm::StdAppInfo::pack_AppInfo\fR. .SS "\s-1APPINFO_PADDING\s0" .IX Subsection "APPINFO_PADDING" Normally, the AppInfo block includes a byte of padding at the end, to bring its length to an even number. However, some databases use this byte for data. .PP If your database uses the padding byte for data, then your \&\f(CW&ParseAppInfoBlock\fR method (see \*(L"\s-1SYNOPSIS\*(R"\s0) should call \&\f(CW&parse_StdAppInfo\fR with a true \f(CW$nopadding\fR argument. .PP If, for whatever reason, you wish to inherit \&\f(CW&StdAppInfo::ParseAppInfoBlock\fR, then add .PP .Vb 1 \& use constant APPINFO_PADDING => 0; .Ve .PP to your handler package, to tell it that the padding byte is really data. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "seed_StdAppInfo" .IX Subsection "seed_StdAppInfo" .Vb 1 \& &Palm::StdAppInfo::seed_StdAppInfo(\e%appinfo); .Ve .PP Creates the standard fields in an existing AppInfo hash. Usually used to ensure that a newly-created AppInfo block contains an initialized category array: .PP .Vb 1 \& my $appinfo = {}; \& \& &Palm::StdAppInfo::seed_StdAppInfo($appinfo); .Ve .PP Note: this is not a method. .SS "newStdAppInfo" .IX Subsection "newStdAppInfo" .Vb 1 \& $appinfo = Palm::StdAppInfo\->newStdAppInfo; .Ve .PP Like \f(CW\*(C`seed_StdAppInfo\*(C'\fR, but creates an AppInfo hash and returns a reference to it. .SS "new" .IX Subsection "new" .Vb 1 \& $pdb = new Palm::StdAppInfo; .Ve .PP Create a new \s-1PDB,\s0 initialized with nothing but a standard AppInfo block. .PP There are very few reasons to use this, and even fewer good ones. If you're writing a helper class to parse some \s-1PDB\s0 format that contains a category list, then you should make that helper class a subclass of \&\f(CW\*(C`Palm::StdAppInfo\*(C'\fR. .SS "parse_StdAppInfo" .IX Subsection "parse_StdAppInfo" .Vb 1 \& $len = &Palm::StdAppInfo::parse_StdAppInfo(\e%appinfo, $data, $nopadding); .Ve .PP This function (this is not a method) is intended to be called from within a \s-1PDB\s0 helper class's \f(CW\*(C`ParseAppInfoBlock\*(C'\fR method. .PP \&\f(CW\*(C`parse_StdAppInfo()\*(C'\fR parses a standard AppInfo block from the raw data \f(CW$data\fR and fills in the fields in \f(CW%appinfo\fR. It returns the number of bytes parsed. .PP \&\f(CW$nopadding\fR is optional, and defaults to false. Normally, the AppInfo block includes a padding byte at the end. If \f(CW$nopadding\fR is true, then \f(CW&parse_StdAppInfo\fR assumes that the padding byte is application data, and includes it in \f(CW$appinfo{\*(Aqother\*(Aq}\fR, so that the caller can parse it. .SS "ParseAppInfoBlock" .IX Subsection "ParseAppInfoBlock" .Vb 2 \& $pdb = new Palm::StdAppInfo; \& $pdb\->ParseAppInfoBlock($data); .Ve .PP If your application's AppInfo block contains standard category support and nothing else, you may choose to just inherit this method instead of writing your own \f(CW\*(C`ParseAppInfoBlock\*(C'\fR method. Otherwise, see the example in \*(L"\s-1SYNOPSIS\*(R"\s0. .SS "pack_StdAppInfo" .IX Subsection "pack_StdAppInfo" .Vb 1 \& $data = &Palm::StdAppInfo::pack_StdAppInfo(\e%appinfo); .Ve .PP This function (this is not a method) is intended to be called from within a \s-1PDB\s0 helper class's \f(CW\*(C`PackAppInfoBlock\*(C'\fR method. .PP \&\f(CW\*(C`pack_StdAppInfo\*(C'\fR takes an AppInfo hash and packs it as a string of raw data that can be written to a \s-1PDB.\s0 .PP Note that if you're using this inside a helper class's \&\f(CW\*(C`PackAppInfoBlock\*(C'\fR method, you should make sure that \&\f(CW$appinfo{other}\fR is properly initialized before you call \&\f(CW&Palm::StdAppInfo::pack_StdAppInfo\fR. .PP \&\f(CW$nopadding\fR is optional, and defaults to false. Normally, the AppInfo block includes a byte of padding at the end. If \f(CW$nopadding\fR is true, then \f(CW&pack_StdAppInfo\fR doesn't include this byte of padding, so that the application can use it. .SS "PackAppInfoBlock" .IX Subsection "PackAppInfoBlock" .Vb 2 \& $pdb = new Palm::StdAppInfo; \& $data = $pdb\->PackAppInfoBlock(); .Ve .PP If your application's AppInfo block contains standard category support and nothing else, you may choose to just inherit this method instead of writing your own \f(CW\*(C`PackAppInfoBlock\*(C'\fR method. Otherwise, see the example in \*(L"\s-1SYNOPSIS\*(R"\s0. .SS "addCategory" .IX Subsection "addCategory" .Vb 1 \& $pdb\->addCategory($name [, $id [, $renamed]]); .Ve .PP Adds a category to \f(CW$pdb\fR. .PP The \f(CW$name\fR argument specifies the new category's name. .PP The optional \f(CW$id\fR argument specifies the new category's numeric \s-1ID\s0; if omitted or undefined, &addCategory will pick one. .PP The optional \f(CW$renamed\fR argument is a boolean value indicating whether the new category should be marked as having been modified. This defaults to true since, conceptually, &addCategory doesn't really add a category: it finds one whose name happens to be empty, and renames it. .PP Returns a true value if successful, false otherwise. In case of failure, &addCategory sets \f(CW$Palm::StdAppInfo::error\fR to an error message. .SS "deleteCategory" .IX Subsection "deleteCategory" .Vb 1 \& $pdb\->deleteCategory($name); .Ve .PP Deletes the category with name \f(CW$name\fR. Actually, though, it doesn't delete the category: it just changes its name to the empty string, and marks the category as renamed. .SS "renameCategory" .IX Subsection "renameCategory" .Vb 1 \& $pdb\->renameCategory($oldname, $newname); .Ve .PP Renames the category named \f(CW$oldname\fR to \f(CW$newname\fR. .PP If successful, returns a true value. If there is no category named \&\f(CW$oldname\fR, returns a false value and sets \f(CW$Palm::StdAppInfo::error\fR to an error message. .SH "SEE ALSO" .IX Header "SEE ALSO" Palm::PDB .SH "CONFIGURATION AND ENVIRONMENT" .IX Header "CONFIGURATION AND ENVIRONMENT" Palm::StdAppInfo requires no configuration files or environment variables. .SH "INCOMPATIBILITIES" .IX Header "INCOMPATIBILITIES" None reported. .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" No bugs have been reported. .SH "AUTHORS" .IX Header "AUTHORS" Andrew Arensburger \f(CW\*(C`\*(C'\fR .PP Currently maintained by Christopher J. Madsen \f(CW\*(C`\*(C'\fR .PP Please report any bugs or feature requests to \f(CW\*(C`\*(C'\fR or through the web interface at . .PP You can follow or contribute to p5\-Palm's development at . .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Andrew Arensburger & Alessandro Zummo. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. .SH "DISCLAIMER OF WARRANTY" .IX Header "DISCLAIMER OF WARRANTY" \&\s-1BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE \*(L"AS IS\*(R" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.\s0 .PP \&\s-1IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE \s0(\s-1INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE\s0), \s-1EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.\s0