addressdb.h

palm os 上的中文伴侣源代码

/******************************************************************************
 * Copyright (c) 1995-2005 palmOne, Inc. or its subsidiaries.
 * All rights reserved.
 *****************************************************************************/
/**
 * @defgroup PIM PIM Database Record Structures
 *
 * @{
 * @}
 */
/**
 * @ingroup PIM
 */

/**
 * @file AddressDB.h
 *
 * @brief Contains database record type and constants for Contacts application.
 *
 * Contacts application uses a different record format than the old AddressBook
 * application due to some feature enhancement and new data fields. This file
 * contains the structure of the record in Contacts DB and can be used to access
 * the database directly. One way to utilize this header file is to combine it
 * with the old Address Book source code so that the record packing and
 * unpacking routines are adjusted for the new structure.
 *
 * Please note that accessing the database directly is generally not recommended
 * and this is offered as a temporary solution for 3rd party developers. The
 * structure might change again in the future.
 *
 * <hr>
 */

#ifndef ADDRESSDB_H
#define ADDRESSDB_H

#include "AddrDefines.h"

#include <AppLaunchCmd.h>
#include <DataMgr.h>
#include <DateTime.h>

/** Contacts DB version number */
#define addrDBVersionNum        1

#ifndef appErrVersionIncompatible
#define appErrVersionIncompatible   (appErrorClass | 1) /**< Error code */
#endif

/**
 *  Indices for fields member of AddrDBRecordType (record fields)
 **/
typedef enum
{
    name,
    firstName,
    company,
    title,

    phone1,         /**< Phone fields. */
    phone2,
    phone3,
    phone4,
    phone5,
    phone6,
    phone7,

    chat1,          /**< Instant message id and service. */
    chat2,

    webpage,

    custom1,        /**< Custom fields. */
    custom2,
    custom3,
    custom4,
    custom5,
    custom6,
    custom7,
    custom8,
    custom9,

    address,        /**< Address fields. */
    city,
    state,
    zipCode,
    country,
    address2,
    city2,
    state2,
    zipCode2,
    country2,
    address3,
    city3,
    state3,
    zipCode3,
    country3,

    note,           /**< The note field must not be more than ~32K. */

    birthdayDate,   /**< Birthday info. */
    birthdayMask,   /**< Holds AddressDBBirthdayFlags type. */
    birthdayPreset,


    /***************************************************************************
     * All fields starting from picture will be added as blob
     * Each blob is: 4 bytes id, 2 bytes length and data
     * App blobs will have reserved id (1 to 64k) to keep them separate from
     * third party blobs.
     **************************************************************************/

    pictureInfo,    /**< holds picture blob: id --> 1, data  -->  2 bytes
    picture dirty flag, picture data */

    addressFieldsCount

} AddressFields;

#define firstAddressField           name    /**< First index of address field */
#define firstPhoneField             phone1  /**< First index of phone field */
#define lastPhoneField              phone7  /**< Last index of phone field */

/** Total number of phone fields */
#define numPhoneFields              (lastPhoneField - firstPhoneField + 1)

#define firstChatField              chat1   /**< First index of chat field */
#define lastChatField               chat2   /**< Last index of chat field */

#define firstWebField               webpage /**< First index of web field */
#define lastWebField                webpage /**< Last index of web field */

/**
 *  Field label sub-indices relating to the position of the field
 *  label within a popup list of labels.
 *  e.g.: the phone label popup list first selection is "Work", the
 *        second is "Home", etc.
 **/

typedef enum
{
    workLabel,
    homeLabel,
    faxLabel,
    otherLabel,
    emailLabel,
    mainLabel,
    pagerLabel,
    mobileLabel
} AddressPhoneLabels;

/**
 *  Field label sub-indices relating to the position of the field
 *  label within a popup list of labels.
 *  e.g.: the phone label popup list first selection is "Work", the
 *        second is "Home", etc.
 **/

typedef enum
{
    otherChatLabel,
    aimChatLabel,
    msnChatLabel,
    yahooChatLabel,
    icqChatLabel

} AddressChatLabels;

/**
 *  Field label sub-indices relating to the position of the field
 *  label within a popup list of labels.
 *  e.g.: the phone label popup list first selection is "Work", the
 *        second is "Home", etc.
 **/

typedef enum
{
    workAddressLabel,
    homeAddressLabel,
    otherAddressLabel
} AddressStreetAddressLabels;

/** Maximum length of a field label, excluding NULL terminator: */
#define addrLabelLength             16

/** Phone labels: */
#define numPhoneLabelsStoredFirst   numPhoneFields
#define numPhoneLabelsStoredSecond  (numPhoneLabels - numPhoneLabelsStoredFirst)

/** Labels preceding the address field groups (work, home, other): */
/*@{*/
#define Addr1FieldGroupLabel        phone1
#define Addr2FieldGroupLabel        phone2
#define Addr3FieldGroupLabel        phone4
/*@}*/

/** The first and last custom/renameable labels: */
/*@{*/
#define firstRenameableLabel        custom1
#define lastRenameableLabel         custom9
/*@}*/

/** Last label in the first set of labels: */
#define lastLabel                   addrNumDisplayFields

