IProviderAdmin::OpenProfileSection

The IProviderAdmin::OpenProfileSection method opens a profile section from the current profile and returns an IProfSect pointer for further access.

Quick Info

See IProviderAdmin : IUnknown.

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

Parameters

lpUID

[in] Pointer to the MAPIUID structure holding 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 calling from their message service entry point functions.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the profile section. Passing NULL results in the profile section's standard interface, or IProfSect, being returned.

ulFlags

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

MAPI_DEFERRED_ERRORS: Allows OpenProfileSection to return successfully, possibly before the profile section is fully accessible to the caller. If the profile section is not accessible, making a subsequent call to it can result in an error.
MAPI_MODIFY: Requests read/write access. By default, objects are opened with read-only access, and callers should not work on the assumption that read/write access has been granted. Clients are not allowed read/write access to provider sections of the profile.

lppProfSect

[out] Pointer to a pointer to the profile section.

Return Values

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, allowing the caller to read information from and possibly write information to the active profile.

Clients cannot open profile sections belonging to providers using the IProviderAdmin::OpenProfileSection method.

Multiple clients or service providers can simultaneously open a profile section with read-only access. However, when a profile section is open with read/write access, 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 access, a subsequent call to request read/write access will fail with MAPI_E_NO_ACCESS. Likewise, if a section is open with read/write access, a subsequent call to request read-only access 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 access, it returns MAPI_E_NOT_FOUND.