Opening the Contacts Database

Before you can work with any address cards, you must first open the database and specify a sort order and a handle to a window. The window receives notification messages from the object store. Before you can open the database, you must create it by calling the CreateAddressBook function.

    To open the Contacts database

1. Call the OpenAddressBook function.
2. Define a sort order to be used and specify a window to receive the notification message.

   If the Boolean function returns TRUE, you can proceed to work with the opened database. The function returns FALSE if you attempt to open a non-existing database. If another Contacts database application has altered the sort order in an existing database, the function returns FALSE as well.

3. Call GetLastError to get error information. If the error value is ERROR_FILE_NOT_FOUND, the Contacts database does not exist.
4. Call the CreateAddressBook function to create the database before re-opening it.

   – Or –

   If the error value is ERROR_INVALID_PARAMETER, the database does exist, but the sort order has been altered. Call OpenAddressBook again, but without specifying a sort order.

The CreateAddressBook function can take as input a NULL array for the sort order properties. In this case, the function uses the surname, company name, office telephone number, and home telephone number properties as the default sort order parameters.

Multiple applications can open the Contacts database simultaneously. To coordinate data access and preserve data integrity, the operating system sends object-store notification messages to attached applications whenever the database is modified. The notification messages have the DB_CEOID_ prefix and are defined in the Windbase.h header file. After receiving a notification message, an application calls the RecountCards function to recalculate the number of records in the database.

The following code example illustrates how to implement opening the Contacts database. When OpenAddressBook fails because the database does not exist, CreateAddressBook is invoked to create the database before OpenAddressBook is called again. The GetPropertyDataStruct function examines address card properties to ensure that the database has not been corrupted. The sample function returns TRUE if the database was successfully opened or FALSE if it was not.

BOOL OpenUpTheAddressBook(HWND hwndParent, HHPRTAG hhSortProp)
{
   DWORD dwError;                   // Error code
   HHPRTAG propList[MAX_COLUMNS];   // Sort-order property tags
   int nColumns;                    // Number of sortable columns 
   int index;                       // Loop index

   if (!OpenAddressBook(hwndParent, hhSortProp)) {
      dwError = GetLastError();
      if (dwError == ERROR_FILE_NOT_FOUND)
      {

            if (!CreateAddressBook(NULL, 0)) 
               {
               goto InitError;
               }

            if (!OpenAddressBook(hwndParent, hhSortProp)) 
               {
               goto InitError;
               }

      } else if (dwError == ERROR_INVALID_PARAMETER) 
      { 
            if (!OpenAddressBook(hwndParent, 0)) 
               {
               goto InitError;
               }

            nColumns = MAX_COLUMNS;
            if (!GetColumnProperties(&propList, &nColumns)) 
               {
               goto InitError;
               }

            for (index = 0; index < nColumns; index++) 
               {
               if (GetPropertyDataStruct(GPDS_PROPERTY, 
                        propList[index], NULL) == GPDS_ERR) 
                     {
                     MessageBox(hwndParent, IDS_CORRUPT_DATABASE, 
                        MB_ICONEXCLAMATION | MB_OK);
                     goto InitError;
                     }
               }

            hhSortProp = propList[0];
            if (!OpenAddressBook(hwndParent, hhSortProp)) 
               {
               goto InitError;
               }
      } else 
            {
            goto InitError;
            }
   }
      return TRUE;

   InitError:
      return FALSE;
}