| GEOS SDK TechDocs | | ConstructOptr() ... | ContactMatchNumber() ...

---

ContactGetDBHandle()

VMFileHandle 	ContactGetDBHandle( void );

This function returns the handle of the Contact database, the database that contains all of the "address book" data used by the contdb library. This handle is necessary for various operations with the library. When you're done with the handle, remember to call ContactReleaseDBHandle() .

Include: contdb.goh

See Also: ContactGetDBHandleNoBlock(), ContactReleaseDBHandle().

ContactGetDBHandleNoBlock()

VMFileHandle 	ContactGetDBHandleNoBlock( void );

This function behaves in the same manner as ContactGetDBHandle() , except that if it cannot get the handle, it returns zero instead of waiting until the handleis available.When you're done with the handle, remember to call ContactReleaseDBHandle() .

Include: contdb.goh

See Also: ContactGetDBHandle().

ContactGetName()

Boolean	ContactGetName( 
        MemHandle 		record,
        TCHAR 		*dest);

This function gets the name associated with the record, filling in the dest buffer. If there was no name in the record, this function returns non-zero; otherwise, it returns zero.

Include: contdb.goh

See Also: ContactGetDBHandle().

ContactGetTruncatedName()

Boolean	ContactGetTrunactedName( 
        MemHandle 		record,
        TCHAR 		*dest,
        word		destSize);				/* Size of dest buffer */

This function gets the name associated with the record, filling in the dest buffer. It will truncate the name, as necessary to make it fit inside the buffer. Remember to leave space for the null terminator when determining how big a buffer you'll need. If there was no name in the record, this function returns non-zero; otherwise, it returns zero.

Include: contdb.goh

See Also: ContactGetDBHandle().

ContactGetUserDataID()

RecordID	ContactGetUserDataID( void );

This functionreturns the RecordID of the special Contacts database record containing the user's own contact data.

Include: contdb.goh

See Also: FoamDBGetRecordFromID().

ContactImportDBFromTextFile()

void 	ContactImportDBFromTextFile(
        hptr 		fileImport);					/* file's handle */

This function imports contact database information from an ASCII text file. This file's format is described below. The function will compare imported records to those already in the Contacts database. Any identical records will be merged.

A short sample file is shown below.

[RECORD]
[FIELD]
Name
[FIELD-NAME]
[FIELD-DATA]
Hudson W.
[FIELD-END]
[FIELD]

Company
[FIELD-NAME]
[FIELD-DATA]
Space Marines
[FIELD-END]
[FIELD]
Title
[FIELD-NAME]
[FIELD-DATA]
Private
[FIELD-END]
[RECORD-END]

[RECORD]
[FIELD]
Name
[FIELD-NAME]
[FIELD-DATA]

Adams, John Quincy
[FIELD-END]
[FIELD]
Tel
[FIELD-NAME]
[FIELD-DATA]
1 617 438 1776
[FIELD-END]
[FIELD]
[FIELD-NAME]
Company
[FIELD-DATA]
[FIELD-END]
USA Government
[FIELD]
Notes
[FIELD-NAME]
Note(Birthday)
[FIELD-DATA]
July 11, 1767
Gift ideas: flowers
[FIELD-END]
[RECORD-END]

The ASCII file follows these rules:

• The page is a DOS text file, using the "Latin 1" code page (number 819).
• Each line of text may ends with a newline; the newline may be preceded by an optional carriage return.
• The data corresponding to each record is delimited by a line reading [RECORD] at the start and another line reading [RECORD-END] at the end. Any text that appears outside of these delimiters is lost.
• Each record consists of one or more fields. Each field is delimited by a line reading [FIELD] and a line reading [FIELD-END].
• For each field, the first line after the [FIELD] line will consist of one of the following strings, specifying the field's type:
  Name, Company, Title, Address, Tel, Fax, Mail, DTMF, Note.
• There may be a line of text between the [FIELD-NAME] and [FIELD-DATA] lines. If there is no such line of text, then the field's name is the default name for its data type. If there is such a line of text, then you may form the field name by placing the text of this line between parentheses and preceding it with the default name for the field. In the "Birthday" example, above, the full field name would be "Note(Birthday)".
  The exception to this rule is "GSM/PCN" in phone number fields. If the line of text is "GSM/PCN", treat it as if it were "GSM". The full field name will probably be "Tel(GSM)" or "Fax(GSM)".
• The line(s) of text between the [FIELD-DATA] line and the [FIELD-END] line contain the field's data, if any. If there are no lines of text, that means that the field contains no data. There may be more than one line of text.

Include: contdb.goh

See Also: ContactExportDBToTextFile().

ContactMatchName()

RecordID	ContactMatchName( 
        TCHAR		name,
        ContdbFieldType		type,
        Boolean		stopEarly,
        FieldID		*field,
        word		*numMatches );

This function takes aname, searches all fields of the specified type in all records of the Contact database, returning the RecordID and FieldID of the matching field, if any; if there was no match, it returns -1.

The comparison of names does not consider case.

This function takes the following arguments:

name

String containing the name to match.

type

The type of phone number to match; one of CFT_NAME, CFT_COMPANY CFT_TITLE, CFT_ADDRESS, CFT_PHONE, CFT_FAX, CFT_EMAIL, CFT_DTMF, CFT_NOTES.

stopEarly

Set this flag true to stop searching after finding the first matching name; set it false to find out the number of matching names.

field

Pointer to a FieldID buffer. The function will fill this buffer in with the FieldID of the matching field, if any.

numMatches

Pointer to a word buffer. The function will fill this buffer in with the number of matching records found. This number is only meaningful if the stopEarly flag is false .

Include: contdb.goh

See Also: ContactEnsureEmptyField(), FoamDBSetFieldData().