IpcGetTemplateList function
Returns official rights policy templates.
Note
Templates are available beginning with Windows Server 2003 with Service Pack 2 (SP2).
Syntax
HRESULT WINAPI IpcGetTemplateList(
_In_opt_ PCIPC_CONNECTION_INFO pConnectionInfo,
DWORD dwFlags,
LCID lcid,
_In_opt_ PCIPC_PROMPT_CTX pContext,
_Reserved_ LPVOID pvReserved,
_Out_ PCIPC_TIL *ppcTil
);
Parameters
-
pConnectionInfo [in, optional]
-
Optional AD RMS server information from which to get templates. For more information, see IPC_CONNECTION_INFO.
-
dwFlags
-
Specifies optional behavior for this function. For a list of optional flags, Get Template List Flags.
-
lcid
-
The locale ID (LCID) to use for template names and descriptions.
When passing a nonzero value as the lcid, only information from templates that have a name and description for that lcid will be retrieved.
When zero is passed as the lcid, the RMS SDK 2.1 infrastructure follows a particular process, described in the Frequently asked questions section of the Release notes topic, to select a locale to use. For more information, see Release notes.
For more information about language IDs, see Locale Identifiers.
-
pContext [in, optional]
-
An optional pointer to an IPC_PROMPT_CTX structure. This can be used in cases where authentication prompts are not desired or when an application wants to control the modal behavior of any prompt dialog boxes.
-
pvReserved
-
This parameter is reserved for future use and must be set to NULL.
-
ppcTil [out]
-
A pointer to a variable that receives a pointer to the buffer that contains the Template Information List. For more information, see IPC_TIL.
Note
The buffer is allocated by the RMS SDK 2.1 and must be freed by calling 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_NEEDS_ONLINE
-
Meaning: 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: The 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_LOCALE_NOT_FOUND
-
Meaning: The application specified a nonzero lcid, but no templates were available that had a descriptor in this locale.
Action: For more information about lcid see, the description of IPC_LI_DESCRIPTOR in License Property Types. Also see the Frequently asked questions section of the Release notes topic.
Remarks
Note
Templates are available starting with Windows Server 2003 with SP2.
Typical application behavior:
- When displaying template selection UI, it typically displays both IPC_TEMPLATE_INFO::wszIssuerDisplayName and IPC_TEMPLATE_INFO::wszName for each available template.
- Extract IPC_TEMPLATE_INFO::wszID from the IPC_TEMPLATE_INFO selected by the user.
- Pass the extracted wszID to IpcSerializeLicense to generate a Rights Management Services (RMS) license.
All templates returned are sorted based on the issuer name in the IPC_TEMPLATE_INFO structure. Downloaded templates are cached locally and are not downloaded again on successive calls unless the cache is expired. To modify this behavior, set dwFlags to IPC_GTL_FLAG_FORCE_DOWNLOAD. For more information, see Get Template List Flags.
Because template updates can occur in the background, in general, applications should call IpcGetTemplateList immediately before presenting the templates to the user.
IpcGetTemplateList 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 IpcGetTemplateList function in silent mode by using the IPC_PROMPT_FLAG_SILENT flag on with the IPC_PROMPT_CTX structure.
Requirements
| Minimum supported client |
Windows Vista with SP2 |
| Minimum supported server |
Windows Server 2008 |
| Header |
|
| Library |
|
| DLL |
|