IMAPIStatus::SettingsDialog

The IMAPIStatus::SettingsDialog method displays a property sheet enabling the user to change a service provider's configuration.

Quick Info

See IMAPIStatus : IMAPIProp.

HRESULT SettingsDialog(
  ULONG ulUIParam,   
  ULONG ulFlags      
);
 

Parameters

ulUIParam

[in] Handle of the parent window for the configuration property sheet.

ulFlags

[in] Bitmask of flags that controls the display of the property sheet. The following flag can be set:

UI_READONLY

Suggests that the provider not enable users to change configuration properties. This flag is only a suggestion; it can be ignored.

Return Values

S_OK

The configuration property sheet was displayed successfully.

MAPI_E_NO_SUPPORT

The status object does not support this method as indicated by the absence of the STATUS_SETTINGS_DIALOG flag in the PR_RESOURCE_METHODS property.

Remarks

The IMAPIStatus::SettingsDialog method displays a configuration property sheet. MAPI recommends that all service providers support the SettingsDialog method, but it is not required. Service providers can implement their own property sheets or use the implementation supplied in the support object's IMAPISupport::DoConfigPropsheet method. DoConfigPropsheet builds a read/write property sheet.

Notes to Implementers

If a remote transport provider has any settings, it should do the following:

• Open the transport provider's profile section.
• Get the transport provider's property settings from the profile.
• Display the property settings in a dialog box.
• If the dialog box allows editing of the property settings, check that the new settings are valid and store them back in the transport provider's profile section.
• Return S_OK, or any error values returned during the preceeding steps.

Notes to Callers

You can use the property sheet displayed through SettingsDialog to perform a variety of tasks, such as:

• Specify a default message store.
• Specify a transport order.
• Specify a default address book container for browsing.
• Specify a search order for resolving ambiguous names.
• Specify a default personal address book.

Service providers can implement property sheets that are read/write, read-only, or a mixture of access modes, depending on the property. Service providers can implement different access on individual properties by setting property restrictions. The default mode for property sheets is read/write. You can request read-only displays by setting the UI_READONLY flag in your calls to SettingsDialog. Service providers that are able to honor the request can do so. However, because some service providers cannot override the default mode, you must be prepared to handle property sheets of either type.

Because a user interface is always involved in this operation, only interactive clients should call SettingsDialog.