Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Palm::StdAppInfo(3)   User Contributed Perl Documentation  Palm::StdAppInfo(3)

NAME
       Palm::StdAppInfo	- Handles standard AppInfo block (categories)

SYNOPSIS
       Usually:

	   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} = <pack application-specific data>;
	       $retval = &Palm::StdAppInfo::pack_StdAppInfo($self->{appinfo});
	       return $retval;
	   }

       Or as a standalone "PDB"	helper class:

	   use Palm::StdAppInfo;

DESCRIPTION
       Many Palm applications use a common format for keeping track of
       categories.  The	"Palm::StdAppInfo" class deals with this common
       format:

	       $pdb = new Palm::PDB;
	       $pdb->Load("myfile.pdb");

	       @categories   = @{$pdb->{appinfo}{categories}};
	       $lastUniqueID =	 $pdb->{appinfo}{lastUniqueID};
	       $other	     =	 $pdb->{appinfo}{other};

       where:

       @categories is an array of references-to-hash:

       "$cat = $categories[0];"
	   "$cat->{name}"
	       The name	of the category, a string of at	most 16	characters.

	   "$cat->{id}"
	       The category ID,	an integer in the range	0-255. Each category
	       has a unique ID.	By convention, 0 is reserved for the "Unfiled"
	       category; IDs assigned by the Palm are in the range 1-127, and
	       IDs assigned by the desktop are in the range 128-255.

	   "$cat->{renamed}"
	       A boolean. This field is	true iff the category has been renamed
	       since the last sync.

	   $lastUniqueID is (I think) the last category	ID that	was assigned.

	   $other is any data that follows the category	list in	the AppInfo
	   block. If you're writing a helper class for a PDB 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
	   &Palm::StdAppInfo::pack_AppInfo.

   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.

       If your database	uses the padding byte for data,	then your
       &ParseAppInfoBlock method (see "SYNOPSIS") should call
       &parse_StdAppInfo with a	true $nopadding	argument.

       If, for whatever	reason,	you wish to inherit
       &StdAppInfo::ParseAppInfoBlock, then add

	   use constant	APPINFO_PADDING	=> 0;

       to your handler package,	to tell	it that	the padding byte is really
       data.

FUNCTIONS
   seed_StdAppInfo
	   &Palm::StdAppInfo::seed_StdAppInfo(\%appinfo);

       Creates the standard fields in an existing AppInfo hash.	Usually	used
       to ensure that a	newly-created AppInfo block contains an	initialized
       category	array:

	       my $appinfo = {};

	       &Palm::StdAppInfo::seed_StdAppInfo($appinfo);

       Note: this is not a method.

   newStdAppInfo
	   $appinfo = Palm::StdAppInfo->newStdAppInfo;

       Like "seed_StdAppInfo", but creates an AppInfo hash and returns a
       reference to it.

   new
	   $pdb	= new Palm::StdAppInfo;

       Create a	new PDB, initialized with nothing but a	standard AppInfo
       block.

       There are very few reasons to use this, and even	fewer good ones. If
       you're writing a	helper class to	parse some PDB format that contains a
       category	list, then you should make that	helper class a subclass	of
       "Palm::StdAppInfo".

   parse_StdAppInfo
	   $len	= &Palm::StdAppInfo::parse_StdAppInfo(\%appinfo, $data,	$nopadding);

       This function (this is not a method) is intended	to be called from
       within a	PDB helper class's "ParseAppInfoBlock" method.

       "parse_StdAppInfo()" parses a standard AppInfo block from the raw data
       $data and fills in the fields in	%appinfo. It returns the number	of
       bytes parsed.

       $nopadding is optional, and defaults to false. Normally,	the AppInfo
       block includes a	padding	byte at	the end. If $nopadding is true,	then
       &parse_StdAppInfo assumes that the padding byte is application data,
       and includes it in $appinfo{'other'}, so	that the caller	can parse it.

   ParseAppInfoBlock
	   $pdb	= new Palm::StdAppInfo;
	   $pdb->ParseAppInfoBlock($data);

       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	"ParseAppInfoBlock" method. Otherwise, see the example
       in "SYNOPSIS".

   pack_StdAppInfo
	   $data = &Palm::StdAppInfo::pack_StdAppInfo(\%appinfo);

       This function (this is not a method) is intended	to be called from
       within a	PDB helper class's "PackAppInfoBlock" method.

       "pack_StdAppInfo" takes an AppInfo hash and packs it as a string	of raw
       data that can be	written	to a PDB.

       Note that if you're using this inside a helper class's
       "PackAppInfoBlock" method, you should make sure that $appinfo{other} is
       properly	initialized before you call
       &Palm::StdAppInfo::pack_StdAppInfo.

       $nopadding is optional, and defaults to false. Normally,	the AppInfo
       block includes a	byte of	padding	at the end. If $nopadding is true,
       then &pack_StdAppInfo doesn't include this byte of padding, so that the
       application can use it.

   PackAppInfoBlock
	   $pdb	= new Palm::StdAppInfo;
	   $data = $pdb->PackAppInfoBlock();

       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	"PackAppInfoBlock" method. Otherwise, see the example
       in "SYNOPSIS".

   addCategory
	   $pdb->addCategory($name [, $id [, $renamed]]);

       Adds a category to $pdb.

       The $name argument specifies the	new category's name.

       The optional $id	argument specifies the new category's numeric ID; if
       omitted or undefined, &addCategory will pick one.

       The optional $renamed 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.

       Returns a true value if successful, false otherwise. In case of
       failure,	&addCategory sets $Palm::StdAppInfo::error to an error
       message.

   deleteCategory
	   $pdb->deleteCategory($name);

       Deletes the category with name $name. Actually, though, it doesn't
       delete the category: it just changes its	name to	the empty string, and
       marks the category as renamed.

   renameCategory
	   $pdb->renameCategory($oldname, $newname);

       Renames the category named $oldname to $newname.

       If successful, returns a	true value. If there is	no category named
       $oldname, returns a false value and sets	$Palm::StdAppInfo::error to an
       error message.

AUTHOR
       Andrew Arensburger <arensb@ooblick.com>

SEE ALSO
       Palm::PDB(3)

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 78:
	   '=item' outside of any '=over'

       Around line 108:
	   You forgot a	'=back'	before '=head2'

perl v5.24.1			  2002-11-07		   Palm::StdAppInfo(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | AUTHOR | SEE ALSO | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Palm::StdAppInfo&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help