FONCTION DRMAcquireLicense (msdrm.h)

Article
08/24/2023

[Le SDK AD RMS tirant parti des fonctionnalités exposées par le client dans Msdrm.dll est disponible dans Windows Server 2008, Windows Vista, Windows Server 2008 R2, Windows 7, Windows Server 2012 et Windows 8. Il sera peut-être modifié ou indisponible dans les versions ultérieures. Utilisez plutôt active Directory Rights Management Services SDK 2.1, qui tire parti des fonctionnalités exposées par le client dans Msipc.dll.]

La fonction DRMAcquireLicense tente d’acquérir une licence d’utilisateur final ou un certificat de licence client de manière asynchrone.

Syntaxe

DRMEXPORT HRESULT UDAPICALL DRMAcquireLicense(
  [in] DRMHSESSION hSession,
  [in] UINT        uFlags,
  [in] PWSTR       wszGroupIdentityCredential,
  [in] PWSTR       wszRequestedRights,
  [in] PWSTR       wszCustomData,
  [in] PWSTR       wszURL,
  [in] VOID        *pvContext
);

Paramètres

[in] hSession

Handle pour une session de stockage client ou de licence.

Un handle de session client est obtenu à l’aide de la fonction DRMCreateClientSession . Dans ce cas, un certificat de licence client est acquis. La fonction de rappel d’application spécifiée dans la fonction DRMCreateClientSession est appelée avec le message DRM_MSG_ACQUIRE_CLIENTLICENSOR pour fournir des commentaires status.

Un handle de session de stockage de licence est obtenu en appelant la fonction DRMCreateLicenseStorageSession . Dans ce cas, une licence d’utilisateur final est acquise. La fonction de rappel d’application spécifiée dans la session cliente passée dans le paramètre hClient de la fonction DRMCreateLicenseStorageSession sera appelée avec le message DRM_MSG_ACQUIRE_LICENSE pour fournir status commentaires.

[in] uFlags

Spécifie les options de l’appel de fonction. Ce paramètre peut être zéro ou une combinaison d’un ou plusieurs des indicateurs suivants.

DRM_AL_NONSILENT ()

L’acquisition de licence nonilent n’est pas prise en charge. DRMAcquireLicense retourne E_INVALIDARG si cet indicateur est défini.

Pour le client RMS (Rights Management Services) 1.0, achetez la licence de manière nonilente. La valeur par défaut est l’acquisition de licence sans assistance.

DRM_AL_NOPERSIST ()

Stockez la licence uniquement dans le magasin de licences temporaire (en mémoire). La valeur par défaut consiste à stocker la licence dans le magasin de licences permanent.

DRM_AL_CANCEL ()

Annulez la requête précédente.

DRM_AL_FETCHNOADVISORY ()

N’achetez pas les listes de révocation requises par la licence. L’action par défaut consiste à acquérir toutes les listes de révocation requises par une licence retournée. Toutefois, toutes les listes de révocation doivent toujours être inscrites à l’aide de la fonction DRMRegisterRevocationList .

DRM_AL_NOUI ()

Cet indicateur supprime la boîte de dialogue d’authentification réseau Windows. Si la demande de licence est refusée car l’utilisateur n’a pas d’autorisation, cet indicateur empêche l’affichage de la boîte de dialogue d’authentification réseau. Cela est utile lorsque vous tentez de gérer l’acquisition de licences sur un thread d’interface non utilisateur ou en arrière-plan, car vous pouvez éviter les boîtes de dialogue potentiellement confuses. Si l’authentification échoue et que cet indicateur est spécifié, le rappel associé à la demande reçoit immédiatement une erreur de E_DRM_LICENSEACQUISITIONFAILED.

Si hSession est un handle de session client, cet indicateur est ignoré.

[in] wszGroupIdentityCredential

Un certificat de compte de droits facultatifs (RAC). Si elle n’est pas utilisée, cette fonction case activée le magasin de licences d’un RAC qui correspond à la licence utilisée pour créer hSession. Si aucune n’est trouvée, cette fonction échoue.

[in] wszRequestedRights

Ce paramètre est réservé et doit être NULL.

[in] wszCustomData

Données facultatives spécifiques à l’application qui peuvent être requises pour une licence. Il doit s’agir d’une chaîne XML valide. Après avoir retourné le contrôle à l’appelant, cette fonction crée une demande de licence à l’aide des données spécifiques à l’application spécifiées ici.

[in] wszURL

URL d’acquisition de licence. Ce paramètre est requis lorsqu’un certificat de licence client est en cours d’acquisition et facultatif lorsqu’une licence d’utilisateur final est en cours d’acquisition. L’URL peut être utilisée pour l’acquisition de licences silencieuses et nonilents. Lorsqu’elle est présente, cette URL remplace l’URL spécifiée dans la licence qui a été utilisée pour créer la session de stockage de licence passée dans hSession.

Une licence peut contenir plusieurs URL d’acquisition de licence, mais seule la première est utilisée par défaut. Pour utiliser l’une des autres URL spécifiées, vous devez analyser la licence. Pour plus d'informations, consultez la section Notes.

[in] pvContext

Valeur 32 bits définie par l’application qui est envoyée dans le paramètre pvContext de la fonction de rappel. Cette valeur peut être un pointeur vers des données, un pointeur vers un handle d’événement ou tout autre élément pour lequel la fonction de rappel personnalisée est conçue pour gérer. Pour plus d’informations, consultez Prototype de rappel.

