IpcSerializeLicense function
Serializes a license.
Serialization is the final mandatory step that is needed before the license can be used for encryption. Call this function to finalize a license. This applies to IpcEncrypt but not IpcfEncryptFile.
Syntax
HRESULT WINAPI IpcSerializeLicense(
_In_ LPCVOID pvLicenseInfo,
DWORD dwType,
DWORD dwFlags,
_In_opt_ PCIPC_PROMPT_CTX pContext,
_Out_opt_ PIPC_KEY_HANDLE phKey,
_Out_ PIPC_BUFFER *ppvLicense
);
Parameters
-
pvLicenseInfo [in]
-
A pointer to the template ID or a license handle, depending on the value of the dwType parameter. The template ID or license handle identifies the license to be serialized.
-
dwType
-
The type of data for the pvLicenseInfo parameter.
-
IPC_SL_TEMPLATE_ID (1)
-
Generate a serialized license based on a supplied Rights Management Services (RMS) Template ID. pvLicenseInfo must contain an LPCWSTR that represents the template ID. The template ID must be computed by calling IpcGetTemplateList, and extracting the wszID field from one of the returned IPC_TEMPLATE_INFO structures.
-
IPC_SL_LICENSE_HANDLE (2)
-
A license handle returned by the IpcCreateLicenseFromScratch or IpcCreateLicenseFromTemplateID function that is used to serialize the license. pvLicenseInfo is of type IPC_LICENSE_HANDLE and points to the returned handle.
dwFlags
Specifies optional behavior for this function.
IPC_SL_FLAG_DEFAULT (0)
Uses all of the default settings for IpcSerializeLicense. Most applications should use this flag when serializing a license.
IPC_SL_FLAG_KEY_NO_PERSIST (2)
Use this flag to prevent a key from being cached locally and inserted within the serialized license. If this flag is used, the content creator must contact the RMS server in order to access the content.
Note
If this flag is used, the creator of the serialized license will require a network connection to the RMS server if they attempt to create a key from it using IpcGetKey.
IPC_SL_FLAG_KEY_NO_PERSIST_DISK (4)
Use this flag to prevent the content key from being cached locally. The content key will still be cached in the serialized license.
IPC_SL_FLAG_DEPRECATED_UNSIGNED_LICENSE_TEMPLATE (8)
This flag should only be used by applications that protect content using functions of the MSDRM library. For more information, see AD RMS Functions. Passing this flag will generate an issuance license template that is compatible with MSDRM.
[!Important]
Licenses that are created with this flag cannot be used with RMS SDK 2.1. This flag cannot be combined with any other flag.
IPC_SL_FLAG_KEY_NO_PERSIST_LICENSE (16)
Use this flag to prevent an encrypted copy of this key from being cached within the serialized license. The key may still be cached locally on disk.
Note
If you are storing confidential information in the AppSpecific data field, you should specify the IPC_SL_FLAG_KEY_NO_PERSIST_LICENSE when serializing your license so your information will remain confidential.
pContext [in, optional]
An optional pointer to an IPC_PROMPT_CTX structure. This can be used in cases where authentication prompts are not desirable or when an application wants to control the modal behavior of any prompt dialogs.
phKey [out, optional]
A pointer to a variable that receives a handle to the key object corresponding to the owner license that can be used for encrypting with the serialized license.
ppvLicense [out]
A pointer to a variable that receives a pointer to the buffer that contains the serialized license. The buffer is allocated by the IPC Client and must be freed using IpcFreeMemory.
Return value
If the function succeeds the return value is S_OK. If the function fails, it returns an HRESULT value that indicates the error.
For more information, see Error codes for a description of all RMS SDK 2.1 return values.
Possible values include, but are not limited to, those in the following list.
-
IPCERROR_ISSUANCELICENSE_LENGTH_LIMIT_EXCEEDED
-
Meaning: Returns this value when the user rights list is too large and the call would have produced a serialized license that exceeds the limits put in place by the RMS system. This is a common occurrence for applications that expand groups and attempt to assign them to the license (for example, a mail client like Outlook).
Action: We recommend that your application user interface prompt the user to express the user rights list by using distribution groups instead of individual user's email addresses.
-
IPCERROR_NEEDS_ONLINE
-
Meaning: The RMS SDK 2.1 needs network access to complete the operation, but the application requested offline mode.
Action: Call the function again, without specifying the IPC_PROMPT_FLAG_OFFLINE flag. Typically, this flag is used in situations in which failure is acceptable and preferred to performing a network access. The system is already optimized to use the network only when absolutely necessary, so we do not recommend that developers use the IPC_PROMPT_FLAG_OFFLINE flag as an optimization.
-
IPCERROR_NEEDS_UI
-
Meaning: RMS SDK 2.1 needs to display a window to complete the operation, but the application requested silent mode.
Action: Call the function again, without specifying the IPC_PROMPT_FLAG_SILENT flag.
-
IPCERROR_RIGHT_NOT_GRANTED
-
Meaning: The user does not have the rights required to serialize this license.
This error can be returned in the following scenarios:
- 1. A license handle is created using either [**IpcCreateLicenseFromScratch**](ipccreatelicensefromscratch.md) or [**IpcCreateLicenseFromTemplateID**](ipccreatelicensefromtemplateid.md).
- 2. Setting the content key on a license handle created in \#1 using [**IpcSetLicenseProperty**](ipcsetlicenseproperty.md) with the **IPC\_LI\_CONTENT\_KEY**.
- 3. The user does not have **IPC\_WRITE\_RIGHTS** on the key handle used in \#2.
Action: If you serialized a license on which you had set the IPC_LI_CONTENT_KEY property, inform the user that they do not have rights to change the access policy for this content.
-
IPCERROR_USER_RIGHTS_NOT_SET
-
Meaning: The license handle specified by pvLicenseInfo does not have a user rights list specified.
Action: Add user rights to the license handle by calling IpcSetLicenseProperty with dwPropID set to IPC_LI_USER_RIGHTS_LIST. For an example of how to add user rights to a license, see the example in add explicit owner rights.
Remarks
IpcSerializeLicense may initialize COM with the COINIT_APARTMENTTHREADED flag to display user interface elements. As a result, callers who have initialized COM with the COINIT_MULTITHREADED flag must use the IpcSerializeLicense function in silent mode by using the IPC_PROMPT_FLAG_SILENT flag with the IPC_PROMPT_CTX structure.
License buffer data is encoded in UTF8 when using the default flags and UTF16 when using the IPC_LI_DEPRECATED_ENCRYPTION_ALGORITHMS flag.
If you are storing confidential information in the AppSpecific data field, you should specify the IPC_SL_FLAG_KEY_NO_PERSIST_LICENSE when serializing your license (IpcSerializeLicense) so your information will remain confidential.
Requirements
| Minimum supported client |
Windows Vista with SP2 |
| Minimum supported server |
Windows Server 2008 |
| Header |
|
| Library |
|
| DLL |
|