Share via


IProviderAdmin::OpenProfileSection

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Opens a profile section from the current profile and returns an IProfSect pointer for further access.

HRESULT OpenProfileSection(
  LPMAPIUID lpUID,
  LPCIID lpInterface,
  ULONG ulFlags,
  LPPROFSECT FAR * lppProfSect
);

Parameters

  • lpUID
    [in] A pointer to the MAPIUID structure that contains the unique identifier for the profile section to be opened. Clients must not pass NULL for the lpUID parameter. Service providers can pass NULL to retrieve the MAPIUID when they call from their message service entry point functions.

  • lpInterface
    [in] A pointer to the interface identifier (IID) that represents the interface to be used to access the profile section. Passing NULL results in the profile section's standard interface (IProfSect) being returned.

  • ulFlags
    [in] A bitmask of flags that controls how the profile section is opened. The following flags can be set:

    • MAPI_DEFERRED_ERRORS
      Enables OpenProfileSection to return successfully, possibly before the profile section is fully available to the caller. If the profile section is not available, making a subsequent call to it can raise an error.

    • MAPI_MODIFY
      Requests read/write permission. By default, objects are opened with read-only permission, and callers should not work on the assumption that read/write permission has been granted. Clients are not allowed read/write permission to provider sections of the profile.

  • MAPI_FORCE_ACCESS
    Allows access to all profile sections, even those owned by individual service providers.

  • lppProfSect
    [out] A pointer to a pointer to the profile section.

Return Value

  • S_OK
    The profile section was successfully opened.

  • MAPI_E_NO_ACCESS
    An attempt was made to modify a read-only profile section or to access an object for which the user has insufficient permissions.

  • MAPI_E_NOT_FOUND
    The requested profile section does not exist.

Remarks

The IProviderAdmin::OpenProfileSection method opens a profile section, enabling the caller to read information from and possibly write information to the active profile.

Clients cannot open profile sections that belong to providers by using the OpenProfileSection method.

Multiple clients or service providers can simultaneously open a profile section with read-only permission. However, when a profile section is open with read/write permission, no other calls can be made to open the section, regardless of the type of access. If a profile section is open with read-only permission, a subsequent call to request read/write permission will fail with MAPI_E_NO_ACCESS. Likewise, if a section is open with read/write permission, a subsequent call to request read-only permission will also fail.

Notes to Callers

If you request that OpenProfileSection open a nonexistent profile section by passing MAPI_MODIFY in ulFlags and an unknown MAPIUID in lpUID, the profile section will be created.

If you request that OpenProfileSection open a nonexistent section with read-only permission, it returns MAPI_E_NOT_FOUND.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File

Function

Comment

MAPIProfileFunctions.cpp

OpenProfileSection

MFCMAPI uses the IProviderAdmin::OpenProfileSection method to open a profile section from the current profile.

See Also

Reference

IMAPIProp : IUnknown

IProfSect : IMAPIProp

MAPIUID

IProviderAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample