DRMEnumerateLicense 函数 (msdrm.h)

[AD RMS SDK 利用由公开的功能

Msdrm.dll 中的客户端可用于 Windows Server 2008、Windows Vista、Windows Server 2008 R2、Windows 7、Windows Server 2012 和 Windows 8。它可能被更改，或者

在后续版本中不可用。请改用 Active Directory Rights Management Services SDK 2.1，

它利用客户端在 Msipc.dll.] 中公开的功能。

DRMEnumerateLicense 函数枚举有效的许可证、计算机证书或权限帐户证书、当前用户的吊销列表或颁发许可证模板。

语法

DRMEXPORT HRESULT UDAPICALL DRMEnumerateLicense(
  [in]      DRMHSESSION hSession,
  [in]      UINT        uFlags,
  [in]      UINT        uIndex,
  [in, out] BOOL        *pfSharedFlag,
  [in, out] UINT        *puCertificateDataLen,
  [out]     PWSTR       wszCertificateData
);

参数

[in] hSession

客户端或许可证存储会话的句柄。传递到 hSession 的会话类型取决于要枚举的项的类型。若要枚举最终用户许可证，请使用使用 DRMCreateLicenseStorageSession 函数创建的许可证存储会话。若要枚举计算机证书、权限帐户证书、客户端许可方证书或颁发许可证模板，请使用使用 DRMCreateClientSession 函数创建的客户端会话。使用任一类型的句柄来枚举吊销列表。

[in] uFlags

包含以下一个或多个值，这些值指定要枚举的项类型和其他选项。

以下标志可以与其他标志结合使用，以指定其他枚举选项。

DRM_EL_EXPIRED

将此值与用于枚举标识符（如 DRM_EL_GROUPIDENTITY_LID）的标志结合使用，以枚举指定类型的过期项。这简化了从许可证存储中删除过期项，使存储保持较小并提高性能。

以下标志用于枚举最终用户许可证。

DRM_EL_EUL

枚举当前许可证存储会话的最终用户许可证。

DRM_EL_EUL_LID

枚举当前许可证存储会话的最终用户许可证标识符。每个 最终用户许可证 的标识符在 wszCertificateData 参数中返回。

以下标志用于枚举客户端许可方证书。这些标志允许应用程序通过许可方枚举当前用户可用的许可证。

DRM_EL_CLIENTLICENSOR

枚举证书存储中的所有客户端许可方证书。

DRM_EL_CLIENTLICENSOR_LID

枚举传入的客户端会话的客户端许可方证书标识符。客户端许可方证书标识符在 wszCertificateData 参数中返回。

DRM_EL_SPECIFIED_CLIENTLICENSOR

返回与客户端会话中的电子邮件地址对应的客户端许可方证书。

以下标志用于枚举计算机证书。

DRM_EL_MACHINE

枚举所选计算机证书。

每个用户都有两个计算机证书。计算机证书的有效索引值为零或一。

注意由于启用加密模式 2 的更新，DRMActivate (计算机) 会将两个计算机证书写入存储。除非应用程序直接调用 RMS 服务器上的认证 Web 方法，否则调用应用程序不需要区分这两个计算机证书：将使用与服务器加密模式对应的计算机证书。

有关详细信息，请参阅 WINDOWS 7 或 Windows Server 2008 R2 中 AD RMS 的 RSA 密钥长度增加到 2048 位。

如果 hSession 是通过调用 DRMCreateClientSession 创建的，则返回的证书来自每用户证书存储， pfSharedFlag 指向的值设置为 FALSE。如果 hSession 是通过调用 DRMCreateLicenseStorageSession 创建的，则 pfSharedFlag 指向的值是其原始值。

Windows Server 2008 R2、Windows 7、Windows Server 2008 SP2、Windows Vista SP2 或 Rights Management Services 1.0： 对于 Rights Management Services 1.0，检索到的证书来自计算机存储， pfSharedFlag 指向的值设置为 TRUE; uIndex 必须设置为零。

在指定此标志之前，必须激活计算机。如果未激活计算机，函数将返回 E_DRM_NEEDS_MACHINE_ACTIVATION。

以下标志用于枚举权限帐户证书。

DRM_EL_GROUPIDENTITY

枚举当前登录用户的权限帐户证书。这包括共享用户和受限用户。

DRM_EL_GROUPIDENTITY_LID

枚举当前登录用户的权限帐户证书标识符。这包括共享用户和受限用户。 权限帐户证书标识符将在 wszCertificateData 参数中返回。

DRM_EL_GROUPIDENTITY_NAME

枚举当前用户的权限帐户名称。

DRM_EL_SPECIFIED_GROUPIDENTITY

使用 DRMCreateClientSession 函数创建客户端会话时，返回指定用户的权限帐户证书。

