IpcGetKey function
Returns a handle to a key object created from a serialized license.
Syntax
HRESULT WINAPI IpcGetKey(
_In_ PCIPC_BUFFER pvLicense,
DWORD dwFlags,
_In_opt_ PCIPC_PROMPT_CTX pContext,
_Reserved_ LPVOID pvReserved,
_Out_ PIPC_KEY_HANDLE phKey
);
Parameters
-
pvLicense [in]
-
The serialized license for which the key is to be created. For more information, see IPC_BUFFER.
-
dwFlags
-
Must be 0.
-
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.
-
pvReserved
-
Reserved for future use. Must be NULL.
-
phKey [out]
-
A pointer to a variable that receives a handle to the key object created by this function.
Note
This key handle should be closed with IpcCloseHandle when no longer needed.
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_NEEDS_ONLINE
-
RMS SDK 2.1 needs network access to complete the operation, but the application requested offline mode.
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
-
RMS SDK 2.1 needs to display a window to complete the operation, but the application requested silent mode.
Call the function again, without specifying the IPC_PROMPT_FLAG_SILENT flag.
-
IPCERROR_RIGHT_NOT_GRANTED
-
Meaning: The user does not have rights to consume the content.
Action: Communicate the process for requesting adequate rights. Referral information can be queried using IpcGetSerializedLicenseProperty with dwPropID set to IPC_LI_REFERRAL_INFO_URL.
Remarks
A key object is required for decryption, encryption, and checking granted rights. A key object is created only if the current user has access to the content that the serialized license in pvLicense is associated with. The key object is populated with the rights granted to the current user. Whether a specific right has been granted to the current user can be checked by calling IpcAccessCheck.
IpcGetKey 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 IpcGetKey function in silent mode by using the IPC_PROMPT_FLAG_SILENT flag with the IPC_PROMPT_CTX structure.
Requirements
| Minimum supported client |
Windows Vista with SP2 |
| Minimum supported server |
Windows Server 2008 |
| Header |
|
| Library |
|
| DLL |
|