Share via


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

See also

IPC_CONNECTION_INFO

IPC_PROMPT_CTX

IPC_TEMPLATE_INFO

IPC_TIL

IpcFreeMemory

IpcGetTemplateIssuerList

Get Template List Flags

IpcSerializeLicense

License Property Types

Locale Identifiers

Error codes

Release notes