Contacts: 1 Setting up a Contact List

ContactListClass, CONTACT_LIST_NOTIFY_CONTACT_SELECTED_MSG, ContactGetDBHandle(), FoamDBGetRecordFromID(), FoamDBGetFieldData(), FoamDBDiscardRecord(), ContactReleaseDBHandle()

To present the user with a list of Contacts, do the following:

Make sure that your .gp file contains lines requiring the foamdb and contdb libraries:

library contdb
library foamdb

In your source code, create a ContactList object. The following ContactList object declaration allows the user to pick a contact. If the contact has more than one GSM phone number, the controller will make the user choose one of the fields.

When the user chooses a contact, the ContactList will send a message to an object. The ContactList's GCI_output and ATTR_CONTACT_LIST_NOTIFY_CONTACT_SELECTED_MSG specify the object and message. In the example below, the application's process object will handle a message. We will discuss the message in more detail below.
To make the ContactList SMS-specific, set its ATTR_CONTACT_LIST_CALL_TYPE to CCT_SMS as shown below. This will gray out contacts which do not have SMS phone numbers.
To include the Select button, set the CLF_SELECT_CONTACT_NUMBER feature flag in ATTR_GEN_CONTROL_REQUIRE_UI.
To include the ContactList's Search bar, set the CLF_SEARCH feature flag in ATTR_GEN_CONTROL_REQUIRE_UI; to exclude the Search bar, exclude the UI.
Optionally, you can use the standard Contact List bitmap by making your ContactList a ComplexMoniker and setting its CMI_iconBitmap field to CMB_CONTACT_LIST.

Putting this together, we end up with the following:

@object ContactListClass MyContactList = {
  GI_visMoniker = "I want to talk to...";
  GCI_output = (TO_PROCESS);
  ATTR_CONTACT_LIST_CALL_TYPE = CCT_SMS;
  ATTR_GEN_CONTROL_REQUIRE_UI = CLF_SEARCH |
                       CLF_SELECT_CONTACT_NUMBER ; 
  HINT_EXPAND_HEIGHT_TO_FIT_PARENT;
  ATTR_CONTACT_LIST_NOTIFY_CONTACT_SELECTED_MSG = 
                        MSG_MYPROCESS_SEND_MESSAGE ;
}

With this configuration, the ContactList will send a MSG_MYPROCESS_SEND_MESSAGE message to your process object when the user chooses a contact. A sample handler for this message is shown below (Handling the ContactList's "Selected" Message). The message will conform to the prototype:

@prototype void
    CONTACT_LIST_NOTIFY_CONTACT_SELECTED_MSG(
                                   dword recordID,
                                   word fieldID);

The message handler should carry out the following steps:

Get the current Contact database's handle. To do this, call ContactGetDBHandle(). This routine takes no arguments, and returns the Contact database's handle.
Get the handle of the record by calling FoamDBGetRecordFromID(). This routine takes the Contact's database handle and the record's RecordID value. It allocates a block of memory to hold the record's data and returns the record's handle.
To extract the contact's GSM phone number, call FoamDBGetFieldData(). Pass the database handle, the record handle, the FieldID associated with the GSM number field (this number is supplied by the ContactList when it sends this message), 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.
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.
Now that you're done with the database, release its handle by calling ContactReleaseDBHandle().

The example below shows a way of carrying out the above set of steps.

Code Display Handling the ContactList's "Selected" Message

@class MyProcessClass, GenProcessClass;
	@message (CONTACT_LIST_NOTIFY_CONTACT_SELECTED_MSG)
						MSG_MYPROCESS_SEND_MESSAGE;
@endc

@method MyProcessClass, MSG_MYPROCESS_SEND_MESSAGE {
	TCHAR           theNumber[31];
	TCHAR           theName[MAX_NAME_DATA_LEN+1];
	word            numLen;
	VMFileHandle    CDBHandle;
	MemHandle       theRecord;

		/* Get the Contact database's handle */
	CDBHandle = ContactGetDBHandle();

		/* Get the handle to the record we're interested in */
	theRecord = FoamDBGetRecordFromID( CDBHandle, recordID );

		/* Get the GSM phone number string; null-terminate it. */
	FoamDBGetFieldData( CDBHandle, theRecord, fieldID, theNumber, 30);
	theNumber[numLen] = `\000'; /* add null terminator */

		/* We'll copy the name to theName buffer. */
	ContactGetName(theRecord, theName);

		/* If you need more information about the contact 
		 * (e.g., business name, job title), this is a good place 
		 * to retrieve it. */

	/* Do what you like with theNumber and theName */

		/* We're done with this record. */
	FoamDBDiscardRecord(CDBHandle, theRecord );

		/* We're done with the database. */
	ContactReleaseDBHandle();
}

Multiple-Selection ContactLists and Groups

Remembering the Search

Detecting Unknown Phone Numbers

Alternate Selection Messages

GEOS SDK TechDocs|

Contacts | Next:

2 Choosing Contacts From a Log