Status Object Implementation

Applies to: Office 2010 | Outlook 2010 | Visual Studio

All service providers must implement a status object and furnish properties from it to the session status table. You can include one or more rows in the status table, depending on the number of resources that you control. A transport provider, for example, should create a row in the status table for each message queue it manages. When changes occur, the appropriate status table row must be updated. Status objects are implemented to provide access both to the information included in the status table and to additional information not included in the table.

To implement a status object

1. Implement the OpenStatusEntry method of your logon object. When clients want to open your status object, they call IMAPISession::OpenEntry. MAPI fulfills the open request by calling your provider's OpenStatusEntry method, causing your provider to open its status object and return to the client a pointer to its IMAPIStatus implementation. In your OpenStatusEntry implementation, complete the following steps:

   1. Perform the following tasks if your logon object has not yet created a status object:

      1. Call the support object's IMAPISupport::OpenProfileSection method to access your provider's profile section.

      2. Create a new status object.

      3. Store a reference to the profile section in your provider's status object and call the profile section's IUnknown::AddRef method to increment its reference count.

      4. Store a reference to the logon object in your provider's status object and call the logon object's IUnknown::AddRef method to increment its reference count.

      5. Store a reference to the status object in your provider's logon object.

   2. Call the status object's IUnknown::AddRef method to increment its reference count in the logon object.

   3. Set the status object's PR_OBJECT_TYPE (PidTagObjectType) property to MAPI_STATUS.

   4. Set the lppMAPIStatus output parameter to point to the status object, and return.

   5. Check the ulFlags input parameter. If it is set to MAPI_MODIFY and your provider supports read/write access to its status object, return a writeable object. However, if your provider does not support read/write access to its status object, do not fail. Return a status object that is read-only. Clients that expect to receive read/write status objects should verify that read/write permission has been granted before attempting to make any changes.

2. Set all of the required status object and status table properties. The properties that you include in your status table row should be available through your status object, except for the properties calculated by MAPI. The required properties are as follows:

   • PR_DISPLAY_NAME (PidTagDisplayName)

   • PR_PROVIDER_DLL_NAME (PidTagProviderDllName)

   • PR_PROVIDER_DISPLAY (PidTagProviderDisplay)

   • PR_RESOURCE_TYPE (PidTagResourceType)

   • PR_RESOURCE_METHODS (PidTagResourceMethods)

   • PR_RESOURCE_FLAGS (PidTagResourceFlags)

   • PR_STATUS_CODE (PidTagStatusCode)

3. Implement the IMAPIStatus : IMAPIProp methods that are appropriate for your provider. Depending on your provider, you do not need to implement all of the four methods in IMAPIStatus. Every provider should implement a read-only version of the methods of the IMAPIProp : IUnknown interface and the IMAPIStatus::ValidateState method. Transport providers should also implement IMAPIStatus::FlushQueues, and all providers should support IMAPIStatus::SettingsDialog. However, support for IMAPIStatus::ChangePassword is optional. Only service providers that require passwords and want to allow users to change them programmatically need to implement this method. For every method that you support, set the corresponding bit in the PR_RESOURCE_METHODS property. For example, if you support ValidateState and SettingsDialog only, set PR_RESOURCE_METHODS to the following:

   STATUS_VALIDATE_STATE | STATUS_SETTINGS_DIALOG

   Clients should check the value of PR_RESOURCE_METHODS before attempting to call your status object. Handle calls to any of your unsupported methods by returning MAPI_E_NO_SUPPORT.

4. Call IMAPISupport::ModifyStatusRow during logon to add your row or rows to the status table. Pass a property value array that contains the column information for the row and 0 for the ulFlags parameter. If at some point later in the session your provider's status changes and it becomes necessary to update the column information, call ModifyStatusRow again with the STATUSROW_UPDATE flag set.

For more information about status objects, see MAPI Status Objects.

See Also

Concepts

MAPI Service Providers