/** Indices to start of second set of phone, address and chat labels: */
/*@{*/
#define phoneLabelSecondStart       addrNumDisplayFields -1
#define chatLabelstart              addrNumDisplayFields
#define webLabelStart               13
/*@}*/

/** Labels for the "Add field" list of fields: */
/*@{*/
#define numAddFieldLabels           3
#define AddFieldLabelStart          addrNumDisplayFields            \
                                    + numPhoneLabelsStoredSecond    \
                                    + numChatLabels
/*@}*/

/** Total field label count: */
/*@{*/
#define numPictureFieldLabels       3
#define numFieldLabels              addrNumDisplayFields            \
                                    + numPhoneLabelsStoredSecond    \
                                    + numChatLabels                 \
                                    + numAddFieldLabels             \
                                    + numPictureFieldLabels
/*@}*/

/***********************************************************************
 *  Application Packed Record Format Related Data
 *
 *  Note: Records are stored in the database in packed format to
 *        conserve space.  When retrieving a record from the database,
 *        it is unpacked into the AddrDBRecordType.  AddrDBGetRecord()
 *        does the necessary unpacking for you.  When creating a new
 *        record, AddrDBNewRecord(), or saving a record, AddrDBChangeRecord(),
 *        the packing is handled for you.
 ***********************************************************************/

/** @brief Packed record flags.
 *
 * AddrDBRecordFlags indicates the address record bits.  It is used
 * to indicate field changes or fields contained in a packed record.
 * Since there is no 64-bit bitfield, a struct with two unsigned
 * longs is used. Please be sure to use the bit macros (defined
 * later below) to extract the bits, as the bit order may change in
 * future.
 */
typedef struct
{
    union
    {
        struct
        {
            UInt32 reserved     :4;

            UInt32 country      :1; /**< Set if record contains a country. */
            UInt32 zipCode      :1; /**< Set if record contains a zipCode. */
            UInt32 state        :1; /**< Set if record contains a state. */
            UInt32 city         :1; /**< Set if record contains a city. */
            UInt32 address      :1; /**< Set if record contains a address. */

            UInt32 custom9      :1; /**< Set if record contains a custom9. */
            UInt32 custom8      :1; /**< Set if record contains a custom8. */
            UInt32 custom7      :1; /**< Set if record contains a custom7. */
            UInt32 custom6      :1; /**< Set if record contains a custom6. */
            UInt32 custom5      :1; /**< Set if record contains a custom5. */
            UInt32 custom4      :1; /**< Set if record contains a custom4. */
            UInt32 custom3      :1; /**< Set if record contains a custom3. */
            UInt32 custom2      :1; /**< Set if record contains a custom2. */
            UInt32 custom1      :1; /**< Set if record contains a custom1. */

            UInt32 webpage      :1; /**< Set if record contains a URL. */

            UInt32 chat2        :1; /**< Set if record contains an instant
                                         message id 2. */
            UInt32 chat1        :1; /**< Set if record contains an instant
                                         message id 1. */

            UInt32 phone7       :1; /**< Set if record contains a phone7. */
            UInt32 phone6       :1; /**< Set if record contains a phone6. */
            UInt32 phone5       :1; /**< Set if record contains a phone5. */
            UInt32 phone4       :1; /**< Set if record contains a phone4. */
            UInt32 phone3       :1; /**< Set if record contains a phone3. */
            UInt32 phone2       :1; /**< Set if record contains a phone2. */
            UInt32 phone1       :1; /**< Set if record contains a phone1. */
            UInt32 title        :1; /**< Set if record contains a title. */
            UInt32 company      :1; /**< Set if record contains a company. */
            UInt32 firstName    :1; /**< Set if record contains a firstName. */
            UInt32 name         :1; /**< Set if record contains a name (bit 0).
            */

        } bits;
        UInt32 allBits;
    };
    union
    {
        struct
        {
            UInt32 reserved2        :6;
            UInt32 reserved         :12;

            UInt32 birthdayPreset   :1; /**< Set if record contains birthday
                                             preset. */
            UInt32 birthdayMask     :1; /**< Set if record contains birthday
                                             mask. */
            UInt32 birthdayDate     :1; /**< Set if record contains birthday
                                             date. */

            UInt32 note             :1; /**< Set if record contains a note
                                             handle. */

            UInt32 country3         :1; /**< Set if record contains a country3.
                                             */
            UInt32 zipCode3         :1; /**< Set if record contains a zipCode3.
                                             */
            UInt32 state3           :1; /**< Set if record contains a state3. */
            UInt32 city3            :1; /**< Set if record contains a city3. */
            UInt32 address3         :1; /**< Set if record contains a address3.
                                             */

            UInt32 country2         :1; /**< Set if record contains a country2.
                                             */
            UInt32 zipCode2         :1; /**< Set if record contains a zipCode2.
                                             */
            UInt32 state2           :1; /**< Set if record contains a state2. */
            UInt32 city2            :1; /**< Set if record contains a city2. */
            UInt32 address2         :1; /**< Set if record contains a address2.
                                             */


        } bits2;
        UInt32 allBits2;
    };
} AddrDBRecordFlags;

/***********************************************************************
 *  Application Unpacked Record Format Related Data
 ***********************************************************************/

/** @brief Label types.
 *
 * This describes the label types for those user selectable label
 * fields: phone, instant messenger, and address.
 */
typedef struct
{