addressdb.h

palm os 上的中文伴侣源代码

 * @param index     The index of the flag to clear. i.e.:
 *                      the bit position of the flag to set.
 *
 * @retval          Nothing.
 */
#define RemoveBitMacro(recFlags, index) if(index < firstRecordFlagBits2Field)  \
                                        ((recFlags).allBits) &= ~BitAtPosition \
                                        (index); else                          \
                                        ((recFlags).allBits2) &=               \
                                        ~BitAtPosition(index)

#define SetBitMacroBits(bitField, index) (bitField |= BitAtPosition(index))

#define PictureFieldListStart   addrNumDisplayFields +          \
                                numPhoneLabelsStoredSecond +    \
                                numChatLabels +                 \
                                numAddFieldLabels

#define phoneLabelNone          -1

#define noPhoneField            0x0000

// <chg 20-sep-99 dia> These are phone fields that you might want to make
// a voice phone call to...
#define IsVoiceLabel(f) (((f) != P1ctFaxPhone) && ((f) != P1ctEmailPhone))

#define IsPhoneLookupField(p) (addrLookupWork <= (p) && (p) <= addrLookupMobile)

#define IsSMSLabel(f) (((f) == P1ctMobilePhone) || ((f) ==P1ctEmailPhone) ||   \
                       ((f) == P1ctOtherPhone))

#define IsSMSLabelNoEmail(f) (((f) == P1ctMobilePhone) ||   \
                              ((f) == P1ctOtherPhone))

/******************************************************************************
 * BLOB ID definition
 * Internal blob id will start from 'Bd00'.
 * Creator ids from 'Bd00 - 'Bd09' is registered for this purpose.
 ******************************************************************************/

/** picture blob id */
#define addrPictureBlobId                       'Bd00'

// Need this constant to hack the fix for a Mullet Outlook conduit bug, which is
// already shipped.
#define appInfoBlockSizeMullet  1092

#define kCallerIDMaxPhoneNumberDigits           63

// This is the number of digits in a phone number that are significant...
// Only check the last 8 chars to allow number to be stored in international
// format to still match if bufferLen is greater than key len just use the key
// length
#define kCallerIDSignificantPhoneNumberDigits   8

#define kStrLenRequiredForMatch                 6

// This structure is only for the exchange of address records.
typedef union
{
    struct
    {
        unsigned reserved       :8;

        // Typically only one of these are set

        unsigned email          :1; /**< set if data is an email address */
        unsigned fax            :1; /**< set if data is a fax */
        unsigned pager          :1; /**< set if data is a pager */
        unsigned voice          :1; /**< set if data is a phone */

        unsigned mobile         :1; /**< set if data is a mobile phone */

        // These are set in addition to other flags.

        unsigned work           :1; /**< set if phone is at work */
        unsigned home           :1; /**< set if phone is at home */

        // Set if this number is preferred over others.  May be preferred
        // over all others.  May be preferred over other emails.  One
        // preferred number should be listed next to the person's name.

        unsigned preferred      :1; /**< set if this phone is preferred (bit 0)
                                         */
    } bits;
    UInt32 allBits;
} AddrDBPhoneFlags;

typedef struct
{
    UInt16          currentCategory;
    FontID          v20NoteFont;                // For 2.0 compatibility (BGT)
    Boolean         showAllCategories;
    Boolean         saveBackup;
    Boolean         rememberLastCategory;

    // Version 3 preferences
    FontID          addrListFont;
    FontID          addrRecordFont;
    FontID          addrEditFont;
    UInt8           reserved1;
    UInt32          businessCardRecordID;
    FontID          noteFont;
    UInt8           reserved2;

    // Version 4 preferences
    Boolean         enableTapToConnect;

    // Version 5 preferences for wireless products
    Boolean         showSimCategory;

} AddrPreferenceType;

/******************************************************************************
 * Function Prototypes
 ******************************************************************************/

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Get ptr to the application database info block.
 *
 * @param dbP   Open database ptr.
 * @return      Locked ptr to the AddrAppInfo or NULL.
 */
extern AddrAppInfoPtr AddrDBAppInfoGetPtr (DmOpenRef dbP);

