Share via


ProtectedFileStream.AcquireAsync method

Creates a ProtectedFileStream object from a backing stream. This method is used to open a protected file. The protected file is loaded from the specified backing stream. After ProtectedFileStream object is created, apps can use ProtectedFileStream::Policy property to get the UserPolicy object that defines the policy used to protect the protected file. The resulting ProtectedFileStream can be used to read the contents of the protected file (as a regular IRandomAccessStream).

[!Warning]
To avoid data loss and/or corruption, FlushAsync must be called if you modify the created stream or before object disposal.

[!Warning]
This method must be called on a UI thread. Calling it on a worker thread may result in an unexpected behavior.

Syntax

public:
static 
      IAsyncOperation<GetProtectedFileStreamResult> AcquireAsync(
  IRandomAccessStream^ stream, 
  
      String
      userId, 
  IAuthenticationCallback^ authenticationCallback, 
  IConsentCallback^ consentCallback, 
  PolicyAcquisitionOptions options
)

Parameters

stream

Type: IRandomAccessStream

The backing stream where the protected file is loaded from.

userId

Type: String

The email address of the user that is trying to consume the protected content.

This email address will be used to determine which policy object to use from the offline cache.

If a policy object for this user is not found in the offline cache then this API will go online (if allowed) to get the policy object.

If null is passed, the first policy object found in the offline cache will be used. And again if there is no policy object found for this content in the offline cache, this API will go online to get the policy object.

This parameter is also used as a hint for userId for user authentication, i.e., it will be passed to the IAuthenticationCallback.GetTokenAsync in the AuthenticationParameters structure.

authenticationCallback

Type: IAuthenticationCallback

Authentication callback to be used for auth

consentCallback

Type: IConsentCallback

Consent callback user for user consent process

options

Type: PolicyAcquisitionOptions

Possible offline flag.

Return value

Type: IAsyncOperation(GetProtectedFileStreamResult)

The asynchronous operation. Upon completion, IAsyncOperation.GetResults returns a ProtectedFileStream object that can be used to write content to the protected file.

Remarks

[!Warning]
To avoid data loss and/or corruption, FlushAsync must be called if you modify the created stream or before object disposal.

[!Warning]
This method must be called on a UI thread. Calling it on a worker thread may result in an unexpected behavior.

Requirements

Minimum supported client
None supported
Minimum supported server
None supported
Minimum supported phone
Windows Phone 8.1
Namespace
Microsoft::Protection
Metadata
Microsoft.RightsManagement.winmd

See also

ProtectedFileStream