3.5.4.1 AcquirePreLicense

In the AcquirePreLicense operation, the requestor specifies a list of recipient email addresses and a publishing license, and the server returns a use license for each recipient.

Figure 8: AcquirePreLicense operation message sequence

 <wsdl:operation name="AcquirePreLicense">
   <wsdl:input message="tns:AcquirePreLicenseSoapIn" />
   <wsdl:output message="tns:AcquirePreLicenseSoapOut" />
 </wsdl:operation>

To perform the request validation, the server MUST validate the input parameters upon receiving an AcquirePreLicense request. The AcquirePreLicense request includes the following parameters:

For a successful request, the server SHOULD verify that each user that is specified in LicenseeIdentities can be identified and that the server is able to retrieve the user's RAC public key. If the server does not have enough information to retrieve a user's public key, the server SHOULD return an <AcquirePreLicenseException> element that contains the AcquirePreLicenseInvalidLicenseeException error in place of a use license for that user.

Once validation is complete, the server retrieves each user's RAC public key, evaluates the rights granted to the user by the IssuanceLicense, and generates a use license with a content key that is protected by the user's RAC public key. The process for generating a use license is defined in [MS-RMPR] section 3.4.4.1.

If the server encounters an error while retrieving the user's public key, the server SHOULD return an <AcquirePreLicenseException> element that contains an exception string in place of a use license for that user.

If the server encounters an error while generating a use license for a user, the server SHOULD return an <AcquirePreLicenseException> element that contains an exception string in place of a use license for that user. The server SHOULD use exceptions listed in [MS-RMPR] section 3.4.4.1 to indicate which error occurred when attempting to generate a use license for a user.

A successful AcquirePreLicense response SHOULD return a use license for each user. If an error occurred while generating a license for a user, an AcquirePreLicenseException element that contains the error message SHOULD be used in place of the use license for that user. Error messages containing exceptions other than "Microsoft.DigitalRightsManagement.Licensing.NoRightsForRequestedPrincipalException" SHOULD be treated as a human-readable error message to assist in troubleshooting unexpected errors and clients SHOULD NOT rely on specific error messages. Clients SHOULD check for the presence of the "Microsoft.DigitalRightsManagement.Licensing.NoRightsForRequestedPrincipalException" exception to determine if a user did not have permission to access the content protected by the PL. If an error affects the entire request, rather than individual users, the server SHOULD throw an exception.

Exceptions Thrown:

The AcquirePreLicense operation MUST throw either Common Fault Codes for the RMS: ISV Extension Protocol, as described in section 3.1.4.2, or the following exceptions.