API Guide Home (Online version only) |

# Contacts.h

Go to the documentation of this file.

    00001 /*
    00002  * Contacts.h
    00003  *
    00004  * public header for shared library
    00005  *
    00006  * Copyright (c) 2005 palmOne, Inc. or its subsidiaries.
    00007  * All rights reserved.
    00008  */
    00009  /******************************************************************************
    00010  *
    00011  * Copyright (c) 2005 Palm, Inc. or its subsidiaries.
    00012  * All rights reserved.
    00013  *
    00014  * File: Contacts.h
    00015  *
    00016  * Release: TBD
    00017  *
    00018  * Description:
    00019  *      This header file contains the public routines used to add/update
    00020  *      contacts and manage the data contained in the database for
    00021  *      the built-in Contacts application.
    00022  *
    00023  * History:
    00024  *      December 23, 2004   Created by Scott Silverman
    00025  *
    00026  *          Name        Date            Description
    00027  *          ----        ----            -----------
    00028  *          SDS         5/31/05         Creation.
    00029  *
    00030  *****************************************************************************/
    00031
    00032 #ifndef CONTACTS_H_
    00033 #define CONTACTS_H_
    00034
    00035 /* Palm OS common definitions */
    00036 #include <SystemMgr.h>
    00037
    00038 #define CONTACTS_LIB_TRAP   SYS_TRAP
    00039
    00040 /*********************************************************************
    00041  * Type and creator of Sample Library database
    00042  *********************************************************************/
    00043 #define     ContactsLibCreatorID        'P1CT'
    00044 #define     ContactsLibTypeID           sysFileTLibrary
    00045
    00046 /*********************************************************************
    00047  * Internal library name which can be passed to SysLibFind()
    00048  *********************************************************************/
    00049 #define     ContactsLibName             "ContactsLib-P1CT"
    00050
    00051 /*********************************************************************
    00052  * ContactsLog result codes
    00053  *********************************************************************/
    00054 #define ContactsLibErrorClass                   (appErrorClass | 0x7300)
    00055 #define ContactsLibErrTooManyClients            (ContactsLibErrorClass | 1) // No More client can open the lib
    00056 #define ContactsLibErrInvalidHandle             (ContactsLibErrorClass | 2)
    00057 #define ContactsLibErrInvalidParam              (ContactsLibErrorClass | 3)
    00058 #define ContactsLibErrUIdNotFound               (ContactsLibErrorClass | 4)
    00059 #define ContactsLibErrCategoryNotFound          (ContactsLibErrorClass | 5)
    00060 #define ContactsLibErrLibAlreadyInUse           (ContactsLibErrorClass | 6)
    00061 #define ContactsLibErrVerNotSupported           (ContactsLibErrorClass | 7)
    00062 #define ContactsLibErrOutOfMemory               (ContactsLibErrorClass | 8)
    00063 #define ContactsLibErrSizeParamOverFlow         (ContactsLibErrorClass | 9)
    00064 #define ContactsLibErrEmptyContact              (ContactsLibErrorClass | 10)
    00065 #define ContactsLibErrInvalidReference          (ContactsLibErrorClass | 11)
    00066 #define ContactsLibErrContactNotFound           (ContactsLibErrorClass | 12)
    00067 #define ContactsLibErrAttachAlreadyExist        (ContactsLibErrorClass | 13)    // Attachment cannot be added it already exist in the record.
    00068 #define ContactsLibErrAttachNotExist            (ContactsLibErrorClass | 14)
    00069 #define ContactsLibErrAttachOverFlow            (ContactsLibErrorClass | 15)
    00070 #define ContactsLibErrRecordNotFound            (ContactsLibErrorClass | 16)
    00071 #define ContactsLibErrAttachOverflow            (ContactsLibErrorClass | 17)
    00072 #define ContactsLibErrInvalidField              (ContactsLibErrorClass | 18)
    00073 #define ContactsLibErrTooManySession            (ContactsLibErrorClass | 19)
    00074 #define ContactsLibErrAlreadyInWriteMode        (ContactsLibErrorClass | 20)    // User have requested to create Session in ReadWriteMode but it is already open.
    00075 #define ContactsLibErrInvalidSessionHandle      (ContactsLibErrorClass | 21)
    00076 #define ContactsLibErrFieldNotFound             (ContactsLibErrorClass | 23)
    00077 #define ContactsLibErrStringNotFound            (ContactsLibErrorClass | 24)
    00078 #define ContactsLibErrInvalidAppInfoBlock       (ContactsLibErrorClass | 25)
    00079 #define ContactsLibErrAppInfoIsMising           (ContactsLibErrorClass | 26)
    00080 #define ContactsLibErrReadOnlySession           (ContactsLibErrorClass | 27)
    00081 #define ContactsLibErrUIdExist                  (ContactsLibErrorClass | 28)
    00082 #define ContactsLibErrMaxLimitReached           (ContactsLibErrorClass | 29)
    00083 #define ContactsLibErrListNotExist              (ContactsLibErrorClass | 30)
    00084 #define ContactsLibErrContactNotLocked          (ContactsLibErrorClass | 31)
    00085 #define ContactsLibErrLibStillOpen              (ContactsLibErrorClass | 32)
    00086
    00087
    00088 #define PALM_OS
    00089 #ifdef PALM_OS
    00090     typedef MemHandle                       ContactsContHandle;
    00091     typedef MemHandle                       ContactsSession;
    00092
    00093     #define ContactsNumCategories           dmRecNumCategories
    00094     #define ContactsAllCategories           dmAllCategories
    00095     #define ContactsUnfiledCategory         dmUnfiledCategory
    00096     #define ContactsSeekForward             dmSeekForward
    00097     #define ContactsSeekBackward            dmSeekBackward
    00098
    00099     typedef DateType                        ContactsDateType;
    00100 #endif
    00101
    00102 #define ContactsLabelLength             16
    00103 typedef char                            ContactsLabel[ContactsLabelLength];
    00104
    00105 /* Contact Field Labels */
    00106 typedef enum
    00107 {
    00108     contactsNoType,
    00109     contactsWorkPhone,      // applicable to Phone1-7 fields
    00110     contactsHomePhone,      // applicable to Phone1-7 fields
    00111     contactsFaxPhone,       // applicable to Phone1-7 fields
    00112     contactsOtherPhone,     // applicable to Phone1-7 fields
    00113     contactsEmailPhone,     // applicable to Phone1-7 fields
    00114     contactsMainPhone,      // applicable to Phone1-7 fields
    00115     contactsPagerPhone,     // applicable to Phone1-7 fields
    00116     contactsMobilePhone,    // applicable to Phone1-7 fields
    00117     contactsOtherChat,      // applicable to Chat1 & Chat2 fields
    00118     contactsAimChat,        // applicable to Chat1 & Chat2 fields
    00119     contactsMsnChat,        // applicable to Chat1 & Chat2 fields
    00120     contactsYahooChat,      // applicable to Chat1 & Chat2 fields
    00121     contactsIcqChat,        // applicable to Chat1 & Chat2 fields
    00122     contactsWorkAddress,    // applicable to Address1-3 fields
    00123     contactsHomeAddress,    // applicable to Address1-3 fields
    00124     contactsOtherAddress    // applicable to Address1-3 fields
    00125 }   ContactsLibFieldLabels;
    00126
    00127 /* Contacts record fields */
    00128 typedef enum
    00129 {
    00130     contactsLastName,
    00131     contactsFirstName,
    00132     contactsCompany,
    00133     contactsTitle,
    00134
    00135     contactsPhone1,
    00136     contactsPhone2,
    00137     contactsPhone3,
    00138     contactsPhone4,
    00139     contactsPhone5,
    00140     contactsPhone6,
    00141     contactsPhone7,
    00142
    00143     contactsChat1,
    00144     contactsChat2,
    00145
    00146     contactsWebpage,
    00147
    00148     contactsCustom1,
    00149     contactsCustom2,
    00150     contactsCustom3,
    00151     contactsCustom4,
    00152     contactsCustom5,
    00153     contactsCustom6,
    00154     contactsCustom7,
    00155     contactsCustom8,
    00156     contactsCustom9,
    00157
    00158     contactsAddress1,
    00159     contactsCity1,
    00160     contactsState1,
    00161     contactsZipCode1,
    00162     contactsCountry1,
    00163     contactsAddress2,
    00164     contactsCity2,
    00165     contactsState2,
    00166     contactsZipCode2,
    00167     contactsCountry2,
    00168     contactsAddress3,
    00169     contactsCity3,
    00170     contactsState3,
    00171     contactsZipCode3,
    00172     contactsCountry3,
    00173
    00174     contactsNote,
    00175
    00176     contactsBirthdate,
    00177     contactsBirthdayMask,
    00178     contactsBirthdayPreset,
    00179     contactsPicture,
    00180     contactsUniqueID        = contactsPicture + 2,
    00181     contactsIndex,
    00182     contactsCategoryID,
    00183     contactsPrivate         = contactsCategoryID + 2,
    00184     contactsBusy,
    00185     contactsDirty,
    00186     contactsRingtoneInfo    = contactsDirty + 4,
    00187     contactsAnniversaryDate,
    00188     contactsAnniversaryMask,
    00189     contactsAnniversaryPreset,
    00190     contactsNumFields
    00191 } ContactsLibAllFields;
    00192
    00193 typedef enum
    00194 {
    00195     contactsStrLastName,
    00196     contactsStrFirstName,
    00197     contactsStrCompany,
    00198     contactsStrTitle,
    00199
    00200     contactsStrPhone1,          // phone fields, all can accept a label
    00201     contactsStrPhone2,
    00202     contactsStrPhone3,
    00203     contactsStrPhone4,
    00204     contactsStrPhone5,
    00205     contactsStrPhone6,
    00206     contactsStrPhone7,
    00207
    00208     contactsStrChat1,           // instant message id and service, both can accept a label
    00209     contactsStrChat2,
    00210
    00211     contactsStrWebpage,
    00212
    00213     contactsStrCustom1,         // custom fields
    00214     contactsStrCustom2,
    00215     contactsStrCustom3,
    00216     contactsStrCustom4,
    00217     contactsStrCustom5,
    00218     contactsStrCustom6,
    00219     contactsStrCustom7,
    00220     contactsStrCustom8,
    00221     contactsStrCustom9,
    00222
    00223     contactsStrAddress1,        // first set of address fields, Address1 can accept a label
    00224     contactsStrCity1,
    00225     contactsStrState1,
    00226     contactsStrZipCode1,
    00227     contactsStrCountry1,
    00228     contactsStrAddress2,        // second set of address fields, Address2 can accept a label
    00229     contactsStrCity2,
    00230     contactsStrState2,
    00231     contactsStrZipCode2,
    00232     contactsStrCountry2,
    00233     contactsStrAddress3,        // third set of address fields, Address3 can accept a label
    00234     contactsStrCity3,
    00235     contactsStrState3,
    00236     contactsStrZipCode3,
    00237     contactsStrCountry3,
    00238
    00239     contactsStrNote             // This field is assumed to be < 32K
    00240 } ContactsLibStrFields;
    00241
    00242 typedef enum
    00243 {
    00244     contactsCustomCustom1   = contactsCustom1,
    00245     contactsCustomCustom2,
    00246     contactsCustomCustom3,
    00247     contactsCustomCustom4,
    00248     contactsCustomCustom5,
    00249     contactsCustomCustom6,
    00250     contactsCustomCustom7,
    00251     contactsCustomCustom8,
    00252     contactsCustomCustom9
    00253 } ContactsLibCustomFields;
    00254
    00255 typedef enum
    00256 {
    00257     contactsWithLabelPhone1         = contactsPhone1,
    00258     contactsWithLabelPhone2,
    00259     contactsWithLabelPhone3,
    00260     contactsWithLabelPhone4,
    00261     contactsWithLabelPhone5,
    00262     contactsWithLabelPhone6,
    00263     contactsWithLabelPhone7,
    00264     contactsWithLabelChat1,
    00265     contactsWithLabelChat2,
    00266     contactsWithLabelAddress1       = contactsAddress1,
    00267     contactsWithLabelAddress2       = contactsAddress2,
    00268     contactsWithLabelAddress3       = contactsAddress3
    00269 } ContactsLibWithLabelFields;
    00270
    00271 typedef enum ContactsLabelTypes
    00272 {
    00273     ContactsChatLabel,
    00274     ContactsAddressLabel,
    00275     ContactsPhoneLabel
    00276 } ContactsLabelType;
    00277
    00278 typedef enum
    00279 {
    00280     contactsDateBirthdate               = contactsBirthdate,
    00281     contactsDateAnniversary             = contactsAnniversaryDate
    00282 } ContactsLibDateFields;
    00283
    00284 typedef enum
    00285 {
    00286     contactsUInt16Index                 = contactsIndex,
    00287     contactsUInt16Category              = contactsCategoryID
    00288 } ContactsLibUInt16Fields;
    00289
    00290 typedef enum
    00291 {
    00292     contactsUInt32UniqueID              = contactsUniqueID
    00293 } ContactsLibUInt32Fields;
    00294
    00295 typedef enum
    00296 {
    00297     contactsUInt8Private                = contactsPrivate,
    00298     contactsUInt8Busy,
    00299     contactsUInt8Dirty,
    00300     contactsUInt8BirthdayMask           = contactsBirthdayMask,
    00301     contactsUInt8BirthdayPreset,
    00302     contactsUInt8AnniversaryMask        = contactsAnniversaryMask,
    00303     contactsUInt8AnniversaryPreset
    00304 } ContactsLibUInt8Fields;
    00305
    00306 typedef enum
    00307 {
    00308     contactsBinaryPictureData           = contactsPicture,
    00309     contactsBinaryRingtoneIdentifier    = contactsRingtoneInfo
    00310 } ContactsLibBinaryFields;
    00311
    00312 typedef enum
    00313 {
    00314     ContactsLibSessionModeReadOnly  = 0x0001,
    00315     ContactsLibSessionModeReadWrite = 0x0003
    00316 } SessionMode;
    00317
    00318
    00319 #define ContactsLibTrapGetVersion                   (sysLibTrapCustom)
    00320
    00321 #define ContactsLibTrapOpenSession                  (sysLibTrapCustom + 23)
    00322 #define ContactsLibTrapCloseSession                 (sysLibTrapCustom + 24)
    00323
    00324 #define ContactsLibTrapCreateHandle                 (sysLibTrapCustom + 90)
    00325 #define ContactsLibTrapReleaseHandle                (sysLibTrapCustom + 4)
    00326
    00327 #define ContactsLibTrapAddContact                   (sysLibTrapCustom + 8)
    00328 #define ContactsLibTrapUpdateContact                (sysLibTrapCustom + 7)
    00329 #define ContactsLibTrapDeleteContact                (sysLibTrapCustom + 9)
    00330
    00331 #define ContactsLibTrapGetContact                   (sysLibTrapCustom + 12)
    00332 #define ContactsLibTrapGetNumOfRecord               (sysLibTrapCustom + 28)
    00333 #define ContactsLibTrapSeekRecord                   (sysLibTrapCustom + 35)
    00334 #define ContactsLibTrapGetFirstContact              (sysLibTrapCustom + 10)
    00335 #define ContactsLibTrapGetNextContact               (sysLibTrapCustom + 11)
    00336
    00337
    00338 #define ContactsLibTrapDoesFieldExist               (sysLibTrapCustom + 36)
    00339 #define ContactsLibTrapIsEmptyContact               (sysLibTrapCustom + 30)
    00340
    00341 #define ContactsLibTrapSetUInt8Field                (sysLibTrapCustom + 51)
    00342 #define ContactsLibTrapSetUInt16Field               (sysLibTrapCustom + 53)
    00343 #define ContactsLibTrapSetDateField                 (sysLibTrapCustom + 55)
    00344 #define ContactsLibTrapSetStringField               (sysLibTrapCustom + 57)
    00345 #define ContactsLibTrapSetBinaryField               (sysLibTrapCustom + 59)
    00346
    00347
    00348 #define ContactsLibTrapGetUInt8Field                (sysLibTrapCustom + 50)
    00349 #define ContactsLibTrapGetUInt16Field               (sysLibTrapCustom + 52)
    00350 #define ContactsLibTrapGetUInt32Field               (sysLibTrapCustom + 63)
    00351 #define ContactsLibTrapGetDateField                 (sysLibTrapCustom + 54)
    00352 #define ContactsLibTrapGetStringField               (sysLibTrapCustom + 56)
    00353 #define ContactsLibTrapGetBinaryField               (sysLibTrapCustom + 58)
    00354
    00355 #define ContactsLibTrapGetFieldLabel                (sysLibTrapCustom + 31)
    00356 #define ContactsLibTrapSetFieldLabel                (sysLibTrapCustom + 32)
    00357 #define ContactsLibTrapGetLabelText                 (sysLibTrapCustom + 82)
    00358
    00359 #define ContactsLibTrapRenameCustomLabel            (sysLibTrapCustom + 33)
    00360
    00361 #define ContactsLibTrapGetCategoryList              (sysLibTrapCustom + 2)
    00362 #define ContactsLibTrapGetNextCategory              (sysLibTrapCustom + 37)
    00363 #define ContactsLibTrapGetCategoryName              (sysLibTrapCustom + 27)
    00364 #define ContactsLibTrapSetCategoryName              (sysLibTrapCustom + 38)
    00365 #define ContactsLibTrapCategoryFind                 (sysLibTrapCustom + 39)
    00366 #define ContactsLibTrapPosInCategory                (sysLibTrapCustom + 48)
    00367
    00368 #define ContactsLibTrapGetRingtoneForCategory       (sysLibTrapCustom + 91)
    00369
    00370 #define ContactsLibTrapLookUpString                 (sysLibTrapCustom + 40)
    00371
    00372 #define ContactsLibGetLastErr                       (sysLibTrapCustom + 64)
    00373
    00374 /*
    00375  * FUNCTION: ContactsLib_OpenLibrary
    00376  *
    00377  * DESCRIPTION:
    00378  *
    00379  * User-level call to open the library.  This inline function
    00380  * handles the messy task of finding or loading the library
    00381  * and calling its open function, including handling cleanup
    00382  * if the library could not be opened.
    00383  *
    00384  * PARAMETERS:
    00385  *
    00386  * refNumP
    00387  *      Pointer to UInt16 variable that will hold the new
    00388  *      library reference number for use in later calls
    00389  *
    00390  * CALLED BY: System
    00391  *
    00392  * RETURNS:
    00393  *      errNone
    00394  *      memErrNotEnoughSpace
    00395  *      sysErrLibNotFound
    00396  *      sysErrNoFreeRAM
    00397  *      sysErrNoFreeLibSlots
    00398  *
    00399  */
    00400 __inline Err ContactsLib_OpenLibrary(UInt16 *refNumP)
    00401 {
    00402     Err error;
    00403     Boolean loaded = false;
    00404
    00405     /* first try to find the library */
    00406     error = SysLibFind(ContactsLibName, refNumP);
    00407
    00408     /* If not found, load the library instead */
    00409     if (error == sysErrLibNotFound)
    00410     {
    00411         error = SysLibLoad(ContactsLibTypeID, ContactsLibCreatorID, refNumP);
    00412         loaded = true;
    00413     }
    00414
    00415     if (error == errNone)
    00416     {
    00417         error = ContactsLibOpen(*refNumP);
    00418         if (error != errNone)
    00419         {
    00420             if (loaded)
    00421             {
    00422                 SysLibRemove(*refNumP);
    00423             }
    00424
    00425             *refNumP = sysInvalidRefNum;
    00426         }
    00427     }
    00428
    00429     return error;
    00430 }
    00431
    00432 /*
    00433  * FUNCTION: ContactsLib_CloseLibrary
    00434  *
    00435  * DESCRIPTION:
    00436  *
    00437  * User-level call to closes the shared library.  This handles removal
    00438  * of the library from system if there are no users remaining.
    00439  *
    00440  * PARAMETERS:
    00441  *
    00442  * refNum
    00443  *      Pointer Library reference number obtained from ContactsLib_OpenLibrary().
    00444  *      Upon successful close, contents will be invalidated.
    00445  *
    00446  * CALLED BY: Whoever wants to close the library
    00447  *
    00448  * RETURNS:
    00449  *      errNone
    00450  *      sysErrParamErr
    00451  */
    00452 __inline Err ContactsLib_CloseLibrary(UInt16 *refNumP)
    00453 {
    00454     Err error;
    00455
    00456     if (*refNumP == sysInvalidRefNum)
    00457     {
    00458         return sysErrParamErr;
    00459     }
    00460
    00461     error = ContactsLibClose(*refNumP);
    00462
    00463     if (error == errNone)
    00464     {
    00465         /* no users left, so unload library */
    00466         SysLibRemove(*refNumP);
    00467
    00468         *refNumP = sysInvalidRefNum;    // invalidate so caller cannot use any longer.
    00469     }
    00470     else if (error == ContactsLibErrLibStillOpen)
    00471     {
    00472         /* don't unload library, but mask "still open" from caller  */
    00473         error = errNone;
    00474     }
    00475
    00476     return error;
    00477 }
    00478
    00479
    00480 #endif /* CONTACTSLIB_H_ */
    00481
    00482
    00483 /*********************************************************************
    00484  * API Prototypes
    00485  *********************************************************************/
    00486
    00487 #ifdef __cplusplus
    00488 extern "C" {
    00489 #endif
    00490
    00491
    00492 /*
    00493  * FUNCTION: ContactsLibGetVersion
    00494  *
    00495  * DESCRIPTION:
    00496  *
    00497  * Returns the version number of the Contacts Library
    00498  *
    00499  * PARAMETERS:
    00500  *
    00501  * libRefnum
    00502  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00503  *
    00504  * RETURNS:
    00505  *      Version number in the form where only the two low bytes are used.
    00506  *      Of those two bytes, the high byte is the major version and
    00507  *      the low byte is the minor version
    00508  *      (i.e. the value 0x00000201 represents version 2.01).
    00509  */
    00510 extern  UInt32      ContactsGetVersion(UInt16 libRefnum)    CONTACTS_LIB_TRAP(ContactsLibTrapGetVersion);
    00511
    00512 /*
    00513  * FUNCTION: ContactsOpenSession
    00514  *
    00515  * DESCRIPTION:
    00516  *
    00517  * Returns the session handle to be passed to other Contacts Lib routines
    00518  * One can either specify a new session to be read only or read/write.
    00519  *
    00520  * PARAMETERS:
    00521  *
    00522  * libRefnum
    00523  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00524  *
    00525  * mode
    00526  *      This is the mode in which you want to open a session.  Must be one of the
    00527  *      valid SessionMode types.
    00528  *
    00529  * RETURNS:
    00530  *      a ContactsSession
    00531  *      NULL (unsuccessful)
    00532  *
    00533  * USAGE:
    00534  *      Typical usage is to always first open a session and retain the session handle returned.
    00535  *      Then subsequent routines to add a new contact for instance will use the internal data
    00536  *      stored in the session handle to access the underlying contacts database.
    00537  * NOTES:
    00538  *      It is important to always close the session with a call to CloseSession
    00539  *      after you are finished with the session.  Doing so will free system memory used internally
    00540  *      by the library and also free a spot for other users to open sessions.
    00541  *      With this version of the library, there is a limit of 4 open sessions.
    00542  */
    00543 extern  ContactsSession     ContactsOpenSession(UInt16 libRefnum, SessionMode mode) CONTACTS_LIB_TRAP(ContactsLibTrapOpenSession);
    00544
    00545 /*
    00546  * FUNCTION: ContactsCloseSession
    00547  *
    00548  * DESCRIPTION:
    00549  *
    00550  * Nullifies the open session handle and frees any internal memory used by the library for this session.
    00551  *
    00552  * PARAMETERS:
    00553  *
    00554  * libRefnum
    00555  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00556  *
    00557  * hSession
    00558  *      This is any valid session handle that was obtain from a call to OpenSession.
    00559  *
    00560  * RETURNS:
    00561  *      errNone
    00562  *      ContactsLibErrInvalidSessionHandle
    00563  *
    00564  * USAGE:
    00565  *      This must be called after a session is no longer needed.  It will prevent memory leaks
    00566  *      of any memory allocated by the OpenSession call.  It also will make available the
    00567  *      session for another caller.
    00568  * NOTES:
    00569  *      It is important to always close the session with a call to ContactsCloseSession
    00570  *      after you are finished with the session.  Doing so will free system memory used internally
    00571  *      by the library and also free a spot for other users to open sessions.
    00572  *      With this version of the library, there is a limit to a total of 4 open sessions.
    00573  */
    00574 extern  Err     ContactsCloseSession(UInt16 libRefnum, ContactsSession hCurSession) CONTACTS_LIB_TRAP(ContactsLibTrapCloseSession);
    00575
    00576 /*
    00577  * FUNCTION: ContactsCreateHandle
    00578  *
    00579  * DESCRIPTION:
    00580  *
    00581  * Returns a brand new ContactsContHandle..
    00582  *
    00583  * PARAMETERS:
    00584  *
    00585  * libRefnum
    00586  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00587  *
    00588  * hSession
    00589  *      This is any valid read/write session handle that was obtain from a call to OpenSession.
    00590  *
    00591  * RETURNS:
    00592  *      a valid ContHandle
    00593  *      NULL (only possible way this could fail is if out of memory)
    00594  *
    00595  * USAGE:
    00596  *      This is called to create a new handle which is then used to set a series of fields.
    00597  *      One would create the handle, do a series of 'sets' and then add the new handle by calling
    00598  *      AddContact.
    00599  * NOTES:
    00600  *      It is critical that after the handle is finished being used, a call to
    00601  *      ReleaseHandle is called.
    00602  */
    00603 extern  ContactsContHandle      ContactsCreateHandle(UInt16 libRefnum, ContactsSession hSession)    CONTACTS_LIB_TRAP(ContactsLibTrapCreateHandle);
    00604
    00605 /*
    00606  * FUNCTION: ContactsReleaseHandle
    00607  *
    00608  * DESCRIPTION:
    00609  *
    00610  * Used to release the memory used by ANY valid ContactsContHandle.
    00611  *
    00612  * PARAMETERS:
    00613  *
    00614  * libRefnum
    00615  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00616  *
    00617  * RETURNS:
    00618  *      errNone
    00619  *      P1ctErrInvalidHandle
    00620  *
    00621  * USAGE:
    00622  *      Once a handle has been obtained, either from a call to CreateHandle or GetContact,
    00623  *      It is critical that the ReleaseHandle routine is called.
    00624  */
    00625 extern  Err     ContactsReleaseHandle(UInt16 libRefnum, ContactsContHandle hContact)    CONTACTS_LIB_TRAP(ContactsLibTrapReleaseHandle);
    00626
    00627 /*
    00628  * FUNCTION: ContactsAddContact
    00629  *
    00630  * DESCRIPTION:
    00631  *
    00632  * Used to add the contact described by a ContHandle to the database.
    00633  *
    00634  * PARAMETERS:
    00635  *
    00636  * libRefnum
    00637  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00638  *
    00639  * hSession
    00640  *      This is any valid read/write session handle that was obtain from a call to OpenSession.
    00641  *
    00642  * hContact
    00643  *      The contact handle returned by CreateContact.
    00644  *
    00645  * RETURNS:
    00646  *      errNone
    00647  *      ContactsLibErrInvalidSessionHandle
    00648  *      P1ctErrReadOnlySession
    00649  *
    00650  * USAGE:
    00651  *      Once a handle has been obtained from CreateHandle,
    00652  *      the user will follow with a series of calls to "Set" routines that will set the fields values.
    00653  *      Once all of the calls to the "set" routines have been made, it is necessary to call
    00654  *      the AddContact routine to write the data to the database.
    00655  *      The final step is to call ReleaseHandle on the ContHandle.
    00656  */
    00657 extern  Err     ContactsAddContact(UInt16 libRefnum, ContactsSession hSession, ContactsContHandle hContact) CONTACTS_LIB_TRAP(ContactsLibTrapAddContact);
    00658
    00659 /*
    00660  * FUNCTION: ContactsUpdateContact
    00661  *
    00662  * DESCRIPTION:
    00663  *
    00664  * Writes the entry to the database.
    00665  *
    00666  * PARAMETERS:
    00667  *
    00668  * libRefnum
    00669  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00670  *
    00671  * hSession
    00672  *      This is any valid read/write session handle that was obtain from a call to ContactsOpenSession.
    00673  *
    00674  * hContact
    00675  *      This is any valid ContHandle that was returned by one of the routines that returns a ContHandle.
    00676  *
    00677  * RETURNS:
    00678  *      errNone
    00679  *      P1ctErrInvalidHandle
    00680  *
    00681  * USAGE:
    00682  *      Once a ContHandle has been obtained, the user can modify the entry by doing one or more "Set" calls.
    00683  *      Once all of the set routines have been made, a call to UpdateContact must be made to save the changes.
    00684  *
    00685  * NOTES:
    00686  *      There are several routines that will return a valid ContHandle (ie GetContact, GetFirstContact, GetNextContact).
    00687  *      Although a call to UpdateContact is not required, if any changes have been made by calling any of the set
    00688  *      routines, UpdateContact must be called to save those changes to the database.
    00689  *      Remember, it IS required to call ReleaseHandle for any ContHandle obtained.
    00690  */
    00691 extern  Err     ContactsUpdateContact(UInt16 libRefnum, ContactsSession hSession, ContactsContHandle hContact)  CONTACTS_LIB_TRAP(ContactsLibTrapUpdateContact);
    00692
    00693 /*
    00694  * FUNCTION: ContactsDeleteContact
    00695  *
    00696  * DESCRIPTION:
    00697  *
    00698  * Immeditely deletes the contact from the Contacts database.
    00699  *
    00700  * PARAMETERS:
    00701  *
    00702  * libRefnum
    00703  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00704  *
    00705  * hSession
    00706  *      This is any valid read/write session handle that was obtain from a call to OpenSession.
    00707  *
    00708  * hContact
    00709  *      This is the valid ContHandle that was returned by one of the routines that returns a ContHandle.
    00710  *
    00711  * archive
    00712  *      Pass true if you want the entry to be archived on PC.
    00713  *
    00714  * RETURNS:
    00715  *      errNone
    00716  *      P1ctErrReadOnlySession
    00717  *
    00718  * USAGE:
    00719  *      Once a ContHandle has been obtained from any of the routines that return a ContHandle (except CreateHandle),
    00720  *      calling this routine will delete this entry.
    00721  *
    00722  * NOTES:
    00723  *      Remember, it STILL is required to call ReleaseHandle for the ContHandle after calling DeleteContact.
    00724  */
    00725 extern  Err     ContactsDeleteContact(UInt16 libRefnum, ContactsSession hSession, ContactsContHandle hContact, Boolean archive) CONTACTS_LIB_TRAP(ContactsLibTrapDeleteContact);
    00726
    00727 /*
    00728  * FUNCTION: ContactsGetContact
    00729  *
    00730  * DESCRIPTION:
    00731  *
    00732  * Gets a ContHandle by either index (0 based) or by uniqueID.
    00733  *
    00734  * PARAMETERS:
    00735  *
    00736  * libRefnum
    00737  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00738  *
    00739  * hSession
    00740  *      This is any valid session handle that was obtain from a call to OpenSession.
    00741  *
    00742  * indexP
    00743  *      pass either a UInt16* containing a 0 based index or NULL.
    00744  *
    00745  * uniqueIDP
    00746  *      Pass either a UInt32* containing a valid uniqueID or NULL.
    00747  *
    00748  * RETURNS:
    00749  *      a valid ContHandle
    00750  *      NULL
    00751  *
    00752  * USAGE:
    00753  *      The routine first checks to see if uniqueIDP is not NULL, if not, a search of the database will be commenced
    00754  *      using the uniqueID stored in that pointer.
    00755  *      IF uniqueIDP is NULL, it will expect a non-NULL indexP which its contents will be used to get the
    00756  *      ContHandle at that index location.
    00757  *
    00758  * NOTES:
    00759  *      Remember to call ReleaseHandle for the ContHandle after finish using it.
    00760  *      IF NULL is returned, the error causing the failure can be obtained call GetLastErr.
    00761  */
    00762 extern  ContactsContHandle      ContactsGetContact(UInt16 libRefnum, ContactsSession hSession, UInt16* indexP, UInt32 *uniqueIDP, Boolean ignored) CONTACTS_LIB_TRAP(ContactsLibTrapGetContact);
    00763
    00764 /*
    00765  * FUNCTION: ContactsGetNumRecords
    00766  *
    00767  * DESCRIPTION:
    00768  *
    00769  * returns the number of records in any given category.
    00770  *
    00771  * PARAMETERS:
    00772  *
    00773  * libRefnum
    00774  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00775  *
    00776  * hSession
    00777  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    00778  *
    00779  * category
    00780  *      either the category index of the category you wish use OR ContactsAllCategories to specify all categories.
    00781  *      To specify "Unfiled," use ContactsUnfiledCategory for the category.
    00782  *
    00783  * RETURNS:
    00784  *      the number of contacts in the specified category.
    00785  *
    00786  * NOTE:
    00787  *      To get the category for an existing record call ContactsGetUInt16Field for that record.
    00788  */
    00789 extern  UInt16      ContactsGetNumRecords(UInt16 libRefnum, ContactsSession hSession, UInt16 category)  CONTACTS_LIB_TRAP(ContactsLibTrapGetNumOfRecord);
    00790
    00791 /* FUNCTION: ContactsPosInCategory
    00792  *
    00793  * DESCRIPTION:
    00794  *
    00795  * Returns the position of a given record in a given category.
    00796  *
    00797  * PARAMETERS:
    00798  *
    00799  * libRefnum
    00800  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00801  *
    00802  * hSession
    00803  *      This any valid session handle that was obtain from a call to OpenSession.
    00804  *
    00805  * hContact
    00806  *      ContHandle of a given contact record.
    00807  *
    00808  * pIndex
    00809  *      on return, contains the index of the record.
    00810  *
    00811  * category
    00812  *      category in which the entry is contained.
    00813  *
    00814  * RETURNS:
    00815  *      position of the record within a given category (0 based).
    00816  *
    00817  * NOTE:
    00818  *      this routine is useful when only a given category is being displayed and for scrolling purposes,
    00819  *      one needs to determine a record's position in that category.
    00820  *      It is important that GetLastError is called and that noError is returned.
    00821  *      This function can return 0 in a valid case but also will return 0 in an error case so
    00822  *      GetLastError should be checked for noError.
    00823  */
    00824 extern  UInt16      ContactsPosInCategory(UInt16 libRefnum, ContactsSession hSession, ContactsContHandle hContact, UInt16 *pIndex, UInt16 category) CONTACTS_LIB_TRAP(ContactsLibTrapPosInCategory);
    00825
    00826 /*
    00827  * FUNCTION: ContactsSeekRecord
    00828  *
    00829  * DESCRIPTION:
    00830  *
    00831  * Returns a ContHandle specified by the seek criteria passed.
    00832  *
    00833  * PARAMETERS:
    00834  *
    00835  * libRefnum
    00836  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00837  *
    00838  * hSession
    00839  *      This is any valid session handle that was obtain from a call to ContactsOpenSession.
    00840  *
    00841  * indexP
    00842  *      This is a pointer that contains the initial index in which to seek from.
    00843  *
    00844  * offset
    00845  *      The number of entries to seek to past the intial position.
    00846  *
    00847  * direction
    00848  *      Specifies to either seek forward or backward from the initial index ( ContactsSeekForward or ContactsSeekBackward)
    00849  *
    00850  * category
    00851  *      Specifies the category in which to seek in.
    00852  *
    00853  * RETURNS:
    00854  *      true    - a valid index has been found.
    00855  *      false   - no index matching the seek criteria has been found.
    00856  *
    00857  *      indexP  - contains the valid index if the routine returned true.
    00858  */
    00859 extern  Boolean     ContactsSeekRecord(UInt16 libRefnum, ContactsSession hSession, UInt16 *indexP, UInt16 offset, Int16 direction, UInt16 category) CONTACTS_LIB_TRAP(ContactsLibTrapSeekRecord);
    00860
    00861 /* FUNCTION: ContactsGetFirstContact
    00862  *
    00863  * DESCRIPTION:
    00864  *
    00865  * Gets the very first ContHandle in a given category
    00866  *
    00867  * PARAMETERS:
    00868  *
    00869  * libRefnum
    00870  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00871  *
    00872  * hSession
    00873  *      This any valid session handle that was obtain from a call to OpenSession.
    00874  *
    00875  * category
    00876  *      either specify a category or pass ContactsAllCategories to indicate the very first contact in all the categories.
    00877  *
    00878  * RETURNS:
    00879  *      a valid ContHandle
    00880  *      NULL
    00881  *
    00882  * NOTES:
    00883  *      Remember to call ReleaseHandle for the ContHandle after finish using it.
    00884  *      If a NULL is returned, the exact error causing the failure can be obtained from GetLastErr.
    00885  */
    00886 extern  ContactsContHandle      ContactsGetFirstContact(UInt16 libRefnum, ContactsSession hSession, UInt16 category)    CONTACTS_LIB_TRAP(ContactsLibTrapGetFirstContact);
    00887
    00888 /* FUNCTION: ContactsGetNextContact
    00889  *
    00890  * DESCRIPTION:
    00891  *
    00892  * Gets the next ContHandle after a specified handle in a category
    00893  *
    00894  * PARAMETERS:
    00895  *
    00896  * libRefnum
    00897  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00898  *
    00899  * Category
    00900  *      This is the category in which you wish to search.
    00901  *
    00902  * hSourceContact
    00903  *      This is the contact to be used as the reference for the search.
    00904  *
    00905  * RETURNS:
    00906  *      a valid ContHandle
    00907  *      NULL
    00908  *
    00909  * NOTES:
    00910  *      The specified hSourceContact does not have to be part of the specified category for the routine
    00911  *      to succeed but it is logical that it would be.
    00912  *      If a ContHandle is returned, remember to call ReleaseHandle for afer done using it.
    00913  */
    00914 extern  ContactsContHandle      ContactsGetNextContact(UInt16 libRefnum, ContactsSession hSession, ContactsContHandle hSourceContact, UInt16 Category)  CONTACTS_LIB_TRAP(ContactsLibTrapGetNextContact);
    00915
    00916 /*
    00917  * FUNCTION: ContactsDoesFieldExist
    00918  *
    00919  * DESCRIPTION:
    00920  *
    00921  * Returns true if the field has been populated in the sepcified record.
    00922  *
    00923  * PARAMETERS:
    00924  *
    00925  * libRefnum
    00926  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00927  *
    00928  * hContact
    00929  *      This is the valid ContHandle that was returned by one of the routines that returns a ContHandle.
    00930  *
    00931  * NameOfField
    00932  *      any valid fieldName (any one of the ContactsLibAllFields fields).
    00933  *
    00934  * RETURNS:
    00935  *      true - if the field contains data.
    00936  *      false - if the specified field is empty in the specified record.
    00937  *
    00938  * USAGE:
    00939  *      This routine is most handy for the picture field to see if a picture exists prior to getting
    00940  *      the data.  However, this routine can be used for any of the fields.
    00941  */
    00942 extern  Boolean     ContactsDoesFieldExist(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibAllFields NameOfField) CONTACTS_LIB_TRAP(ContactsLibTrapDoesFieldExist);
    00943
    00944 /* FUNCTION: ContactsIsEmptyContact
    00945  *
    00946  * DESCRIPTION:
    00947  *
    00948  * Will return true if ALL of the fields of a given record are empty.
    00949  *
    00950  * PARAMETERS:
    00951  *
    00952  * libRefnum
    00953  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00954  *
    00955  * hSession
    00956  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    00957  *
    00958  * hContact
    00959  *      The contact you which to know is empty or not.
    00960  *
    00961  * RETURNS:
    00962  *      true    - record is completely empty.
    00963  *      false   - there is at least one field that contains data in the specified record.
    00964  */
    00965 extern  Boolean     ContactsIsEmptyContact (UInt16 libRefnum,  ContactsSession hSession, ContactsContHandle hCont, UInt16 *Index, UInt32 *UniqueID) CONTACTS_LIB_TRAP(ContactsLibTrapIsEmptyContact);
    00966
    00967
    00968 /* FUNCTION: ContactsSetUInt8Field
    00969  *
    00970  * DESCRIPTION:
    00971  *
    00972  * Set the value of the specified UInt8 field.
    00973  *
    00974  * PARAMETERS:
    00975  *
    00976  * libRefnum
    00977  *      Library reference number obtained from ContactsLib_OpenLibrary().
    00978  *
    00979  * hContact
    00980  *      This any valid read/write session handle that was obtain from a call to OpenSession.
    00981  *
    00982  * nameOfField
    00983  *      This is the field of size UInt8 in which you want to set (ContactsLibUInt8Fields).
    00984  *
    00985  * fieldValue
    00986  *      value you wish to assign to that field.
    00987  *
    00988  * RETURNS:
    00989  *      noErr.
    00990  *      P1ctErrInvalidParam
    00991  *      ContactsLibErrInvalidHandle.
    00992  */
    00993 extern  Err     ContactsSetUInt8Field(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibUInt8Fields nameOfField, UInt8 fieldValue)  CONTACTS_LIB_TRAP(ContactsLibTrapSetUInt8Field);
    00994
    00995 /* FUNCTION: ContactsSetUInt16Field
    00996  *
    00997  * DESCRIPTION:
    00998  *
    00999  * Set the value of the specified UInt16 field.
    01000  *
    01001  * PARAMETERS:
    01002  *
    01003  * libRefnum
    01004  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01005  *
    01006  * hContact
    01007  *      This any valid session handle that was obtain from a call to OpenSession.
    01008  *
    01009  * NameOfField
    01010  *      This is the field of size UInt16 in which you want to set (ContactsLibUInt16Fields).
    01011  *
    01012  * FieldValue
    01013  *      value you wish to set field with.
    01014  *
    01015  * RETURNS:
    01016  *      noErr.
    01017  *      P1ctErrInvalidParam
    01018  *      ContactsLibErrInvalidHandle.
    01019  */
    01020 extern  Err     ContactsSetUInt16Field(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibUInt16Fields NameOfField, UInt16 FieldValue)   CONTACTS_LIB_TRAP(ContactsLibTrapSetUInt16Field);
    01021
    01022 /* FUNCTION: ContactsSetDateField
    01023  *
    01024  * DESCRIPTION:
    01025  *
    01026  * Set the value of the specified Date field.
    01027  *
    01028  * PARAMETERS:
    01029  *
    01030  * libRefnum
    01031  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01032  *
    01033  * hContact
    01034  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    01035  *
    01036  * nameOfField
    01037  *      This is the field of type ContactsDateType in which you want to set (ContactsLibDateFields).
    01038  *
    01039  * fieldValue
    01040  *      value you wish to set field with.
    01041  *
    01042  * RETURNS:
    01043  *      noErr.
    01044  *      P1ctErrInvalidParam
    01045  *      ContactsLibErrInvalidHandle.
    01046  */
    01047 extern  Err     ContactsSetDateField(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibDateFields nameOfField, ContactsDateType fieldValue) CONTACTS_LIB_TRAP(ContactsLibTrapSetDateField);
    01048
    01049 /* FUNCTION: ContactsSetStringField
    01050  *
    01051  * DESCRIPTION:
    01052  *
    01053  * Set the value of the specified String field.
    01054  *
    01055  * PARAMETERS:
    01056  *
    01057  * libRefnum
    01058  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01059  *
    01060  * hContact
    01061  *      This any valid read/write session handle that was obtain from a call to OpenSession.
    01062  *
    01063  * nameOfField
    01064  *      This is the field of type Char * in which you want to set (ContactsLibStrFields).
    01065  *
    01066  * FieldValue
    01067  *      value you wish to set field with.
    01068  *
    01069  * RETURNS:
    01070  *      noErr.
    01071  *      ContactsLibErrInvalidHandle.
    01072  */
    01073 extern  Err     ContactsSetStringField(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibStrFields nameOfField, char *FieldValue)   CONTACTS_LIB_TRAP(ContactsLibTrapSetStringField);
    01074
    01075 /* FUNCTION: ContactsSetBinaryField
    01076  *
    01077  * DESCRIPTION:
    01078  *
    01079  * Set the value of the specified Binary field.
    01080  *
    01081  * PARAMETERS:
    01082  *
    01083  * libRefnum
    01084  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01085  *
    01086  * hContact
    01087  *      This any valid session handle that was obtain from a call to OpenSession.
    01088  *
    01089  * NameOfField
    01090  *      This is the field of type Binary in which you want to set (ContactsLibBinaryFields).
    01091  *
    01092  * FieldValue
    01093  *      value you wish to set field with.
    01094  *
    01095  * DataSize
    01096  *      Length in bytes of the data you wish to set.
    01097  *
    01098  * RETURNS:
    01099  *      noErr.
    01100  *      ContactsLibErrInvalidHandle.
    01101  */
    01102 extern  Err     ContactsSetBinaryField(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibBinaryFields NameOfField, void *pFieldData, UInt16 DataSize)   CONTACTS_LIB_TRAP(ContactsLibTrapSetBinaryField);
    01103
    01104 /* FUNCTION: ContactsGetUInt8Field
    01105  *
    01106  * DESCRIPTION:
    01107  *
    01108  * Fetches the UInt8 value of the specified field from the specified record.
    01109  *
    01110  * PARAMETERS:
    01111  *
    01112  * libRefnum
    01113  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01114  * hContact
    01115  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    01116  * NameOfField
    01117  *      This is the field of type UInt8 in which you want to set (ContactsLibUInt8Fields).
    01118  * pFieldValue
    01119  *      pointer to the UInt8 in which the fetched value will be placed.
    01120  * RETURNS:
    01121  *      noErr.
    01122  *      ContactsLibErrInvalidHandle.
    01123  */
    01124 extern  Err                     ContactsGetUInt8Field(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibUInt8Fields NameOfField, UInt8 *pFieldValue)    CONTACTS_LIB_TRAP(ContactsLibTrapGetUInt8Field);
    01125
    01126 /* FUNCTION: ContactsGetUInt16Field
    01127  *
    01128  * DESCRIPTION:
    01129  *
    01130  * Fetches the UInt16 value of the specified field from the specified record.
    01131  *
    01132  * PARAMETERS:
    01133  *
    01134  * libRefnum
    01135  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01136  * hContact
    01137  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    01138  * NameOfField
    01139  *      This is the field of type UInt16 in which you want to set (ContactsLibUInt16Fields).
    01140  * pFieldValue
    01141  *      pointer to the UInt16 in which the fetched value will be placed.
    01142  * RETURNS:
    01143  *      noErr.
    01144  *      ContactsLibErrInvalidHandle.
    01145  */
    01146 extern  Err                     ContactsGetUInt16Field(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibUInt16Fields NameOfField, UInt16 *pFieldValue) CONTACTS_LIB_TRAP(ContactsLibTrapGetUInt16Field);
    01147
    01148 /* FUNCTION: ContactsGetUInt32Field
    01149  *
    01150  * DESCRIPTION:
    01151  *
    01152  * Fetches the UInt32 value of the specified field from the specified record.
    01153  *
    01154  * PARAMETERS:
    01155  *
    01156  * libRefnum
    01157  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01158  * hContact
    01159  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    01160  * NameOfField
    01161  *      This is the field of type UInt32 in which you want to set (ContactsLibUInt32Fields).
    01162  * pFieldValue
    01163  *      pointer to the UInt32 in which the fetched value will be placed.
    01164  * RETURNS:
    01165  *      noErr.
    01166  *      ContactsLibErrInvalidHandle.
    01167  */
    01168 extern  Err                     ContactsGetUInt32Field(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibUInt32Fields NameOfField, UInt32 *pFieldValue) CONTACTS_LIB_TRAP(ContactsLibTrapGetUInt32Field);
    01169
    01170 /* FUNCTION: ContactsGetDateField
    01171  *
    01172  * DESCRIPTION:
    01173  *
    01174  * Fetches the Date value of the specified field from the specified record.
    01175  *
    01176  * PARAMETERS:
    01177  *
    01178  * libRefnum
    01179  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01180  * hContact
    01181  *      This any valid ContHandle that was obtain from a call to ContactsOpenSession.
    01182  * NameOfField
    01183  *      This is the field of type DateType in which you want to set (ContactsLibDateFields).
    01184  * pFieldValue
    01185  *      pointer to the Date in which the fetched value will be placed.
    01186  * RETURNS:
    01187  *      noErr.
    01188  *      ContactsLibErrInvalidHandle.
    01189  */
    01190 extern  Err                     ContactsGetDateField(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibDateFields NameOfField, DateType *pFieldValue)   CONTACTS_LIB_TRAP(ContactsLibTrapGetDateField);
    01191
    01192 /* FUNCTION: ContactsGetStringField
    01193  *
    01194  * DESCRIPTION:
    01195  *
    01196  * Fetches the String value of the specified field from the specified record.
    01197  *
    01198  * PARAMETERS:
    01199  *
    01200  * libRefnum
    01201  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01202  * hContact
    01203  *      This any valid ContHandle that was obtain from a call to ContactsOpenSession.
    01204  * NameOfField
    01205  *      This is the field of type String in which you want to set (ContactsLibStrFields).
    01206  * pFieldValue
    01207  *      pointer to the String in which the fetched value will be placed.
    01208  * RETURNS:
    01209  *      noErr.
    01210  *      ContactsLibErrInvalidHandle.
    01211  */
    01212 extern  Err                     ContactsGetStringField(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibStrFields NameOfField, char **pFieldValue) CONTACTS_LIB_TRAP(ContactsLibTrapGetStringField);
    01213
    01214 /* FUNCTION: ContactsGetBinaryField
    01215  *
    01216  * DESCRIPTION:
    01217  *
    01218  * Fetches the binary value of the specified field from the specified record.
    01219  *
    01220  * PARAMETERS:
    01221  *
    01222  * libRefnum
    01223  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01224  * hContact
    01225  *      This any valid ContHandle that was obtain from a call to ContactsOpenSession.
    01226  * NameOfField
    01227  *      This is the field of type binary in which you want to set (ContactsLibBinaryFields).
    01228  * pFieldValue
    01229  *      pointer to the binary in which the fetched value will be placed.
    01230  * RETURNS:
    01231  *      noErr.
    01232  *      ContactsLibErrInvalidHandle.
    01233  * NOTES:
    01234  *      There are two possible fields that contain binary data, pictureField & ringtoneIdentifier.
    01235  *      pictureField will return a pointer to a string of data of the picture (JPEG).
    01236  *      ringtoneIdentifier returns a pointer to a 6 byte structure of type ToneIdentifier (described in ToneLibTypes.h)
    01237  */
    01238 extern  void*                   ContactsGetBinaryField(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibBinaryFields NameOfField, UInt16 *pDataSize)   CONTACTS_LIB_TRAP(ContactsLibTrapGetBinaryField);
    01239
    01240 /* FUNCTION: ContactsGetRingtoneForCategory
    01241  *
    01242  * DESCRIPTION:
    01243  *
    01244  * Gets the ToneIdentifier for a given category.
    01245  *
    01246  * PARAMETERS:
    01247  *
    01248  * libRefnum
    01249  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01250  * categoryID
    01251  *      The index of the category.
    01252  * tone
    01253  *      This is a pointer to a struct of type ToneIdentifier which contains the toneType (UInt16) and toneID (UInt32).
    01254  * RETURNS:
    01255  *      noErr.
    01256  */
    01257 extern  Err                     ContactsGetRingtoneForCategory(UInt16 libRefnum, UInt16 categoryID, void *tone) CONTACTS_LIB_TRAP(ContactsLibTrapGetRingtoneForCategory);
    01258
    01259 /* FUNCTION: ContactsGetFieldLabel
    01260  *
    01261  * DESCRIPTION:
    01262  *
    01263  * Gets the field label index of a field containing a label.
    01264  *
    01265  * PARAMETERS:
    01266  *
    01267  * libRefnum
    01268  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01269  * hContact
    01270  *      This any valid ContHandle.
    01271  * FieldNum
    01272  *      This is the field value of type (ContactsLibWithLabelFields).
    01273  * RETURNS:
    01274  *      Index of the label assigned to that field.
    01275  * NOTES:
    01276  *      In addition to a field have a field value, it can also have a field label.
    01277  *      For example, the Address field can also have a label describing if it is a Home, Work, etc.
    01278  *      This routine returns the index of the label which can then be used to get the actual label text
    01279  *      using GetLabelText or GetLabelList.
    01280  */
    01281 extern  Int16                   ContactsGetFieldLabel(UInt16 libRefnum, ContactsContHandle hContact, ContactsLibWithLabelFields FieldNum)   CONTACTS_LIB_TRAP(ContactsLibTrapGetFieldLabel);
    01282
    01283 /* FUNCTION: ContactsSetFieldLabel
    01284  *
    01285  * DESCRIPTION:
    01286  *
    01287  * Sets the field label index of a field containing a label.
    01288  *
    01289  * PARAMETERS:
    01290  *
    01291  * libRefnum
    01292  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01293  * hContact
    01294  *      This any valid ContHandle.
    01295  * FieldNum
    01296  *      This is the field value of type (ContactsLibWithLabelFields).
    01297  * LabelIndex
    01298  *      This is the 0 based index of the label to which the field should be assigned.
    01299  * RETURNS:
    01300  *      Nothing.
    01301  */
    01302 extern  void                    ContactsSetFieldLabel(UInt16 libRefnum, ContactsContHandle hToCont, ContactsLibWithLabelFields FieldNum, Int16 LabelIndex)  CONTACTS_LIB_TRAP(ContactsLibTrapSetFieldLabel);
    01303
    01304 /* FUNCTION: ContactsGetLabelText
    01305  *
    01306  * DESCRIPTION:
    01307  *
    01308  * Gets a particular label for a field based on its index.
    01309  *
    01310  * PARAMETERS:
    01311  *
    01312  * libRefnum
    01313  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01314  * hSession
    01315  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    01316  * type
    01317  *      This is type of the field label you wish to get (ContactsLabelType).
    01318  * labelNum
    01319  *      This is index within the label list.
    01320  * RETURNS:
    01321  *      String containing the label name.
    01322  *      pSizeOfBuffer
    01323  *          contains the size of the allocated buffer returned.
    01324  * NOTES:
    01325  *      This routine allocates memory and the string pointer returned must be freed by the caller.
    01326  */
    01327 extern  char*                   ContactsGetLabelText(UInt16 libRefnum, ContactsSession hSession, ContactsLabelType type, UInt16 labelNum, UInt16 *pSizeOfBuffer)    CONTACTS_LIB_TRAP(ContactsLibTrapGetLabelText);
    01328
    01329 /* FUNCTION: ContactsRenameCustomLabel
    01330  *
    01331  * DESCRIPTION:
    01332  *
    01333  * Sets one of the Custom Labels to a specified string.
    01334  *
    01335  * PARAMETERS:
    01336  *
    01337  * libRefnum
    01338  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01339  * hSession
    01340  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    01341  * fieldNum
    01342  *      This is field number of any one of the custom fields (ContactsLibCustomFields).
    01343  * fieldLabel
    01344  *      This is the string pointer in which you want the custom field's name to be assigned.
    01345  *      (the maximum length of a field label is ContactsLabelLength (includes null byte))
    01346  * RETURNS:
    01347  *      noErr.
    01348  * NOTES:
    01349  *      This routine allocates memory and the string pointer returned must be freed by the caller.
    01350  */
    01351 extern  Err                     ContactsRenameCustomLabel(UInt16 libRefnum, ContactsSession hSession, ContactsLibCustomFields fieldNum, Char* fieldLabel)   CONTACTS_LIB_TRAP(ContactsLibTrapRenameCustomLabel);
    01352
    01353 /* FUNCTION: ContactsGetCategoryList
    01354  *
    01355  * DESCRIPTION:
    01356  *
    01357  * Returns the current list of categories for the Contacts application.
    01358  *
    01359  * PARAMETERS:
    01360  *
    01361  * libRefnum
    01362  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01363  * hSession
    01364  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    01365  * pCategoryList
    01366  *      A pointer to an array of string pointers.
    01367  * RETURNS:
    01368  *      Each of the locations in the pCategoryList will cotain a string pointer.  If the category
    01369  *      does not exist, the string will be of length of zero.
    01370  * NOTES:
    01371  *      This routine allocates a string pointer for EVERY location in pCategoryList (even if
    01372  *      no category exists at that location).
    01373  */
    01374 extern  void                    ContactsGetCategoryList(UInt16 libRefnum, ContactsSession hSession, char *pCategoryList[ContactsNumCategories]) CONTACTS_LIB_TRAP(ContactsLibTrapGetCategoryList);
    01375
    01376 /* FUNCTION: ContactsGetNextCategory
    01377  *
    01378  * DESCRIPTION:
    01379  *
    01380  * Returns the current list of categories for the Contacts application.
    01381  *
    01382  * PARAMETERS:
    01383  *
    01384  * libRefnum
    01385  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01386  * hSession
    01387  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    01388  * currentCategory
    01389  *      The index of a category to be used as a reference to seek to the next category.
    01390  *      Passing ContactsAllCategories as the current Category is legal and can be used
    01391  *      to initiat a search of all the available categories.
    01392  * RETURNS:
    01393  *      The index of the next category.
    01394  */
    01395 extern  UInt16                  ContactsGetNextCategory(UInt16  libRefnum, ContactsSession hSession, UInt16 currentCategory)    CONTACTS_LIB_TRAP(ContactsLibTrapGetNextCategory);
    01396
    01397 /* FUNCTION: ContactsGetCategoryName
    01398  *
    01399  * DESCRIPTION:
    01400  *
    01401  * Returns the name of a category for a specified category index.
    01402  *
    01403  * PARAMETERS:
    01404  *
    01405  * libRefnum
    01406  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01407  * hSession
    01408  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    01409  * categoryIndex
    01410  *      The index of a category to be used as a reference to seek to the next category.
    01411  *      Passing ContactsAllCategories as the current Category is legal and can be used
    01412  *      to get the name of the "All" category label.
    01413  * RETURNS:
    01414  *      A string pointer to the category name.
    01415  * NOTE:
    01416  *      This routine returns a string pointer which must be freed.
    01417  */
    01418 extern  Char*                   ContactsGetCategoryName(UInt16 libRefnum, ContactsSession hSession, UInt16 categoryIndex)   CONTACTS_LIB_TRAP(ContactsLibTrapGetCategoryName);
    01419
    01420 /* FUNCTION: ContactsSetCategoryName
    01421  *
    01422  * DESCRIPTION:
    01423  *
    01424  * Returns the name of a category for a specified category index.
    01425  *
    01426  * PARAMETERS:
    01427  *
    01428  * libRefnum
    01429  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01430  * hSession
    01431  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    01432  * categoryIndex
    01433  *      The index of a category in which to assign the new label.
    01434  * pCategoryName
    01435  *      A string pointer in which to assign the category label.
    01436  * RETURNS:
    01437  *      none.
    01438  * NOTE:
    01439  *      To clear out a particular category, simply pass NULL for the pCategoryName.
    01440  */
    01441 extern  void                    ContactsSetCategoryName(UInt16 libRefnum, ContactsSession hSession, UInt16 categoryIndex, const Char *pCatName) CONTACTS_LIB_TRAP(ContactsLibTrapGetCategoryName);
    01442
    01443 /* FUNCTION: ContactsCategoryFind
    01444  *
    01445  * DESCRIPTION:
    01446  *
    01447  * Returns the category index given a specified category name.
    01448  *
    01449  * PARAMETERS:
    01450  *
    01451  * libRefnum
    01452  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01453  * hSession
    01454  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    01455  * pCatName
    01456  *      Name of the label in which to locate its index..
    01457  * RETURNS:
    01458  *      index of the category name specified.
    01459  */
    01460 extern  UInt16                  ContactsCategoryFind(UInt16 libRefnum, ContactsSession hSession, const Char *pCatName)  CONTACTS_LIB_TRAP(ContactsLibTrapCategoryFind);
    01461
    01462 /* FUNCTION: ContactsGetRingtoneForCategory
    01463  *
    01464  * DESCRIPTION:
    01465  *
    01466  * Returns ringtone for a given category.
    01467  *
    01468  * PARAMETERS:
    01469  *
    01470  * libRefnum
    01471  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01472  * categoryID
    01473  *      This is the index for any given category.
    01474  * pTone
    01475  *      a pointer to a ToneIdentifier structure.
    01476  * RETURNS:
    01477  *      Populates the pTone structure with a valid ToneIdentifier.
    01478  */
    01479 extern  Err                     ContactsGetRingtoneForCategory(UInt16 libRefnum, UInt16 categoryID, void *pTone)    CONTACTS_LIB_TRAP(ContactsLibTrapGetRingtoneForCategory);
    01480
    01481 /* FUNCTION: ContactsLookUpString
    01482  *
    01483  * DESCRIPTION:
    01484  *
    01485  * Searchs the contact database for the first match based on the specified key.
    01486  *
    01487  * PARAMETERS:
    01488  *
    01489  * libRefnum
    01490  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01491  * hSession
    01492  *      This any valid session handle that was obtain from a call to ContactsOpenSession.
    01493  * key
    01494  *      This is the string pointer to the key to be used for the search.
    01495  * sortByCompany
    01496  *      specifies how the db is sorted for this search.
    01497  * category
    01498  *      category to search within.
    01499  * completeMatch
    01500  *      contains true upon return if the key was completely matched.
    01501  * pNumMatchingChars
    01502  *      returns the number of matching characters upon return.  Pass NULL if dont care.
    01503  * masked
    01504  *      pass true if to include masked records in the search.
    01505  * RETURNS:
    01506  *      If a match is found, returns the ContHandle of the entry.
    01507  * NOTE:
    01508  *      Remember, a call to ReleaseHandle must be made if this routine returns a non-NULL value.
    01509  */
    01510 extern  ContactsContHandle      ContactsLookUpString(UInt16 libRefnum, ContactsSession hSession, Char* key, Boolean sortByCompany, UInt16 category,
    01511                                                         Boolean* completeMatch, UInt16* pNumMatchingChars, Boolean masked)  CONTACTS_LIB_TRAP(ContactsLibTrapLookUpString);
    01512
    01513 /* FUNCTION: ContactsGetLastError
    01514  *
    01515  * DESCRIPTION:
    01516  *
    01517  * Returns ringtone for a given category.
    01518  *
    01519  * PARAMETERS:
    01520  *
    01521  * libRefnum
    01522  *      Library reference number obtained from ContactsLib_OpenLibrary().
    01523  * RETURNS:
    01524  *      the last error code stored by the library.
    01525  * NOTE:
    01526  *      Some routines do not return error codes but store them internally.  The last error code store dinternally
    01527  *      can be obtained by calling this routine.
    01528  */
    01529 extern  Err                     ContactsGetLastError(UInt16 libRefnum)  CONTACTS_LIB_TRAP(ContactsLibGetLastErr);
    01530
    01531 #ifdef __cplusplus
    01532 }
    01533 #endif

Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:06:52 2008 for Palm API Guide