以下标志用于枚举吊销列表。

所有证书都可以包含吊销列表，因此可以将客户端或许可证存储会话传递给此函数。传入的客户端会话句柄将检索权限帐户证书或客户端许可方证书的吊销列表。传入的许可证存储会话句柄将检索最终用户许可证的吊销列表。

DRM_EL_REVOCATIONLIST

枚举吊销列表。

DRM_EL_REVOCATIONLIST_LID

枚举吊销列表标识符。吊销列表标识符将在 wszCertificateData 参数中返回。

以下标志可用于检索颁发者的显示名称。

DRM_EL_ISSUERNAME

此标志不能与 DRM_EL_EXPIRED 标志一起使用，并且必须与以下标志之一一一起使用：

DRM_EL_CLIENTLICENSOR
DRM_EL_GROUPIDENTITY
DRM_EL_SPECIFIED_CLIENTLICENSOR
DRM_EL_SPECIFIED_GROUPIDENTITY

以下标志可用于枚举模板。

DRM_EL_ISSUANCELICENSE_TEMPLATE

枚举颁发许可证模板。此标志从 Windows Vista SP1 和 Windows Server 2008 开始可用。

DRM_EL_ISSUANCELICENSE_TEMPLATE_LID

枚举颁发许可证模板标识符 (GUID) 。此标志从 Windows Vista SP1 和 Windows Server 2008 开始可用。

[in] uIndex

要检索的证书或许可证的索引号。若要开始枚举，请为此参数传入零。若要获取后续许可证，请递增此值，直到函数返回 E_DRM_NO_MORE_DATA。有关详细信息，请参阅“备注”。

[in, out] pfSharedFlag

指向 BOOL 值的指针，如果检索到的许可证已共享，则接收 1 (1) ;如果检索到的许可证不共享，则接收 0 (0) 。

[in, out] puCertificateDataLen

指向 UINT 值的指针，该值在输入时包含 wszCertificateData 缓冲区的大小。此大小包括终止 null 字符。函数返回后，此值包含复制到缓冲区的字符数，包括终止 null 字符。

若要获取缓冲区的必要大小，请为 wszCertificateData 传递 NULL。所需的字符数（包括终止 null 字符）将放在此值中。

[out] wszCertificateData

指向以 null 结尾的 Unicode 字符串的指针，该字符串根据设置的标志接收许可证、ID 或模板。

若要获取此缓冲区的必要大小，请为 wszCertificateData 传递 NULL。所需的字符数（包括终止 null 字符）将放在 puCertificateDataLen 中。

返回值

如果函数成功，该函数将返回S_OK。

如果函数失败，它将返回指示错误的 HRESULT 值。可能的值包括但不限于以下列表中的值。有关常见错误代码的列表，请参阅常见 HRESULT 值。

注解

默认情况下，此函数仅枚举通过比较每个许可证中的 VALIDITYTIME 元素与会话对象的创建时间确定的未过期许可证。若要在枚举中包含过期的许可证，请将 uFlags 参数与 DRM_EL_EXPIRED合并。

此外，如果许可证的 ISSUEDPRINCIPALS 元素中的 ID 元素与与会话对象关联的用户 ID 不匹配，或者会话用户 ID 与已登录用户的 ID 不匹配，则此函数将失败。有关详细信息，请参阅 DRMCreateClientSession。

以下部分讨论如何枚举各种类型的许可证。循环访问集合时，可以通过手动分析 XrML 字符串来检查检索的每个许可证，或者在某些情况下，通过绑定到许可证并使用 DRMGetBoundLicense* 函数来检查检索到的每个许可证。

执行以下步骤以枚举最终用户许可证：

调用 DRMCreateLicenseStorageSession，传入已签名的颁发许可证。
将 uIndex 参数设置为零，将 uFlags 参数设置为 DRM_EL_EUL 并调用 DRMEnumerateLicense。 AD RMS 客户端检索其内容 ID 与用于创建许可证存储会话的颁发许可证的内容 ID 匹配的第一个有效 EUL。但是，如果发布许可证使用相同的内容 ID 但不同的权限重新发布，则返回的 EUL 可能不是所寻求的内容。如果不是，则递增 uIndex 参数并再次调用 DRMEnumerateLicense 。可以继续迭代，直到找到正确的 EUL 或函数返回 E_DRM_NO_MORE_DATA。

执行以下步骤来枚举计算机证书：

调用 DRMCreateClientSession 或 DRMCreateLicenseStorageSession 以创建会话对象。创建的会话类型决定了 pfSharedFlag 参数中返回的值的性质。有关详细信息，请参阅 uFlags 参数中的 DRM_EL_MACHINE 常量。
将 uIndex 参数设置为零或 1，将 uFlags 参数设置为 DRM_EL_MACHINE 并调用 DRMEnumerateLicense。

