Contacts: 3 Using a Dedicated Contact

| Up: GEOS SDK TechDocs | Up | Prev: 2 Choosing Contacts From a Log | Next: 4 Logging Calls 
ContactMatchName(), ContactEnsureField()

Perhaps you're writing a special-purpose application that is supposed to communicate with just one contact. Perhaps a carry-out restaurant chain has contracted you to write an application that the user can use to place an order over the phone. The program would only need to make contact with one place: the local restaurant's GSM phone number.

In this case, you wouldn't want to provide any gadgetry for choosing a contact--your program is only interested in one dedicated contact. Still, it's worthwhile to store the contact in the Contact database--if the restaurant's phone number changes, the user can enter the corrected number using the Contact Manager built-in application.

To find the Contact record for a particular contact, you will need to make sure that your .gp file contains the following lines:

library contdb
library foamdb

Finding the "Stuckey's Snack Shack" Contact , below, shows an example of how you could find a dedicated contact in the Contact database, and extract the phone number associated with that contact.

To locate a dedicated contact and extract its phone number, carry out the following steps:

  1. To get the RecordID of the contact's record, call ContactMatchName() . This routine takes a search string (pass the contact's name), a ContdbFieldType (pass CFT_NAME, since we're searching by name), a flag (pass a non-zero value to specify that you're only interested in one matching record), a pointer to a FieldID buffer to fill in and a pointer to a word value to fill in. It returns the RecordID of the contact (or -1 if the contact wasn't found). It also fills in the FieldID buffer with the contact's name field FieldID and fills in the word value with the number of matches found; neither of these values is important to our purpose.
    If the contact is not found, there are a couple of approaches the application can take:
    ¸ Create a new record with the proper name and a guess at the phone number. The code example below illustrates this approach.
    ¸ Signal to the user that an error has occured and halt the current operation.
  2. Get the Contact database's handle. To do this, call ContactGetDBHandle() . This routine takes no arguments and returns the database's handle.
  3. Get the record's handle by calling FoamDBGetRecordFromID() . This routine takes the Contact database's handle and the record's RecordID . It returns the record's memory handle.
  4. Get the FieldID of the record's GSM phone number field. In the example below, we assume that the record has only one phone number field, and that this is the field we want. For a more rigorous approach, we could examine each field to make sure it was named "Tel (GSM)". For an example of how one might examine all the fields of a record, see To Get More Info on a Contact .
    For our shortcut, we use the ContactEnsureField() function. This function takes as arguments a record handle, a field name string (in our example, we pass a null optr to specify that we should use the default field name, and the ContdbFieldType of the field to find ( pass CFT_PHONE). The function returns a FieldID .
  5. To extract the phone number data, call FoamDBGetFieldData() . Pass the database handle, the record handle, the FieldID , a buffer to write the name to, and the size of that buffer. The function fills in the buffer with the phone number string, and returns the length of that string. The returned string might not be null-terminated; thus you will either need to keep track of the returned string length, or else terminate the string.
  6. Now that you're done with the record, let the database know by calling FoamDBDiscardRecord() . This routine takes the Contact's database handle and the record's handle as arguments.
  7. Now that you're done with the database, release its handle by calling ContactReleaseDBHandle() .

Code Display 4-3 Finding the "Stuckey's Snack Shack" Contact

TCHAR 		theName[]=		"Stuckey's Snack Shack";
TCHAR 		gsmNum[MAX_NUMBER_FIELD_DATA_LEN] = "1.800.788.2539"
word 		gsmNumLen;
FieldID 		theField;
word		dummyNumMatches;
RecordID		theRecordID;
Memhandle 		theRecord;
VMFileHandle 		CDBHandle;
theRecordID = ContactMatchName(theName, CFT_NAME,1, &theField, &dummnyNumMatches);
if ( theRecordID == LECI_INVALID_CONTACT_ID) { /* If we didn't find the record...*/
  theRecord = ContactCreateRecordFromTemplate(); /* ... then we create it */

  /* Fill in the name field; here @TelGSMStr is a chunk holding the string
   * "Tel(GSM)" */
  theField = ContactEnsureField( theRecord, NullOptr, CFT_NAME );
  CDBHandle = ContactGetDBHandle();
  FoamDBSetFieldData( CDBHandle, theRecord,theField, theName, sizeof(theName)-1 );
  /* Fill in the fax field of new record with default GSM number string */
  /* Fill in the name field; here @TelGSMStr is a chunk holding the string
   * "Tel(GSM)" */
  theField = ContactEnsureField( theRecord, @TelGSMStr, CFT_PHONE );
  FoamDBSetFieldData( CDBHandle, theRecord, theField, gsmNum, 14 );

  ContactReleaseDBHandle();
  /* Save the newly created record to the Contact DB */
  theRecordIIndex = ContactSaveRecord( theRecord );
  theRecord = FoamDBGetVisibleRecord( CDBHandle, theRecordIndex );
}
else { /* If we successfully found the record, then get its handle */
CDBHandle = ContactGetDBHandle();
theRecord = FoamDBGetRecordFromID( CDBHandle, theRecordID);
}
/* Whether we found the record or just now created it, we now have 
 * its handle and can extract the information that we want. */
  /* Fill in the name field; here @TelGSMStr is a chunk holding the string
   * "Tel(GSM)" */
theField = ContactEnsureField( theRecord, @TelGSMStr, CFT_PHONE );
/* Copy the fax number into our buffer */
gsmNumLen = FoamDBGetFieldData( CDBHandle, theRecord, theField, gsmNum,
						MAX_NUMBER_FIELD_DATA_LEN);
gsmNum[gsmNumLen]= `\000`
	/* If we need more information about the contact (e.g., street address,
	 * fax number, etc.) this would be a good place to get it. */
FoamDBDiscardRecord( CDBHandle, theRecord );
ContactReleaseHandle();

/* Do something clever with theName and gsmNum */

To allow the user to edit the contact information for this single contact, use a ContactEdit object. To specify the contact that the user will work with, you will need its handle. Pass the handle as an argument to the MSG_CONTACT_EDIT_DISPLAY_RECORD message. (Don't call ContactSaveRecord() , FoamDBDeleteRecord() , or FoamDBDiscardRecord() when done with this handle; the controller will do so.)

| Up: GEOS SDK TechDocs | Up | Prev: 2 Choosing Contacts From a Log | Next: 4 Logging Calls