/**
 * Create an app info chunk if missing and initialize with defaults.
 *
 * @param dbP   Open database ptr.
 * @return      0 if successful, error code if not.
 */
extern Err AddrDBAppInfoInit (DmOpenRef dbP);

/**
 * Set the field labels to those appropriate to the current
 * country (based on system preferences).
 *
 * @param appInfoP  Application info block ptr.
 * @return          Nothing.
 */
extern void AddrDBChangeCountry (AddrAppInfoPtr appInfoP);

/**
 * Set a record field's label and mark it dirty.
 *
 * @param dbP           Open database ptr.
 * @param fieldNum      Field label to change.
 * @param fieldLabel    New field label to use.
 * @return              Nothing.
 */
extern void AddrDBSetFieldLabel (DmOpenRef dbP, UInt16 fieldNum,
                                 Char * fieldLabel);

/**
 * Return the scheduled alarm time (in seconds) associated with the given
 * record.
 *
 * @param record         Ptr to the record from which to retrieve the alarm
 *                           time.
 * @param alarmSeconds   Ptr to var to set with the alarm time in seconds
 *                           from 1/1/1904.
 * @param wrapToNextYear True if the alarm time returned should be for next
 *                           year when the alarm time is before the current
 *                           time.
 * @return               True if the alarm is on (set to occur).
 */
extern Boolean AddrDBGetAlarm (AddrDBRecordType* record, UInt32 *alarmSeconds,
                               Boolean wrapToNextYear);

/**
 * Return the birthdate (in seconds) associated with the given record.
 *
 * @param record        Ptr to the record from which to retrieve the
 *                          birthdate.
 * @return              Birthdate in seconds from 1/1/1904.
 */
extern UInt32 AddrDBGetBirthday (AddrDBRecordType* record);

/**
 * Get the application's database, opening or creating it as neccessary.
 *
 * @param addrPP    Ptr to a database ref var (DmOpenRef) to set.
 * @param mode      How to open the database (e.g.: dmModeReadWrite).
 * @return          0 if successful, error code if not.
 */
extern Err AddrDBGetDatabase (DmOpenRef *addrPP, UInt16 mode);

/**
 * Change a record in the database.
 *
 * @param dbP           Open database ptr.
 * @param index         Index of database record to change.
 * @param r             Ptr to a record having the changes to save.
 * @param changedFields The fields to change.
 * @param blobDirty     True if data in the blob has been changed
 * @return              0 if successful, error code if not.
 */
Err AddrDBChangeRecord(DmOpenRef dbP, UInt16 *index, AddrDBRecordPtr r,
                       AddrDBRecordFlags changedFields, UInt16 BlobDirty);

/**
 * Get a record's data from the database and lock the record.
 *
 * @param dbP       Open database ptr.
 * @param index     Index of database record to retrieve.
 * @param recordP   Ptr to a record to initialize with the retrieved data.
 * @param recordH   Record handle to unlock when finished with the record.
 * @return          0 if successful, error code if not.
 */
extern Err AddrDBGetRecord (DmOpenRef dbP, UInt16 index,
                            AddrDBRecordPtr recordP, MemHandle *recordH);

/**
 * Create a new packed record in sorted position in the database.
 *
 * @param dbP   Open database ptr.
 * @param r     Ptr to a record to copy into the DB.
 * @param index Ptr to index var to set with the new record's index.
 * @return      0 if successful, error code if not.
 */
extern Err AddrDBNewRecord (DmOpenRef dbP, AddrDBRecordPtr r, UInt16 *index);

/**
 * Checks if a record is empty or contains data.
 *
 * @param recordP   Ptr to a record to examine.
 * @return          true if the record contains data, false if it is empty.
 */
extern Boolean AddrDBRecordContainsData (AddrDBRecordPtr recordP);

/**
 * Change the sort order of the database.
 *
 * @param dbP               Open database ptr.
 * @param sortByCompany     True if sort order should be by the company field.
 * @return                  Always returns 0.
 */
extern Err AddrDBChangeSortOrder (DmOpenRef dbP, Boolean sortByCompany);

