Contacts: 5 To Get More Info about a Contact

| Up: GEOS SDK TechDocs| Up | Prev: 4 Logging Calls | Next: 6 The User's Own Data 
FoamDBFieldEnum(), FoamDBGetFieldType(), FoamDBGetFieldName()

In previous examples, we've shown how to get a selected contact's name and GSM phone number. It is possible to get more information about a contact given if you know which database it's in and its RecordID number.

In the examples shown in Handling the ContactList's "Selected" Message, Handling the RecentContacts "Selected" Message, and Finding the "Stuckey's Snack Shack" Contact there is a comment noting a good place to get more information about a contact. If, for some reason, you need to find out information about a Contact in a context other than shown in one of those examples,

  1. The database containing the contact must be the current contact database; in the contexts described above, this will be true. You will need the record's RecordID number.
    To query a ContactList object for the RecordID of its selected record, use the MSG_CONTACT_LIST_GET_ID_OF_SELECTED_RECORD message. This message takes no arguments, and returns a RecordID.
  2. Gain access to the current Contact database by calling ContactGetDBHandle(), storing the returned handle.
  3. To access the database record corresponding to the selected contact, call FoamDBGetRecordFromID(). This returns the record's handle.
  4. Get the contact information you need. Information about how you might do this is described in the paragraphs following this checklist.
  5. When you're done with the record handle, call FoamDBDiscardRecord() to free the handle.
  6. Be sure to call ContactReleaseDBHandle() to signal you're done with the database. You shouldn't keep the handle around for long; doing so prevents the file from being closed.

To find out any other sort of information about the contact, you'll need to access one of the fields of the record. Fields within a Foam DB record (the Contact DB is a Foam DB) are identified by a FieldID number.

The FoamDBFieldEnum() function provides a way to scan all the fields of a record. The following code snippet shows how you might use FoamDBFieldEnum() to search for all of a contact's voice phone numbers. FoamDBFieldEnum() calls a callback routine for each of the record's fields. FoamDBFieldEnum() takes as arguments a record handle, a pointer to a data buffer (this pointer will be passed to the callback routine; it gives you a way to pass data to the callback; in our example, we pass the record handle in the buffer), and a pointer to a callback function. The callback function is passed a FieldHeader structure and a pointer to the data buffer that was passed toFoamDBFieldEnum(). From the FieldHeader, it can get the FieldID from the FieldHeader's FH_id field. To get information about each field, use the FoamDBGetFieldType(), FoamDBGetFieldName(), and/or FoamDBGetFieldData() routines. Each of these routines takes the contact database handle, a record handle, a FieldID, and a pointer to a buffer to fill with a return value.

Code Display: Checking All Fields of a Contact

In this example, we check all fields of a contact and build up an array with the names and data for those fields that correspond to voice phone numbers. We know that the database containing the contact is the current contact database. We know the contact's RecordID value.

void BuildNumberList( RecordID recordID ) {
	/* Scan all fields of the Contact record */
	/* For each one that corresponds to a voice phone number, store 
	 * the field's name (e.g., "Phone") and data (e.g., "555-1212") in
	 * the global Data array. */

	VMFileHandle 		CDBHandle;
	MemHandle		curRecord;
	CDBHandle = ContactGetDBHandle();
	curRecord = FoamDBGetRecordFromID( CDBHandle, recordID );
	NumberOfNumbers = 0			/* Global variable: 
					number of elements in Data array*/
	FoamDBFieldEnum( curRecord, &curRecord, &BuildNumberListCallback );
	FoamDBDiscardRecord( CDBhandle, curRecord) ; /* Done with the record */
	ContactReleaseDBHandle(); /* Done with the Contact DB for now */
}
Boolean _pascal BuildNumberListCallback( FieldHeader *field, void *enumData ) {
	VMFileHandle		CDBHandle;
	byte		fieldType;
	MemHandle		curRecord = *((MemHandle *) enumData );
	CDBandle = ContactGetDBHandle();
	FoamDBGetFieldType( CDBHandle, curRecord, field->FH_id, &fieldType);
	if (fieldType == CFT_PHONE ) { /* For each voice phone number */
				/* To look for something other than a phone 
				 * number, we would use a different 
				 * ContdbFieldType value. */
					/* Grab the field name */
	  FoamDBGetFieldName( CDBHandle, curRecord, field->FH_id, 
			Data[NumberOfNumbers].fName, MAX_FIELD_LABEL_LEN);
					/* Grab the field data */
					/* If the data has zero length, func will
					 * return zero. */
	  if (FoamDBGetFieldData( CDBHandle, curRecord, field->FH_id, 
			Data[NumberOfNumbers].fData, MAX_FIELD_NUMBER_DATA_LEN)) {
					/* If the data was not of zero length
					 * (wasn't just a blank field), then 
					 * up our NumberOfNumbers. */
	    NumberOfNumbers++;
	  }
	}
	ContactReleaseDBHandle(); 	/* We're done with the database */
				/* if we return non-zero, we'll stop Enum'ing 
				 * through the fields. Since we only have room
				 * for 10 fields in our array... */
	return( NumberOfNumbers > 10) ; 
}

As shown above, to get the field data and field name associated with a field, use the FoamDBGetFieldData() and FoamDBFGetFieldName() functions. Many users will leave blank fields in their contact records; to test for a blank field, check FoamDBGetFieldData()'s return value; if it is zero, then the user has not filled in that field of the contact information.

| Up: GEOS SDK TechDocs| Up | Prev: 4 Logging Calls | Next: 6 The User's Own Data