<!-- $Id: ref-blocks.sgml,v 1.1 1999/05/24 09:25:26 rob Exp $ -->
<chapter id="ref-blocks">
  <title>Blocks</title>

  <para>
    All objects and classes described here are located in the
    <classname/Pyrite.Blocks/ module.  The contents of that module are
    imported into the base package, so everything described in this
    chapter can be accessed directly from the <classname/Pyrite/
    module as well.
  </para>

  <sect1 id="ref-blocks-block">
    <title>Class: Block</title>

    <para>
      A <classname/Block/ object represents a generic chunk of data
      which can be stored in a Pyrite-accessible database.  The
      <classname/Block/ class provides support for conversion between
      an internal representation (a string of raw data) and a more
      useful Python-friendly representation consisting of named
      fields.
    </para>

    <sect2 id="ref-blocks-block-attributes">
      <title>Attributes</title>
      
      <variablelist>
	<varlistentry>
	  <term><structfield/fields/ (<type/dictionary of sequences/)</term>
	  <listitem>
	    <para>Definitions of named fields.  Each key is the name
	      of a field; the corresponding value is a sequence (tuple
	      or list) containing at least two elements.  The first
	      element is a constant specifying the type of the field,
	      and the second element holds the field's default value.
	      Elements beyond the first two are optional, and may be
	      used to specify type-dependent information.</para>

	    <para>The available field types are:</para>
	    
	    <variablelist>
	      <varlistentry>
		<term><literal/FLD_UNKNOWN/</term>
		<listitem>
		  <para>A field of unknown type.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term><literal/FLD_ANY/</term>
		<listitem>
		  <para>A field that may contain any value.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term><literal/FLD_BOOLEAN/</term>
		<listitem>
		  <para>A boolean field.  Its value will be treated as
		    either true or false, no matter what it actually
		    is. (By convention, boolean fields use a value of
		    1 to signify truth, and either 0 or None to
		    signify falsity.)</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term><literal/FLD_INT/</term>
		<listitem>
		  <para>A field containing an integer.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term><literal/FLD_FLOAT/</term>
		<listitem>
		  <para>A field containing a floating-point number.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term><literal/FLD_TIME/</term>
		<listitem>
		  <para>A field containing a date/time value, in the
		    normal Unix format of seconds since the epoch.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term><literal/FLD_TIME_T/</term>
		<listitem>
		  <para>A field containing a date/time value, in the
		    Unix <type/time_t/ format (represented in Python
		    by a 9-element tuple.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term><literal/FLD_LIST/</term>
		<listitem>
		  <para>A field containing a list of values.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>
	The field types are defined as constants at the module level.
      </para>
    </sect2>
    
    <sect2 id="ref-blocks-block-methods">
      <title>Methods</title>

      <variablelist>
	<varlistentry>
	  <term><function/__init__/ (<parameter/raw/=None)</term>
	  <listitem>
	    <para>Create a Block object, setting its initial contents
	      to the supplied raw string, then unpack it so the
	      contents can be accessed as named fields.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/unpack/ (<parameter/raw/)</term>
	  <listitem>
	    <para>Set the contents of the Block to the supplied
	      string, and unpack it so the contents can be accessed as
	      named fields.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/pack/</term>
	  <listitem>
	    <para>Pack the contents of the Block's named fields into a
	      raw string, and return it.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><function/packfields/ (<parameter/format/,
	    <parameter/names/)</term>
	  <listitem>
	    <para>Pack the named fields into a raw string, according
	      to the supplied format string (which should be in the
	      format used by the standard <classname/struct/
	      module).</para>
	    
	    <para>This function is intended as a helper to developers
	      writing a custom <function/pack/ function.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><function/unpackfields/ (<parameter/format/,
	    <parameter/names/, <parameter/raw/)</term>
	  <listitem>
	    <para>Unpack the supplied raw string according to the
	      supplied format string (in the format used by the
	      <classname/struct/ module), putting the values obtained
	      into a series of named fields.</para>
	    
	    <para>This function is intended as a helper to developers
	      writing a custom <function/unpack/ function.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/__getitem__/ (<parameter/name/)</term>
	  <term><function/__setitem__/ (<parameter/name/,
	    <parameter/value/)</term>
	  <term><function/get/ (<parameter/name/,
	    <parameter/default/=None)</term>
	  <term><function/keys/</term>
	  <term><function/values/</term>
	  <term><function/items/</term>
	  <term><function/has_key/ (<parameter/name/)</term>
	  <listitem>
	    <para>Dictionary-like interface to named fields.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><function/__len__/</term>
	  <listitem>
	    <para>Pack the contents of the Block's named fields into a
	      raw string, then return the length of that
	      string.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/dump/ (<parameter/file/=sys.stdout,
	    <parameter/verbose/=0)</term>
	  <listitem>
	    <para>Print the raw contents of the Block to the specified
	      file, in a hex-dump format.  If <parameter/verbose/ is
	      true, print the unpacked values of the Block's named
	      fields as well.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
  </sect1>
  
  <sect1 id="ref-blocks-record">
    <title>Class: Record</title>

    <para>
      A <classname/Record/ object represents a single record in a
      database.
    </para>

    <para>
      <classname/Record/ is a subclass of <classname/Block/.
    </para>

    <sect2 id="ref-blocks-record-attributes">
      <title>Attributes</title>
      
      <variablelist>
	<varlistentry>
	  <term><structfield/deleted/ (<type/boolean/)</term>
	  <listitem>
	    <para>True if the record was deleted by the handheld
	      user.  (Deleted records may be retained in the handheld
	      until synchronization, to allow archiving.)</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><structfield/modified/ (<type/boolean/)</term>
	  <listitem>
	    <para>True if the record has been modified by the handheld
	      user since the last synchronization.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><structfield/busy/ (<type/boolean/)</term>
	  <listitem>
	    <para>True if the record is in use by a handheld
	      application.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><structfield/secret/ (<type/boolean/)</term>
	  <listitem>
	    <para>True if the record has been marked "secret" by the
	      handheld user.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><structfield/archived/ (<type/boolean/)</term>
	  <listitem>
	    <para>True if the record has been archived.  (This
	      attribute is not saved in records on the handheld, or in
	      most other databases.  It is provided so that
	      synchronization software can use it for temporary
	      marking.)</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><structfield/category/ (<type/integer/)</term>
	  <listitem>
	    <para>The record's category.  Currently only values from 0
	      to 15 are valid; 0 is "Unfiled".</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><structfield/id/ (<type/integer/)</term>
	  <listitem>
	    <para>A unique identifier for the record, an integer from
	      0 to 0xFFFFFF.  Since id values should only be assigned
	      by the handheld, a value of 0 can be used to signify "no
	      id assigned yet".</para>
	    </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><structfield/index/ (<type/integer/)</term>
	  <listitem>
	    <para>The index (from 0 to the length of the database) at
	      which this record was found.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
    
    <sect2 id="ref-blocks-record-methods">
      <title>Methods</title>
      
      <variablelist>
	<varlistentry>
	  <term><function/__init__/ (<parameter/raw/='',
	    <parameter/index/=0, <parameter/id/=0, <parameter/attr/=0,
	    <parameter/category/=0)</term>
	  <listitem>
	    <para>Create a new Record object with the specified
	      contents, index, id, boolean attributes, and
	      category.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><function/attributes/</term>
	  <listitem>
	    <para>Return an integer representing the record's boolean
	      attributes, in the same form as they appear on the
	      handheld.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
  </sect1>

  <sect1 id="ref-blocks-appblock">
    <title>Class: AppBlock</title>

    <para>
      An <classname/AppBlock/ object represents the application
      information (or <firstterm/appinfo/) block of a database.  Each
      database may have exactly one associated appinfo block.
    </para>

    <para>
      <classname/AppBlock/ is a subclass of <classname/Block/.
    </para>
  </sect1>
  
  <sect1 id="ref-blocks-categoryappblock">
    <title>Class: CategoryAppBlock</title>

    <para>
      A <classname/CategoryAppBlock/ object represents the appinfo
      block of a database set up to use the standard handheld Category
      Manager.  The Category Manager expects the database's appinfo
      block to begin with certain specific structures; as a result,
      the <classname/CategoryAppBlock/ class defines several named
      fields to represent category information.
    </para>

    <para>
      <classname/CategoryAppBlock/ is a subclass of
      <classname/AppBlock/.
    </para>
    
    <sect2 id="ref-blocks-categoryappblock-fields">
      <title>Fields</title>

      <variablelist>
	<varlistentry>
	  <term><literal/categoryName/ (<type/list(16) of strings/)</term>
	  <listitem>
	    <para>The names of each category.  Category 0 is always
	      called "Unfiled".</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><literal/categoryID/ (<type/list(16) of integers/)</term>
	  <listitem>
	    <para>A unique numeric identifier for each category, used
	      to help the handheld OS keep track of name changes
	      across synchronizations.  Each time a category name is
	      changed, a new identifier is generated.</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><literal/categoryRenamed/ (<type/list(16) of booleans/)</term>
	  <listitem>
	    <para>A flag for each category, true if the category has
	      been renamed since the last synchronization. (?)</para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><literal/categoryLastUniqueID/ (<type/integer/)</term>
	  <listitem>
	    <para>The most recently used unique numeric identifier.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
  </sect1>
  
  <sect1 id="ref-blocks-sortblock">
    <title>Class: SortBlock</title>
    
    <para>
      A <classname/SortBlock/ object represents the sort information
      (or <firstterm/sortinfo/) block of a database.  Each database
      may have exactly one associated sortinfo block.
    </para>

    <important>
      <para>
	The use of sortinfo blocks, and thus <classname/SortBlock/
	objects, is deprecated.  No known application uses them, and the
	standard installation and backup software (including that found
	in Pyrite) does not copy them.
      </para>
    </important>

    <para>
      <classname/SortBlock/ is a subclass of <classname/Block/.
    </para>
  </sect1>
  
  <sect1 id="ref-blocks-resource">
    <title>Class: Resource</title>
    <para>Not described yet...</para>
  </sect1>

  <sect1 id="ref-blocks-prefblock">
    <title>Class: PrefBlock</title>
    <para>Not described yet...</para>
  </sect1>

  <sect1 id="ref-blocks-attributes">
    <title>Attributes</title>
    
    <variablelist>
      <varlistentry>
	<term><literal/FLD_UNKNOWN/</term>
	<term><literal/FLD_ANY/</term>
	<term><literal/FLD_BOOLEAN/</term>
	<term><literal/FLD_INT/</term>
	<term><literal/FLD_FLOAT/</term>
	<term><literal/FLD_TIME/</term>
	<term><literal/FLD_TIME_T/</term>
	<term><literal/FLD_LIST/</term>
	<listitem>
	  <para>Constants used in field definitions.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>
    
  <sect1 id="ref-blocks-functions">
    <title>Functions</title>

    <para>
      The functions in this module are intended for use in
      application-specific subclasses, as an aid to the packing and
      unpacking of data formats used on the handheld.
    </para>
    
    <variablelist>
      <varlistentry>
	<term><function/palm_date_to_tuple/ (<parameter/date/,
	  <parameter/hour/=0, <parameter/minute/=0, <parameter/second/=0)</term>
	<listitem>
	  <para>Convert a date in the format used on the handheld
	    (2-byte packed) into a 9-element time tuple suitable for
	    use with the Python <classname/time/ module.  The
	    <parameter/hour/, <parameter/minute/, and
	    <parameter/second/ parameters may be used to provide
	    contents for the corresponding elements in the returned
	    tuple; otherwise, the return value represents midnight on
	    the specified date.  The return value is presumed to be in
	    the local time zone.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><function/tuple_to_palm_date/ (<parameter/tuple/)</term>
	<listitem>
	  <para>Convert the date portion of a time tuple to the format
	    used on the handheld (2-byte packed).  The time and time
	    zone portions of the tuple are ignored.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><function/trim_null/ (<parameter/string/)</term>
	<listitem>
	  <para>Trim a null-terminated string, removing the null byte
	    and any extraneous garbage after it.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><function/pad_null/ (<parameter/string/, <parameter/length/)</term>
	<listitem>
	  <para>Convert a string to a fixed-width field of
	    <parameter/length/ bytes.  Within the result, the original
	    string is null-terminated and any unused portion is also
	    filled with nulls.  If the string is longer than
	    (<parameter/length/-1) bytes, it will be truncated.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><function/unpack_category_appinfo/ (<parameter/dict/,
	  <parameter/raw/)</term>
	<listitem>
	  <para>Unpack the supplied raw string, assuming that it
	    contains the data structure used by the handheld Category
	    Manager.  Fills in the supplied dictionary with the
	    results, and returns the number of bytes of the raw string
	    that were "consumed".</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><function/pack_category_appinfo/ (<parameter/dict/)</term>
	<listitem>
	  <para>Pack Category Manager information, supplied in a
	    dictionary, into a raw string representing the data
	    structure used on the handheld.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>
</chapter>

<!--Local Variables: -->
<!--sgml-parent-document: ("prg.sgml" "chapter") -->
<!--sgml-doctype: "prg.sgml" -->
<!--End: -->