Valeur retournée

Si la fonction réussit, la fonction retourne S_OK.

Si la fonction échoue, elle retourne une valeur HRESULT qui indique l’erreur. Les valeurs possibles incluent, sans s’y limiter, celles de la liste suivante. Pour obtenir la liste des codes d’erreur courants, consultez Valeurs HRESULT courantes.

Remarques

Cette fonction est utilisée pour récupérer une licence d’utilisateur final ou un certificat de licence client de manière asynchrone. Il n’existe aucune version synchrone de cette fonction. Pour annuler une demande de licence en cours, appelez à nouveau DRMAcquireLicense avec DRM_AL_CANCEL spécifiée dans uFlags. La progression de cette fonction et toutes les données retournées sont retournées à la fonction de rappel (voir Création d’une fonction de rappel).

Si la licence de l’utilisateur final récupérée nécessite des listes de révocation, celles-ci sont acquises en même temps, sauf si DRM_AL_FETCHNOADVISORY est spécifié dans uFlags. Un échec de récupération des listes de révocation requises est indiqué par E_DRM_NO_CONNECT. L’application doit inscrire toutes les listes récupérées à l’aide de DRMRegisterRevocationList.

Cette fonction peut se produire en mode silencieux ou non.

Note L’acquisition de licence nonilent est prise en charge uniquement dans le client RMS 1.0. À compter du client RMS 1.0 SP1, l’acquisition de licences noniles n’est plus prise en charge et MSDRMCtrl.dll n’est pas expédié.

Dans l’acquisition de licence nonilent, une URL d’acquisition de licence est retournée à la fonction de rappel dans une structure de DRM_LICENSE_ACQ_DATA . L’application ouvre ensuite un navigateur web qui est dirigé vers une URL qui spécifie une page HTML qui contient le contrôle ActiveX dans MSDRMCtrl.dll. La page est utilisée pour obtenir des informations supplémentaires, telles qu’un numéro de crédit carte, puis appelle la fonction AcquireLicense du contrôle ActiveX, ce qui entraîne le déroulement normal de l’acquisition de la licence. La licence ne peut être retournée qu’au magasin de licences permanent.

Dans l’acquisition de licence sans assistance, aucune page web n’a besoin d’être ouverte, et la progression de l’acquisition de licence est notée dans la fonction de rappel de l’application.

La licence récupérée est ajoutée au magasin de licences temporaire ou permanente, selon que DRM_AL_NOPERSIST est spécifié ou non. Dans l’acquisition de licence nonilent, la licence acquise ne peut pas être ajoutée au magasin de licences temporaire, uniquement au magasin de licences permanent, où elle doit être récupérée à l’aide de DRMEnumerateLicense. La liste suivante décrit les combinaisons possibles du type d’acquisition de licence avec le type de magasin de licences.

Magasin de licences	Acquisition silencieuse	Acquisition nonilente
Temporaire	DRM_AL_NOPERSIST	Impossible
Permanent	Aucun indicateur	DRM_AL_NONSILENT

Note Bien que la licence d’émission soit signée et protégée par chiffrement, il serait possible pour un éditeur malveillant d’inclure l’URL d’un site web malveillant ; il n’existe aucun moyen de vérifier à l’avance la nature de cette URL.

AD RMS permet à un administrateur de spécifier une URL de licence extranet en plus d’une URL interne (intranet). Chaque URL est copiée dans la licence sous un nœud DISTRIBUTIONPOINT> distinct <avec l’URL interne qui apparaît en premier. Ceci est illustré par l’exemple suivant.


      <DISTRIBUTIONPOINT>
      - <OBJECT type="License-Acquisition-URL">
          <ID type="MS-GUID">
            {0F45FD50-383B-43EE-90A4-ED013CD0CFE5}
          </ID> 
          <NAME>DRM Server Cluster</NAME> 
          <ADDRESS type="URL">
            https://corprights/_wmcs/licensing
          </ADDRESS> 
        </OBJECT>
      </DISTRIBUTIONPOINT>
      <DISTRIBUTIONPOINT>
      - <OBJECT type="Extranet-License-Acquisition-URL">
          <ID type="MS-GUID">
            {94BF969A-CA04-44d6-AA96-51071281FAG2}
          </ID> 
          <NAME>DRM Server Cluster</NAME> 
          <ADDRESS type="URL">
            https://corprights.example.com/_wmcs/licensing
          </ADDRESS> 
        </OBJECT>
      </DISTRIBUTIONPOINT>

Plusieurs URL sont souvent spécifiées afin que les utilisateurs puissent accéder au contenu protégé à la fois au travail et à la maison. La deuxième URL fournit un point d’acquisition de licence qui n’oblige pas l’utilisateur travaillant à domicile à se connecter au réseau d’entreprise. Toutefois, la fonction DRMAcquireLicense utilise la première URL par défaut. Par conséquent, pour permettre au consommateur d’utiliser une AUTRE URL, votre application doit analyser la licence.

Configuration requise

Condition requise	Valeur
Plateforme cible	Windows
En-tête	msdrm.h
Bibliothèque	Msdrm.lib
DLL	Msdrm.dll

Voir aussi

Fonctions AD RMS

Partager via