Delen via


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
Ipcprot.h (include Msipc.h)
Library
Msipc.lib
DLL
Msipc.dll

See also

IPC_BUFFER

IPC_PROMPT_CTX

IpcAccessCheck

IpcCloseHandle

IpcSerializeLicense

Error codes