|
|
|
|
|
|
|
Contact.opx — The Contacts engine 
The Contacts Engine is an EPOC Release 5 resource which provides a central repository for address book information. Clients of the Contacts Engine include the Contacts application and Messaging. Contact data may be synchronized with PC based Personal Information Managers using EPOC Connect.
One of the major benefits of using the Contacts Engine in preference to the Data Model is that the Contacts Engine is server based, rather than file based. This means that multiple applications may have simultaneous access to the data.
Contact OPX gives access to the Contacts Engine. To use this OPX, you must include the header file Contact.oxh, which contains the following declaration:
CONST KUidContactOpx&=&10003ED7
CONST KOpxContactVersion%=$100
DECLARE OPX Contact,KUidContactOpx&,KOpxContactVersion%
COCreateContactFile:(aFileName$):1
COOpenContactFile:(aFileName$):2
COCloseContactFile: :3
COCountContacts&: :4
COSortContactFile:(aMappingArray&):5
COFindContact&:(aString$,aMappingArray&):6
COSortedContactFileAt:(aIndex&):7
COContactId&: :8
COReadContact:(aContactItemId&):9
COOpenContact:(aContactItemId&):10
COCloseContact: :11
COCreateContact: :12
COAddNewContact: :13
CODeleteContact: :14
COOpenContactTemplate: :15
COCloseContactTemplate: :16
COContactFieldDisable:(aBool%) :17
COContactFieldIsDisabled%: :18
COSetContactHidden:(aHidden%):19
COIsContactHidden%: :20
COSetContactSystem:(aSystem%):21
COIsContactSystem%: :22
COCompressContactFile: :23
COCompressNeeded%: :24
COContactFieldCount&: :25
COContactFieldArrayAt:(aIndex&):26
COContactFieldFind%:(aTypeArrayHandle&):27
COContactFieldReset: :28
COContactFieldCreate: :29
COContactFieldInsert:(aIndex&):30
COContactFieldAdd: :31
COContactFieldDelete: :32
COContactFieldMove:(aPosFrom&,aPosTo&):33
COContactFieldContent:(aContentTypeArray&):34
COContactFieldSetHidden:(aHidden%):35
COContactFieldIsHidden%: :36
COContactFieldSetReadOnly:(aReadOnly%):37
COContactFieldIsReadOnly%: :38
COContactFieldSetLabel:(aLabel$):39
COContactFieldLabel$: :40
COContactFieldSetMapping:(aMapping&):41
COContactFieldAddType:(aType&):42
COContactFieldSetText:(aString$):43
COContactFieldSetLong:(aStringAddr&,aLength&):44
COContactFieldText$: :45
COContactFieldLength&: :46
COContactFieldLong:(aBufHandle&) :47
END DECLARE
This OPX is introduced in ER5, and is not available to users of earlier devices.
Usage: COCreateContactFile: (aFileName$)
Creates a new contacts file with the path and filename aFileName$. Note that filenames other than \system\data\contacts.cdb can not be accessed by the Contacts application.
See COOpenContactFile:.
Usage: COOpenContactFile: (aFileName$)
Opens an existing contacts file with the path and filename aFileName$. aFileName$ will usually refer to \system\data\contacts.cdb on one of the drives. Due to the Contacts Engine’s server architecture there is no requirement to close the Contacts application in order for an OPL application to gain read/write access to the database. Individual records are locked when write access is needed.
See COCloseContactFile:.
Usage: COCloseContactFile:
Closes the contacts database which has previously been opened or created.
See COOpenContactFile:, COCreateContactFile:.
Usage: numContacts& = COCountContacts&:
Returns the number of contacts in the contacts database.
Usage: COSortContactFile: (aMappingArray&)
Sorts the contacts database by one or more fields. The fields to sort by are specified by an array of long integers. The first entry in the array is a count of the number of elements in the array, including itself. The remaining entries in the array specify the UIDs of the fields to sort by. Use ADDR() to pass the address of this array as a parameter. Rather than physically sort the records in the database, the OPX creates an internal index array which can be accessed using COSortedContactFileAt:. The following field UIDs are defined in Contacts.oxh:
CONST KUidCntFieldAddressValue =&1000130C
CONST KUidCntFieldPostOfficeValue =&10004DF4
CONST KUidCntFieldExtendedAddressValue=&10004DF5
CONST KUidCntFieldLocalityValue =&10004DF6
CONST KUidCntFieldRegionValue =&10004DF7
CONST KUidCntFieldPostCodeValue =&10004DF8
CONST KUidCntFieldCountryValue =&10004DF9
CONST KUidCntFieldCompanyNameValue =&1000130D
CONST KUidCntFieldPhoneNumberValue =&1000130E
CONST KUidCntFieldGivenNameValue =&1000137C
CONST KUidCntFieldFamilyNameValue =&1000137D
CONST KUidCntFieldAdditionalNameValue =&1000178A
CONST KUidCntFieldSuffixNameValue =&1000178B
CONST KUidCntFieldPrefixNameValue =&1000178C
CONST KUidCntFieldHiddenValue =&1000178D
CONST KUidCntFieldEMailValue =&1000178E
CONST KUidCntFieldMsgValue =&1000178F
CONST KUidCntFieldSmsValue =&10001790
CONST KUidCntFieldFaxValue =&10001791
CONST KUidCntFieldDefinedTextValue =&10001792
CONST KUidCntFieldNoteValue =&1000401C
CONST KUidCntFieldBirthdayValue =&10004034
CONST KUidCntFieldUrlValue =&10004035
CONST KUidCntFieldStorageInlineValue =&10004036
CONST KUidCntFieldNoneValue =&00000000
See COSortedContactFieldAt:
Usage: numberFound& = COFindContact&: (aString$, aMappingArray&)
Searches from the beginning of the contacts database for aString$. The fields to be searched are specified in an array of UIDs. The setting up of this array is described above in SortContactFile:
See COSortContactFile:, COSortedContactFileAt:.
Usage: COSortedContactFileAt: (aIndex&)
Moves the current contact pointer. This is set using the index array previously created by a call to COSortContactFile: or COFindContact:. Valid values for aIndex& range from 1 to COCountContacts&: in the case of a sort. For a search, COFindContact returns the number of matching records which acts as an upper bound for aIndex&.
See COSortContactFile:, COFindContact:.
Usage: contactId& = COContactId&:
Return the ID of the current contact. The returned ID may be stored and used in subsequent calls to COReadContact: and COOpenContact:.
Usage: COReadContact: (aContactId&)
Moves to the contact record aContactId& and prepares it for read access.
See COOpenContact:, COContactId&:.
Usage: COOpenContact: (aContactId&)
Opens the contact record aContactId& for read/write access. As a result of this call, the record will be locked and unavailable for use by other applications. A call must subsequently be made to COCloseContact: to unlock the record.
See COReadContact:.
Usage: COCloseContact:
Close the previously opened contact. Current data will be written to the database, and the lock on the record will be removed. A call to COOpenContact: must always be followed by COCloseContact:.
Usage: COCreateContact:
Creates a new contact. The fields created are based upon the template. Once data has been added to the contact, it should be written to the database with a call to COAddNewContact:
See COOpenContactTemplate:.
Usage: COAddNewContact:
Add the current contact to the contacts file. This will normally follow a call to COCreateContact:, and the addition of some contact data.
Usage: CODeleteContact:
Sets the deleted flag in the current contact. This will not affect the database until the contact has been closed.
Usage: COOpenContactTemplate:
The contacts engine has a special purpose record: the template. The template is used for creating new empty records. COCreateContact: copies the fields in the template to create the blank record. COOpenContactTemplate: opens the database template. Once a template has been opened, all record and field oriented procedures operate on the template until a call to COCloseContactTemplate: is made.
Usage: COCloseContactTemplate:
Writes the contact template to the contacts database. Any further calls to field procedures will act on the current contact.
See COOpenContactTemplate:.
Usage: COContactFieldDisable:(aState%)
In a template, fields may be disabled. A field marked as disabled in the template will not be created in a new contact. aState% is set to 1 to disable a field, and 0 to enable it.
Usage: COContactFieldIsDisabled%:
Checks whether the current field in the template is marked as disabled. A non-zero value is returned if the field is disabled.
Usage: COSetContactHidden: (aHidden%)
Set the hidden attribute of the current contact. aHidden% is 1 to set the hidden attribute or 0 to clear it. This will not affect the database until the contact has been closed.
See COIsContactHidden%:.
Usage: hidden% = COIsContactHidden%:
Checks whether the current contact has the hidden attribute set. Returns a non-zero value if the hidden attribute is set or zero otherwise.
See COSetContactHidden:.
Usage: COSetContactSystem: (aSystem%)
Set the system attribute of the current contact. aSystem% is 1 to set the system attribute or 0 to clear it. This will not affect the database until the contact has been closed.
See COIsContactSystem%:.
Usage: system% = COIsContactSystem%:
Checks whether the current contact has the system attribute set. Returns a non-zero if the system attribute is set or zero otherwise.
See COSetContactSystem:.
Usage: COCompressContactFile:
Compress the contacts file. Space taken up by deleted contacts is released. Note that the engine may hold on to deleted records until after synchronization, and may not perform a compress at all if the gains are deemed to be small.
See COCompressNeeded%:.
Usage: compressNeeded% = COCompressNeeded%:
Checks whether compression is advisable because a lot of space is occupied by deleted records. The call returns a non-zero value if compression is advised.
See COCompressContactFile:.
Usage: numberOfFields& = COContactFieldCount&:
Returns the number of fields in the current contact.
Usage: COContactFieldArrayAt: (aIndex&)
Sets the current field to field number aIndex&. Field numbers range from 1 to COContactFieldCount&:.
Usage: index% = COContactFieldFind%: (aTypeArrayHandle&)
Searches for a particular field within the current / template contact field array. The field to search for is specified by an array of long integers. The first entry in the array is a count of the number of elements in the array, including itself. The second entry is a UID from this list (defined in Contacts.oxh):
CONST KUidCntFieldAddressValue =&1000130C
CONST KUidCntFieldPostOfficeValue =&10004DF4
CONST KUidCntFieldExtendedAddressValue=&10004DF5
CONST KUidCntFieldLocalityValue =&10004DF6
CONST KUidCntFieldRegionValue =&10004DF7
CONST KUidCntFieldPostCodeValue =&10004DF8
CONST KUidCntFieldCountryValue =&10004DF9
CONST KUidCntFieldCompanyNameValue =&1000130D
CONST KUidCntFieldPhoneNumberValue =&1000130E
CONST KUidCntFieldGivenNameValue =&1000137C
CONST KUidCntFieldFamilyNameValue =&1000137D
CONST KUidCntFieldAdditionalNameValue =&1000178A
CONST KUidCntFieldSuffixNameValue =&1000178B
CONST KUidCntFieldPrefixNameValue =&1000178C
CONST KUidCntFieldHiddenValue =&1000178D
CONST KUidCntFieldEMailValue =&1000178E
CONST KUidCntFieldMsgValue =&1000178F
CONST KUidCntFieldSmsValue =&10001790
CONST KUidCntFieldFaxValue =&10001791
CONST KUidCntFieldDefinedTextValue =&10001792
CONST KUidCntFieldNoteValue =&1000401C
CONST KUidCntFieldBirthdayValue =&10004034
CONST KUidCntFieldUrlValue =&10004035
CONST KUidCntFieldStorageInlineValue =&10004036
CONST KUidCntFieldNoneValue =&00000000
The third value is a VCard mapping. This is used when synchronizing to other applications using the VCard format:
CONST KIntCntFieldVCardMapADR =&1000401D
CONST KIntCntFieldVCardMapPOSTOFFICE =&10004DEA
CONST KIntCntFieldVCardMapEXTENDEDADR =&10004DEB
CONST KIntCntFieldVCardMapLOCALITY =&10004DEC
CONST KIntCntFieldVCardMapREGION =&10004DED
CONST KIntCntFieldVCardMapPOSTCODE =&10004DEE
CONST KIntCntFieldVCardMapCOUNTRY =&10004DEF
CONST KIntCntFieldVCardMapAGENT =&1000401E
CONST KIntCntFieldVCardMapBDAY =&1000401F
CONST KIntCntFieldVCardMapEMAILINTERNE =&10004020
CONST KIntCntFieldVCardMapGEO =&10004021
CONST KIntCntFieldVCardMapLABEL =&10004022
CONST KIntCntFieldVCardMapLOGO =&10004023
CONST KIntCntFieldVCardMapMAILER =&10004024
CONST KIntCntFieldVCardMapNOTE =&10004025
CONST KIntCntFieldVCardMapORG =&10004026
CONST KIntCntFieldVCardMapPHOTO =&10004027
CONST KIntCntFieldVCardMapROLE =&10004028
CONST KIntCntFieldVCardMapSOUND =&10004029
CONST KIntCntFieldVCardMapTEL =&1000402A
CONST KIntCntFieldVCardMapTELFAX =&1000402B
CONST KIntCntFieldVCardMapTITLE =&1000402C
CONST KIntCntFieldVCardMapURL =&1000402D
CONST KIntCntFieldVCardMapUnusedN =&1000402E
CONST KIntCntFieldVCardMapUnusedFN =&1000402F
CONST KIntCntFieldVCardMapNotRequired =&10004030
CONST KIntCntFieldVCardMapUnknownXDash =&10004031
CONST KIntCntFieldVCardMapUnknown =&10004032
CONST KIntCntFieldVCardMapUID =&10004033
The remaining entries in the array are used to specify the field more explicitly than is possible using just the VCard mapping above. For example KIntCntFieldVCardMapTEL on it’s own is not sufficient to differentiate a home phone number from a work number. These entries are known as VCard types. Useful VCard types are:
CONST KIntCntFieldVCardTypeWORK=&100039DA
CONST KIntCntFieldVCardTypeHOME=&100039DB
CONST KIntCntFieldVCardTypeMSG=&100039DC
CONST KIntCntFieldVCardTypeVOICE=&100039DD
CONST KIntCntFieldVCardTypeFAX=&100039DE
CONST KIntCntFieldVCardTypePREF=&10003E70
CONST KIntCntFieldVCardTypeCELL=&10003E71
CONST KIntCntFieldVCardTypePAGER=&10003E72
CONST KIntCntFieldVCardTypeBBS=&100039D5
CONST KIntCntFieldVCardTypeMODEM=&100039D6
CONST KIntCntFieldVCardTypeCAR=&100039D7
CONST KIntCntFieldVCardTypeISDN=&100039D8
CONST KIntCntFieldVCardTypeVIDEO=&100039D9
CONST KIntCntFieldVCardTypeDOM=&10003E80
By way of example, here are some common fields and the arrays needed to find them:
|
Field |
Entries in array |
|
Title |
3 |
|
First name |
3 |
|
Middle name |
3 |
|
Last name |
3 |
|
Suffix |
3 |
|
Mobile |
5 |
|
Home tel |
4 |
|
Home fax |
5 |
|
Pager |
5 |
|
Home Email |
4 |
|
Home PO box |
4 |
|
Home ext address |
4 |
|
Home address |
4 |
|
Home city |
4 |
|
Home region |
4 |
|
Home p’code |
4 |
|
Home country |
4 |
|
Company |
3 |
|
Job title |
2 |
|
Work mobile |
5 |
|
Work tel |
4 |
|
Work fax |
5 |
|
Work pager |
5 |
|
Work email |
4 |
|
Web page |
3 |
|
Work PO box |
4 |
|
Work ext address |
4 |
|
Work address |
4 |
|
Work city |
4 |
|
Work region |
4 |
|
Work p’code |
4 |
|
Work country |
4 |
|
Birthday |
3 |
|
Notes |
3 |
Usage: COContactFieldReset:
Deletes all the fields in the current contact. Attempting to use this procedure on the template will result in a KErrAccess% error.
Usage: COContactFieldCreate:
Creates an empty field which can be added / inserted to the current contact / template.
See COContactFieldInsert:, COContactFieldAdd:
Usage: COContactFieldInsert: (aIndex&)
Inserts a field into the current contact at the position aIndex&. The field should be created first with COContactFieldCreate: Field numbering starts at 1.
Usage: COContactFieldAdd:
Appends an empty new field to the current contact. The field should be created first with COContactFieldCreate:
Usage: COContactFieldDelete:
Deletes the current field from the current contact. Any subsequent fields are renumbered.
Usage: COContactFieldMove: (aPosFrom&, aPosTo&)
Moves a field in the current contact from aPosFrom& to aPosTo&. Field numbering starts at 1.
Usage: COContactFieldContent: (contentTypeArray&)
Returns a description of the current field in terms of a UID and VCard mappings. The address of a long integer array is passed in contentTypeArray&, which is filled with data as described in COContactFieldFind%:.
Usage: COContactFieldSetHidden: (aHidden%)
Sets the hidden attribute of the current contact. aHidden% is 1 to set the hidden attribute or 0 to clear it. Setting a field to hidden in the template has a useful effect in the Contacts application. The field will not be added to new records, but will be available in the “Add item” list.
See COContactFieldIsHidden%:.
Usage: hidden% = COContactFieldIsHidden%:
Checks whether the current field is hidden. Returns 1 if the hidden attribute is set or 0 otherwise.
See COContactFieldSetHidden:.
Usage: COContactFieldSetReadOnly: (aReadOnly%)
Sets the read only attribute of the current contact. aHidden% is 1 to set the read only attribute or 0 to clear it.
See COContactFieldIsReadOnly%:.
Usage: readOnly% = COContactFieldIsReadOnly%:
Checks whether the current field is read only. Returns a non-zero value if the read only attribute is set.
See COContactFieldSetReadOnly:.
Usage: COContactFieldSetLabel: (aLabel$)
Sets the label of the current field.
See COContactFieldLabel$:.
Usage: label$ = COContactFieldLabel$:
Returns the label of the current field.
See COContactFieldSetLabel:
Usage: COContactFieldSetMapping: (aMapping&)
Sets a field’s VCard mapping. There is one mapping per field.
See COContactFieldFind%:, COContactFieldAddType:
Usage: COContactFieldAddType: (aType&)
Sets a field’s Uid or VCard type. There may be multiple VCard types specified for each field. The first call to this procedure adds the Uid, subsequent calls add VCard types.
See COContactFieldFind%:, COContactFieldSetMapping:.
Usage: COContactFieldSetText: (aString$)
Assigns a text value to the current field. If a value needs to be set which is longer than the OPL string limit of 255 characters, use COContactFieldSetLong:
Usage: COContactFieldSetLong:(aStringAddr&,aLength)
Assigns a text value to the current field. The value is specified by passing the address of a buffer containing the value, and the length of the text held within it. For short strings, it may be more straightforward to use COContactFieldSetText.
Usage: string$= COContactFieldText$:
Retrieves the text value of the current field. If the value is longer than 255 characters, it is truncated. To retrieve longer values, use COContactFieldLong:.
Usage: length&=COContactFieldLength&:
Returns the length of the current field in characters.
Usage: COContactFieldLong:(aBufHandle&)
Retrieves the text value of the current field. The value is written to a buffer starting at aBufHandle&. COContactFieldLength& may be used to ensure the buffer is large enough hold the value.
See COContactFieldText$:.
|
|
|
|
|
|
|