/**
 * Find the record containing the most of the string passed.  Searches all
 * categories. Calls AddrDBLookupString() and AddrDBLookupSeekRecord().
 *
 * @param dbP               Open database ptr.
 * @param key               String for which to search.
 * @param sortByCompany     True if database sort order is by company field.
 * @param field1            Field that the sought record should contain.
 * @param field2            Field that the sought record should contain.
 * @param recordP           Ptr to record index var to set with the index
 *                              of the found record.
 * @param phoneP            Ptr to a var to set with the phone field index
 *                              having
 *                           data in a found record.
 * @param lookupFieldMap    Array mapping look-up fields to record fields, where
 *                              the array index is a look-up field number, and
 *                              the data in that element is the corresponding
 *                              record field number.
 * @param completeMatch     True if a record contains all of the given key.
 * @param uniqueMatch       True if the found record is the only record with the
 *                              key matching to the extent the found record
 *                              does.
 *
 * @return True if a record is found; false if no string is passed or there
 *             aren't any records.
 */
extern Boolean AddrDBLookupLookupString (DmOpenRef dbP, Char *key,
                                         Boolean sortByCompany,
                                         AddressLookupFields field1,
                                         AddressLookupFields field2,
                                         UInt16 *recordP, Int16 *phoneP,
                                         AddressFields lookupFieldMap[],
                                         Boolean * completeMatch,
                                         Boolean *uniqueMatch);

/**
 * Given the index of a record, scan forewards or backwards for a displayable
 * record having the given fields.
 *
 * @param dbP               Open database ptr.
 * @param indexP            Ptr to the index of a record to start from; the
 *                              index of the record found is returned in this
 *                              parameter.
 * @param phoneP            Ptr to a var to set with the phone field index
 *                              having data in a found record.
 * @param offset            Number of records to skip:
 *                              0  - seek from the current record to the next
 *                                   displayable record, if the current record
 *                                   is displayable, its index is returned.
 *                              1  - seek foreward, skipping one displayable
 *                                   record.
 *                             -1  - seek backwards, skipping one displayable
 *                                   record.
 * @param direction         Direction to seek: dmSeekForward or dmSeekBackward.
 * @param field1            Field that the sought record should contain.
 * @param field2            Field that the sought record should contain.
 * @param lookupFieldMap    Array mapping look-up fields to record fields, where
 *                              the array index is a look-up field number, and
 *                              the data in that element is the corresponding
 *                              record field number.
 * @return                  True if a displayable record was found.
 */
extern Boolean AddrDBLookupSeekRecord (DmOpenRef dbP, UInt16 * indexP,
                                       Int16 *phoneP, Int16 offset,
                                       Int16 direction,
                                       AddressLookupFields field1,
                                       AddressLookupFields field2,
                                       AddressFields lookupFieldMap[]);

/**
 * Find the record containing the most of the string passed. Called by
 * AddrDBLookupLookupString().
 *
 * @param dbP                   Open database ptr.
 * @param key                   String for which to search.
 * @param sortByCompany         True if database sort order is by company field.
 * @param category              What category to restrict the search.  Pass
 *                                  dmAllCategories for no restriction to
 *                                  records in a specific category.
 * @param recordP               Ptr to record index var to set with the index
 *                                  of the found record.
 * @param completeMatch         True if a record contains all of the given key.
 * @param oNumMatchingCharsP    Ptr to the var to set with the number of chars
 *                                  matching the given key:
 *                                  0: if no match
 *                                  The length of the key string: if a complete
 *                                                                match.
 *                                  Pass NULL if you don't care.
 * @param masked                True if the masked records preference is
 *                                  enabled.
 *
 * @return                      True if a record is found; false if no string is
 *                                  passed or there aren't any records.
 */
extern Boolean AddrDBLookupString (DmOpenRef dbP, Char *key,
                                   Boolean sortByCompany, UInt16 category,
                                   UInt16 *recordP, Boolean *completeMatch,
                                   UInt16* oNumMatchingCharsP, Boolean masked);

#ifdef __cplusplus
}
#endif

#endif // ADDRESSDB_H