执行以下步骤， (NIC) 枚举权限帐户证书：

调用 DRMCreateClientSession 以创建客户端会话。
将 uIndex 参数设置为零，将 uFlags 参数设置为 DRM_EL_GROUPIDENTITY 并调用 DRMEnumerateLicense。
检查返回的 RAC。如果不是所寻求的，请递增 uIndex 并再次调用 DRMEnumerateLicense 。可以继续迭代，直到找到正确的 RAC 或函数返回 E_DRM_NO_MORE_DATA。

执行以下步骤， (CLC) 枚举客户端许可方证书：

调用 DRMCreateClientSession 以创建客户端会话。
将 uIndex 参数设置为零，将 uFlags 参数设置为 DRM_EL_CLIENTLICENSOR 并调用 DRMEnumerateLicense。
检查返回的 CLC。如果不是所寻求的，请递增 uIndex 并再次调用 DRMEnumerateLicense 。可以继续迭代，直到找到正确的 CLC 或函数返回 E_DRM_NO_MORE_DATA。

执行以下步骤以枚举颁发许可证模板：

调用 DRMCreateClientSession 以创建客户端会话。
将 uIndex 参数设置为零，将 uFlags 参数设置为 DRM_EL_ISSUANCELICENSE_TEMPLATE 并调用 DRMEnumerateLicense。
检查模板。如果不是所寻求的，请递增 uIndex 并再次调用 DRMEnumerateLicense 。可以继续迭代，直到找到正确的模板或函数返回 E_DRM_NO_MORE_DATA。

执行以下步骤以枚举吊销列表：

调用 DRMCreateClientSession 或 DRMCreateLicenseStorageSession 以创建会话对象。使用客户端会话句柄检索权限帐户或客户端许可方证书的吊销列表。使用许可证存储会话句柄检索最终用户许可证的吊销列表。
将 uIndex 参数设置为零，将 uFlags 参数设置为 DRM_EL_REVOCATIONLIST 并调用 DRMEnumerateLicense。
如果吊销列表不是所寻求的列表，请递增 uIndex 并再次调用 DRMEnumerateLicense 。可以继续迭代，直到找到正确的列表或函数返回 E_DRM_NO_MORE_DATA。

必须调用 DRMEnumerateLicense 两次才能检索一个许可证。在第一次调用时，将 wszCertificateData 设置为 NULL 以检索所需的缓冲区大小。分配内存并再次调用 DRMEnumerateLicense 。以下示例对此进行了说明。

// Call DRMEnumerateLicense with the wszCertificateData parameter set
// to NULL.
hr = DRMEnumerateLicense( 
         hClient,                          // Client session handle
         DRM_EL_SPECIFIED_CLIENTLICENSOR,  // Flags
         0,                                // Index
         &fShared,                         // Shared license
         &uiClientLicensorCertLength,      // Certificate length
         NULL                              // Certificate
         );

if ( FAILED( hr ) && ( E_DRM_NO_MORE_DATA != hr ) )
{
   goto e_Exit;
}

// There are no client licensor certificates. Acquire one.
else if ( E_DRM_NO_MORE_DATA == hr )
{
    // TODO: Acquire a client licensor certificate.
}

// A client licensor certificate was found. Allocate memory and
// call DRMEnumerateLicense again.
else
{

   wszClientLicensorCert = new WCHAR[ uiClientLicensorCertLength ];
   if ( NULL == wszClientLicensorCert )
   {
      hr = E_OUTOFMEMORY;
      goto e_Exit;
   }

   hr = DRMEnumerateLicense( 
         hClient,                          // Client session handle
         DRM_EL_SPECIFIED_CLIENTLICENSOR,  // Flags
         0,                                // Index
         &fShared,                         // Shared license
         &uiClientLicensorCertLength,      // Certificate length
         wszClientLicensorCert             // Certificate
         );

   if ( FAILED( hr ) )
   {
      goto e_Exit;
   }
}

e_Exit:

    if ( NULL != hClient )
    {
        hr = DRMCloseSession( hClient );
    }

    if ( NULL != wszUserId )
    {
        delete [] wszUserId;
    }


    if ( NULL != wszLicensingSvr )
    {
        delete [] wszLicensingSvr;
    }

    if ( NULL != wszClientLicensorCert )
    {
        delete [] wszClientLicensorCert;
    }

    return hr;

要求

要求	值
目标平台	Windows
标头	msdrm.h
Library	Msdrm.lib
DLL	Msdrm.dll

另请参阅

AD RMS 函数

OfflineSigning_GetCertificate.cpp

反馈

此页面是否有帮助？

Last updated on 2023-08-24