Fonction DRMActivate (msdrm.h)

Article
08/24/2023

[Le Kit de développement logiciel (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 peut être modifié ou

non disponible dans les versions suivantes. 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 DRMActivate obtient un lockbox et un certificat d’ordinateur pour une machine ou un certificat de compte de droits pour un utilisateur.

Syntaxe

DRMEXPORT HRESULT UDAPICALL DRMActivate(
  [in] DRMHSESSION      hClient,
  [in] UINT             uFlags,
  [in] UINT             uLangID,
  [in] DRM_ACTSERV_INFO *pActServInfo,
  [in] VOID             *pvContext,
  [in] HWND             hParentWnd
);

Paramètres

[in] hClient

Handle d’une session cliente, créé par DRMCreateClientSession.

[in] uFlags

Spécifie le type d’activation souhaité, ainsi que les options supplémentaires ; Pour plus d’informations, consultez Remarques. Ce paramètre peut être une combinaison d’un ou plusieurs des indicateurs suivants.

DRM_ACTIVATE_MACHINE

Activez l’ordinateur. L’indicateur DRM_ACTIVATE_SILENT est également requis, mais l’indicateur DRM_ACTIVATE_GROUPIDENTITY ne doit pas être défini. Le paramètre pActServInfo est ignoré.

Chaque ordinateur est activé par utilisateur. Autrement dit, le certificat d’ordinateur est généré et stocké pour l’utilisateur actuellement connecté.

La fonction de rappel d’application spécifiée dans la fonction DRMCreateClientSession sera appelée avec le message DRM_MSG_ACTIVATE_MACHINE pour fournir l’activation de la machine status commentaires.

DRM_ACTIVATE_GROUPIDENTITY

Active un compte de droits. Cet indicateur ne peut pas être combiné avec DRM_ACTIVATE_MACHINE.

L’indicateur DRM_ACTIVATE_SILENT est requis pour RMS v1.0 SP2 et Windows Vista. L’indicateur DRM_ACTIVATE_SILENT est toutefois facultatif pour Windows Vista avec SP1 et Windows Server 2008.

La fonction de rappel d’application spécifiée dans la fonction DRMCreateClientSession sera appelée avec le message DRM_MSG_ACTIVATE_GROUPIDENTITY pour fournir l’activation du compte de droits status commentaires.

DRM_ACTIVATE_TEMPORARY

Acquérir un certificat de compte de droits temporaires (RAC). Un RAC temporaire n’est bon que pendant une courte période, mais il est stocké dans le magasin de licences permanent. Cet indicateur est ignoré dans l’activation nonilente ; Pour plus d’informations, consultez Remarques.

DRM_ACTIVATE_CANCEL

Annuler une tentative d’activation en cours.

DRM_ACTIVATE_SILENT

Activez un utilisateur sans afficher de boîte de dialogue de mot de passe Windows. Cet indicateur est requis pour DRM_ACTIVATE_MACHINE et facultatif pour DRM_ACTIVATE_GROUPIDENTITY, en fonction du système d’exploitation. Pour plus d’informations, consultez le paramètre DRM_ACTIVATE_GROUPIDENTITY .

Si cet indicateur est utilisé avec DRM_ACTIVATE_GROUPIDENTITY, le paramètre pActServInfo ne peut pas être NULL. S’il est utilisé avec DRM_ACTIVATE_MACHINE, pActServInfo est ignoré.

DRM_ACTIVATE_SHARED_GROUPIDENTITY

Cet indicateur n’est pas utilisé.

DRM_ACTIVATE_DELAYED

Activation différée de l’ordinateur. En mode d’activation en mode silencieux normal, le client reçoit un fichier CAB qui contient des fichiers d’activation qui sont développés et exécutés automatiquement. Avec cet indicateur, les fichiers sont enregistrés à un emplacement qui est passé au paramètre pvParam de la fonction de rappel, où un client peut les case activée pour les virus avant de les développer et de les exécuter.

[in] uLangID

ID de langue utilisé par l’application. Si ce paramètre est défini sur zéro, l’ID de langue par défaut de l’utilisateur connecté est utilisé.

[in] pActServInfo

Informations de serveur facultatives. Si le client n’a pas été configuré pour utiliser Services ADFS (ADFS) avec AD RMS, vous pouvez passer la valeur NULL pour utiliser le service Windows Live ID pour la découverte de service. Si le client a été configuré pour utiliser ADFS, vous devez passer l’URL de certification Windows Live. Pour plus d’informations sur la découverte de service, consultez DRMGetServiceLocation.

[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 que la fonction de rappel personnalisé est conçue pour gérer. Pour plus d’informations, consultez Prototype de rappel.

[in] hParentWnd

Handle de fenêtre parente utilisé dans l’activation de Windows Live ID nonilent (activation utilisateur uniquement). Dans l’activation nonilent, une fenêtre Windows Live ID s’ouvre pour demander des informations utilisateur. Ce paramètre permet à l’application d’affecter une fenêtre arbitraire en tant que parent de la fenêtre. Si ce paramètre a la valeur NULL, la fenêtre active est utilisée.

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

Si une application tente d’activer un utilisateur sur un ordinateur qui n’a pas encore été activé, la fonction échoue. Nous recommandons à une application d’appeler DRMIsActivated avant d’appeler cette fonction pour déterminer la status d’activation de l’ordinateur. L’activation d’une machine déjà activée remplace le verrou et le certificat d’ordinateur existants. L’activation d’un utilisateur une deuxième fois ajoute un certificat de compte de droits supplémentaires à l’ordinateur. Un utilisateur ne doit activer un ordinateur particulier qu’une seule fois, même si les mises à jour de l’architecture lockbox peuvent nécessiter le téléchargement et l’activation d’une nouvelle zone de verrouillage.

L’activation comporte plusieurs options.

Option	Description
Silencieux ou non-ilent	L’activation nonilent est la valeur par défaut. L’activation en mode silencieux est spécifiée par DRM_ACTIVATE_SILENT et est requise pour l’activation de l’ordinateur. Si l’activation silencieuse est spécifiée et que pActServInfo n’a pas la valeur NULL, la fonction crée et envoie une demande d’activation à l’URL spécifiée dans le membre wszURL de pActServInfo. Pour plus d’informations, consultez DRM_ACTSERV_INFO.
Windows ou Windows Live ID	Cela est déterminé par le type de handle client passé à hClient.
Temporaire ou permanent	Cela s’applique uniquement à un certificat de compte de droits (RAC), et non à un certificat d’ordinateur. L’activation permanente est la valeur par défaut. Temporaire est spécifié par l’indicateur DRM_ACTIVATE_TEMPORARY . Lorsque vous acquérez un rac temporaire à l’aide de l’indicateur DRM_ACTIVATE_TEMPORARY , le RAC est stocké dans le magasin de licences permanent, bien qu’il expire bientôt. La durée de validité par défaut d’un RAC temporaire est de 15 minutes, même si cela peut être modifié par l’administrateur du service AD RMS. Pour éviter d’encombrer le magasin de licences avec des RAC arrivés à expiration, vous devez supprimer un rac temporaire lors de la fin d’une session cliente.

La liste suivante décrit ce qui se passe avec les combinaisons de ces options.

Option	Temporaire	Permanent
Windows silencieux	L’activation se produit sans boîte de dialogue. L’utilisateur actuellement connecté est activé.	L’activation se produit sans boîte de dialogue. L’utilisateur actuellement connecté est activé.
Windows nonilent	Une boîte de dialogue mot de passe Windows s’affiche. L’utilisateur spécifié est activé.	Une boîte de dialogue mot de passe Windows s’affiche. L’utilisateur spécifié est activé.
Windows Live ID silencieux	Non autorisé.	Non autorisé.
Windows Live ID nonilent	Une fenêtre de connexion à Windows Live ID s’affiche. L’utilisateur spécifié est activé.	Une fenêtre de connexion à Windows Live ID s’affiche. L’utilisateur spécifié est activé.

Pendant l’exécution, DRMActivate appelle la fonction de rappel définie par l’utilisateur et définit le paramètre msgsur DRM_MSG_ACTIVATE_MACHINE ou DRM_MSG_ACTIVATE_GROUPIDENTITY. Pour plus d’informations, consultez Création d’une fonction de rappel.