GNU Info

Info Node: (bbdb.info)Internals

(bbdb.info)Internals


Next: Mailing Lists Prev: Utilities Up: Top
Enter node , (file) or (file)node

Internals
=========

   This section is currently a dumping ground for things that should
eventually go here, but were found elsewhere in the file.

   INFORMATION IN THIS SECTION IS FOR INFORMATIONAL PURPOSES ONLY.  IT
SHOULD NOT BE TAKEN AS DOCUMENTATION OF AN EXTERNAL API.  EVERYTHING
LISTED BELOW IS SUBJECT TO CHANGE WITHOUT NOTICE

   The first time you use one of the BBDB commands, this file is read
into an emacs buffer, and remains there.  As you make changes to the
database, this buffer is changed as well, ensuring that if it is
auto-saved, it will be saved in its most current state.

BBDB data file format
---------------------

   The data file is arranged in a hierarchical fashion.  At the top
level are vectors, with one vector per database record.  It is very
important that each vector be on its own line, as the BBDB builds and
stores markers based on this layout.  The markers are then used to
increase the speed of database modifications (more on this later).  The
record vectors contain the individual fields of the record.  These
fields can be of any type, but are currently integers, strings, lists of
strings, alists, vectors, or lists of vectors.  In the case of fields
that contain one or more vectors, they can be further broken down in
terms of the fields of their component vectors.

   In an effort to provide a more concrete example to illustrate the
above, and to provide a reference for database accessor and modifier
functions, we describe the database format below.  This description
starts with the fields of the individual record vectors, and drills
down through the vectors used by some of the fields.

Record Vectors
..............

Name      Type           Accessor and Modifier      Description
First     String         `bbdb-record-firstname'    Entity's first name
name                     `bbdb-record-set-firstname'
Last name String         `bbdb-record-lastname'     Entity's last name
                         `bbdb-record-set-lastname' 
AKAs      List of        `bbdb-record-aka'          Alternate names for
          Strings        `bbdb-record-set-aka'      entity
Company   String         `bbdb-record-company'      Company with which
                         `bbdb-record-set-company'  entity is associated
Phones    List of        `bbdb-record-phones'       List of phone number
          Vectors        `bbdb-record-set-phones'   vectors
Addresses List of        `bbdb-record-addresses'    List of address vectors
          Vectors        `bbdb-record-set-addresses'
Net       List of        `bbdb-record-net'          List of network
address   Strings        `bbdb-record-set-net'      addresses
Notes     String or      `bbdb-record-raw-notes'    String or Association
          Alist          `bbdb-record-set-raw-notes'list of note fields
                                                    (strings)
Cache     Vector         `bbdb-record-cache'        Record cache.
                         `bbdb-record-set-cache'    Internal version only.

   The phone, address and cache vector fields are described below.
Please note that, as indicated in the table above, the cache is present
only in the internal version of the database - it is not written out as
part of the `.bbdb' file.

   In addition, the accessor and modifier functions for the notes alist
are described.

Phone Vectors
.............

   To access the fields in the below table, you must first get the list
of phone vectors using the `bbdb-record-phones' function.  Note that if
you alter the phones field with the `bbdb-record-set-phones' function,
you are altering the entire phones list for the given record.  Use the
modifier functions below for modifications to individual phone vectors.

Name      Type           Accessor and Modifier      Description
Location  String         `bbdb-phone-location'      Phone number identifier
                         `bbdb-phone-set-location'  
Area      Integer        `bbdb-phone-area'          Area code for phone
                         `bbdb-phone-set-area'      number
Exchange  Integer        `bbdb-phone-exchange'      Exchange (aka prefix)
                         `bbdb-phone-set-exchange'  for phone number
Suffix    Integer        `bbdb-phone-suffix'        Suffix for phone number
                         `bbdb-phone-set-suffix'    
Extension Integer        `bbdb-phone-extension'     Phone number extension
                         `bbdb-phone-set-extension' (`0' if none)

Address Vectors
...............

   To access the fields in the below table, you must first get the list
of address vectors using the `bbdb-record-addresses' function.  Note
that if you alter the addresses field with the
`bbdb-record-set-addresses' function, you are altering the entire
addresses list for the given record.  Use the modifier functions below
for modifications to individual address vectors.

Name      Type           Accessor and Modifier      Description
Location  String         `bbdb-address-location'    Address identifier
                         `bbdb-address-set-location'
Streets   List           `bbdb-address-streets'     List of street address
                         `bbdb-address-set-streets' lines.  `nil' if none.
Street3   String         `bbdb-address-street3'     Third line of street
                         `bbdb-address-set-street3' address.  "" if none.
City      String         `bbdb-address-city'        City name
                         `bbdb-address-set-city'    
State     String         `bbdb-address-state'       State abbreviation
                         `bbdb-address-set-state'   
Zip       Integer        `bbdb-address-zip'         Zip code
          (american)     `bbdb-address-set-zip'     
            List                                    
          (non-american)                            
Country   String         `bbdb-address-country'     Country
                         `bbdb-address-set-country' 

Cache Vector
............

   This vector is present only in the internal database representation.
It is not written out to the database file because it contains
information aggregated from the rest of the record that is
reconstructed when the database is read.  To write the cache
information to the database file would increase the risk of database
inconsistency, and would violate the principles of normalization.

   To access the cache fields using the functions listed below that
begin with `bbdb-cache-', you must first get the cache vector using the
`bbdb-record-cache' function.  The functions that begin with
`bbdb-record-' get the cache vector internally.  Note that if you alter
the cache field in the high-level record with the
`bbdb-record-set-cache' function, you are altering the entire cache
vector for the given record.  Use the modifier functions below for
modifications to individual cache fields.

Name        Type         Accessor and Modifier      Description
Name Cache  String       `bbdb-cache-namecache'     Preconcatenated name
                         `bbdb-cache-set-namecache' of entity
Sort Key    String       `bbdb-cache-sortkey'       Preconcatenated sort
                         `bbdb-cache-set-sortkey'   key for record
Marker      Marker       `bbdb-cache-marker'        Marker in `.bbdb' for
                         `bbdb-record-marker'       start of record
                         `bbdb-cache-set-marker'    
                         `bbdb-record-set-marker'   
Deleted     Boolean      `bbdb-cache-deleted-p'     Set to `t' if record
                         `bbdb-record-deleted-p'    has been deleted,
                         `bbdb-cache-set-deleted-p' `nil' if not
                         `bbdb-record-set-deleted-p'

   The functions listed above will return `nil' if their respective
cache fields are not set.  The functions listed below will return the
value of their cache fields if set, but will also build (and set) the
correct field values if the fields are unset:

`bbdb-record-name'
     Return the name in the Name Cache field of the cache (if set).  If
     the name has not been built yet (if the field is `nil'), the name
     is built, stored in the Name Cache field, and returned.

`bbdb-record-sortkey'
     Return the name it the Sort Key field of the cache (if set).  If
     the Sort Key field has not yet been set (if the field is `nil'),
     the Sort Key is built, stored in the Sort Key field, and returned.

Notes String or Alist
.....................

   If there is only a single note for a given record, the notes field
for that record will be a string.  If there is more than one note, the
notes field will be an association list (alist) with elements of the
form

                           ( NAME . VALUE )

where NAME is the symbol for the name of the note, and VALUE is the
value of the note.

Example BBDB record
...................


automatically generated by info2www version 1.2.2.9