Partager via

Énumération CLSCTX (wtypesbase.h)

  • Article

Valeurs utilisées dans les appels d’activation pour indiquer les contextes d’exécution dans lesquels un objet doit être exécuté. Ces valeurs sont également utilisées dans les appels à CoRegisterClassObject pour indiquer l’ensemble de contextes d’exécution dans lesquels un objet de classe doit être mis à disposition pour les demandes de construction d’instances.

Syntax

typedef enum tagCLSCTX {
  CLSCTX_INPROC_SERVER = 0x1,
  CLSCTX_INPROC_HANDLER = 0x2,
  CLSCTX_LOCAL_SERVER = 0x4,
  CLSCTX_INPROC_SERVER16 = 0x8,
  CLSCTX_REMOTE_SERVER = 0x10,
  CLSCTX_INPROC_HANDLER16 = 0x20,
  CLSCTX_RESERVED1 = 0x40,
  CLSCTX_RESERVED2 = 0x80,
  CLSCTX_RESERVED3 = 0x100,
  CLSCTX_RESERVED4 = 0x200,
  CLSCTX_NO_CODE_DOWNLOAD = 0x400,
  CLSCTX_RESERVED5 = 0x800,
  CLSCTX_NO_CUSTOM_MARSHAL = 0x1000,
  CLSCTX_ENABLE_CODE_DOWNLOAD = 0x2000,
  CLSCTX_NO_FAILURE_LOG = 0x4000,
  CLSCTX_DISABLE_AAA = 0x8000,
  CLSCTX_ENABLE_AAA = 0x10000,
  CLSCTX_FROM_DEFAULT_CONTEXT = 0x20000,
  CLSCTX_ACTIVATE_X86_SERVER = 0x40000,
  CLSCTX_ACTIVATE_32_BIT_SERVER,
  CLSCTX_ACTIVATE_64_BIT_SERVER = 0x80000,
  CLSCTX_ENABLE_CLOAKING = 0x100000,
  CLSCTX_APPCONTAINER = 0x400000,
  CLSCTX_ACTIVATE_AAA_AS_IU = 0x800000,
  CLSCTX_RESERVED6 = 0x1000000,
  CLSCTX_ACTIVATE_ARM32_SERVER = 0x2000000,
  CLSCTX_ALLOW_LOWER_TRUST_REGISTRATION,
  CLSCTX_PS_DLL = 0x80000000
} CLSCTX;

Constantes

 
CLSCTX_INPROC_SERVER
Valeur : 0x1
Le code qui crée et gère les objets de cette classe est une DLL qui s'exécute dans le même processus que l'appelant de la fonction spécifiant le contexte de classe.
CLSCTX_INPROC_HANDLER
Valeur : 0x2
Le code qui gère les objets de cette classe est un gestionnaire in-process. Il s’agit d’une DLL qui s’exécute dans le processus client et implémente les structures côté client de cette classe lorsque les instances de la classe sont accessibles à distance.
CLSCTX_LOCAL_SERVER
Valeur : 0x4
Le code EXE qui crée et gère les objets de cette classe s'exécute sur le même ordinateur mais il est chargé dans un espace de processus séparé.
CLSCTX_INPROC_SERVER16
Valeur : 0x8
Obsolète.
CLSCTX_REMOTE_SERVER
Valeur : 0x10
Contexte distant. Le code LocalServer32 ou LocalService qui crée et gère les objets de cette classe est exécuté sur un autre ordinateur.
CLSCTX_INPROC_HANDLER16
Valeur : 0x20
Obsolète.
CLSCTX_RESERVED1
Valeur : 0x40
Réservé.
CLSCTX_RESERVED2
Valeur : 0x80
Réservé.
CLSCTX_RESERVED3
Valeur : 0x100
Réservé.
CLSCTX_RESERVED4
Valeur : 0x200
Réservé.
CLSCTX_NO_CODE_DOWNLOAD
Valeur : 0x400
Désactive le téléchargement de code à partir du service d’annuaire ou d’Internet. Cet indicateur ne peut pas être défini en même temps que CLSCTX_ENABLE_CODE_DOWNLOAD.
CLSCTX_RESERVED5
Valeur : 0x800
Réservé.
CLSCTX_NO_CUSTOM_MARSHAL
Valeur : 0x1000
Spécifiez si vous souhaitez que l’activation échoue si elle utilise le marshaling personnalisé.
CLSCTX_ENABLE_CODE_DOWNLOAD
Valeur : 0x2000
Permet le téléchargement de code à partir du service d’annuaire ou d’Internet. Cet indicateur ne peut pas être défini en même temps que CLSCTX_NO_CODE_DOWNLOAD.
CLSCTX_NO_FAILURE_LOG
Valeur : 0x4000
Le CLSCTX_NO_FAILURE_LOG peut être utilisé pour remplacer la journalisation des échecs dans CoCreateInstanceEx.

Si ActivationFailureLoggingLevel est créé, les valeurs suivantes peuvent déterminer la status de journalisation des événements :


  • 0 = Journalisation discrétionnaire. Journaliser par défaut, mais les clients peuvent remplacer en spécifiant CLSCTX_NO_FAILURE_LOG dans CoCreateInstanceEx.

  • 1 = Consignez toujours toutes les défaillances, quelle que soit la valeur spécifiée par le client.

  • 2 = Ne journaliser jamais les échecs, quel que soit le client spécifié. Si l’entrée du Registre est manquante, la valeur par défaut est 0. Si vous devez contrôler les applications clientes, il est recommandé de définir cette valeur sur 0 et d’écrire le code client pour remplacer les échecs. Il est vivement recommandé de ne pas définir la valeur sur 2. Si la journalisation des événements est désactivée, il est plus difficile de diagnostiquer les problèmes.
CLSCTX_DISABLE_AAA
Valeur : 0x8000
Désactive les activations AAA (Activate-As-Activator) pour cette activation uniquement. Cet indicateur remplace le paramètre de l’indicateur EOAC_DISABLE_AAA de l’énumération EOLE_AUTHENTICATION_CAPABILITIES. Cet indicateur ne peut pas être défini en même temps que CLSCTX_ENABLE_AAA. Toute activation dans laquelle un processus serveur serait lancé sous l’identité de l’appelant est appelée activation en tant qu’activateur (AAA). La désactivation des activations AAA permet à une application qui s’exécute sous un compte privilégié (tel que LocalSystem) d’empêcher son identité d’être utilisée pour lancer des composants non approuvés. Les applications de bibliothèque qui utilisent des appels d’activation doivent toujours définir cet indicateur pendant ces appels. Cela permet d’empêcher l’utilisation de l’application de bibliothèque dans le cadre d’une attaque de sécurité par escalade des privilèges. Il s’agit de la seule façon de désactiver les activations AAA dans une application de bibliothèque, car l’indicateur EOAC_DISABLE_AAA de l’énumération EOLE_AUTHENTICATION_CAPABILITIES est appliqué uniquement au processus serveur et non à l’application de bibliothèque.

Windows 2000 : Cet indicateur n’est pas pris en charge.
CLSCTX_ENABLE_AAA
Valeur : 0x10000
Active les activations AAA (Activate-As-Activator) pour cette activation uniquement. Cet indicateur remplace le paramètre de l’indicateur EOAC_DISABLE_AAA de l’énumération EOLE_AUTHENTICATION_CAPABILITIES. Cet indicateur ne peut pas être défini en même temps que CLSCTX_DISABLE_AAA. Toute activation dans laquelle un processus serveur serait lancé sous l’identité de l’appelant est appelée activation en tant qu’activateur (AAA). L’activation de cet indicateur permet à une application de transférer son identité vers un composant activé.

Windows 2000 : Cet indicateur n’est pas pris en charge.
CLSCTX_FROM_DEFAULT_CONTEXT
Valeur : 0x20000
Commence cette activation à partir du contexte par défaut de l'appartement actuel.
CLSCTX_ACTIVATE_X86_SERVER
Valeur : 0x40000
CLSCTX_ACTIVATE_32_BIT_SERVER
Activer ou se connecter à une version 32 bits du serveur ; échoue si l’un d’eux n’est pas inscrit.
CLSCTX_ACTIVATE_64_BIT_SERVER
Valeur : 0x80000
Activer ou se connecter à une version 64 bits du serveur ; échoue si l’un d’eux n’est pas inscrit.
CLSCTX_ENABLE_CLOAKING
Valeur : 0x100000
Lorsque cet indicateur est spécifié, COM utilise le jeton d’emprunt d’identité du thread, le cas échéant, pour la demande d’activation effectuée par le thread. Lorsque cet indicateur n’est pas spécifié ou si le thread n’a pas de jeton d’emprunt d’identité, COM utilise le jeton de processus du processus du thread pour la demande d’activation effectuée par le thread.


Windows Vista ou version ultérieure : Cet indicateur est pris en charge.
CLSCTX_APPCONTAINER
Valeur : 0x400000
Indique que l’activation concerne un conteneur d’application.


Note Cet indicateur est réservé à un usage interne et n’est pas destiné à être utilisé directement à partir de votre code.

 
CLSCTX_ACTIVATE_AAA_AS_IU
Valeur : 0x800000
Spécifiez cet indicateur pour le comportement d’activation interactive des utilisateurs pour les serveurs As-Activator. Une application du Windows Store Medium IL fortement nommée peut utiliser cet indicateur pour lancer un serveur COM « As Activator » sans nom fort. Vous pouvez également utiliser cet indicateur pour établir une liaison à un instance en cours d’exécution du serveur COM lancé par une application de bureau.

Le client doit être moyen IL, il doit avoir un nom fort, ce qui signifie qu’il a un SysAppID dans le jeton client, qu’il ne peut pas être dans la session 0 et qu’il doit avoir le même utilisateur que l’utilisateur de l’ID de session dans le jeton client.

Si le serveur est hors processus et « en tant qu’activateur », il lance le serveur avec le jeton de l’utilisateur de session du jeton client. Ce jeton ne sera pas fortement nommé.

Si le serveur est hors processus et s’exécute « Utilisateur interactif », cet indicateur n’a aucun effet.

Si le serveur est hors processus et qu’il s’agit d’un autre type RunAs, l’activation échoue.

Cet indicateur n’a aucun effet pour les serveurs in-process.

Les activations hors ordinateur échouent lorsqu’elles utilisent cet indicateur.
CLSCTX_RESERVED6
Valeur : 0x1000000
CLSCTX_ACTIVATE_ARM32_SERVER
Valeur : 0x2000000
CLSCTX_PS_DLL
Valeur : 0x80000000
Utilisé pour le chargement des DLL proxy/stub.


Note Cet indicateur est réservé à un usage interne et n’est pas destiné à être utilisé directement à partir de votre code.

 

Remarques

Les valeurs de l’énumération CLSCTX sont utilisées dans les appels d’activation (CoCreateInstance, CoCreateInstanceEx, CoGetClassObject, etc.) pour indiquer les contextes d’exécution préférés (in-process, local ou distant) dans lesquels un objet doit être exécuté. Ils sont également utilisés dans les appels à CoRegisterClassObject pour indiquer l’ensemble de contextes d’exécution dans lesquels un objet de classe doit être mis à disposition pour les demandes de construction d’instances (IClassFactory::CreateInstance).

Pour indiquer que plusieurs contextes sont acceptables, vous pouvez combiner plusieurs valeurs avec des UO booléens. Les contextes sont essayés dans l’ordre dans lequel ils sont répertoriés.

Étant donné un ensemble d’indicateurs CLSCTX , le contexte d’exécution à utiliser dépend de la disponibilité des codes de classe inscrits et d’autres paramètres en fonction de l’algorithme suivant.

  1. Si l’appel spécifie l’un des éléments suivants, CLSCTX_REMOTE_SERVER est implicite et est ajouté à la liste des indicateurs :
    1. Structure COSERVERINFO explicite indiquant une machine différente de l’ordinateur actuel.
    2. Aucune structure COSERVERINFO explicite spécifiée, mais la classe spécifiée est inscrite avec la valeur de Registre RemoteServerName ou ActivateAtStorage .
    Le deuxième cas permet aux applications écrites avant la publication de COM distribué de configurer des classes pour l’activation à distance à utiliser par les applications clientes disponibles avant DCOM et l’indicateur CLSCTX_REMOTE_SERVER. Les cas dans lesquels il n’y a pas de structure COSERVERINFO explicite sont lorsque la valeur est spécifiée comme NULL ou lorsqu’elle n’est pas l’un des paramètres de fonction (comme dans les appels à CoCreateInstance et CoGetClassObject).
  2. Si le paramètre COSERVERINFO explicite indique l’ordinateur actuel, CLSCTX_REMOTE_SERVER est supprimé s’il est présent.
Le reste du traitement se poursuit en examinant la ou les valeurs dans l’ordre suivant :
  1. Si les indicateurs incluent CLSCTX_REMOTE_SERVER et qu’aucun paramètre COSERVERINFO n’est spécifié et si la demande d’activation indique un état persistant à partir duquel initialiser l’objet (avec CoGetInstanceFromFile, CoGetInstanceFromIStorage ou, pour un moniker de fichier, dans un appel à IMoniker::BindToObject) et que la classe a un ActivateAtStorage sous-clé ou aucune information de registre de classe, la demande d’activation et d’initialisation est transférée à l’ordinateur où réside l’état persistant. (Pour plus d’informations, reportez-vous aux fonctions d’activation à distance répertoriées dans la section Voir aussi.)
  2. Si les indicateurs incluent CLSCTX_INPROC_SERVER, le code de classe dans la DLL trouvée sous la clé InprocServer32 de la classe est utilisé si cette clé existe. Le code de classe s’exécute dans le même processus que l’appelant.
  3. Si les indicateurs incluent CLSCTX_INPROC_HANDLER, le code de classe dans la DLL qui se trouve sous la clé InprocHandler32 de la classe est utilisé si cette clé existe. Le code de classe s’exécute dans le même processus que l’appelant.
  4. Si les indicateurs incluent CLSCTX_LOCAL_SERVER, le code de classe dans le service qui se trouve sous la clé LocalService de la classe est utilisé si cette clé existe. Si aucun service n’est spécifié, mais qu’un EXE est spécifié sous cette même clé, le code de classe associé à cette EXE est utilisé. Le code de classe (dans les deux cas) sera exécuté dans un processus de service distinct sur le même ordinateur que l’appelant.
  5. Si l’indicateur est défini sur CLSCTX_REMOTE_SERVER et qu’un paramètre COSERVERINFO supplémentaire pour la fonction spécifie un ordinateur distant particulier, une demande d’activation est transmise à cet ordinateur distant avec les indicateurs modifiés pour définir sur CLSCTX_LOCAL_SERVER. Le code de classe s’exécute dans son propre processus sur cet ordinateur spécifique, qui doit être différent de celui de l’appelant.
  6. Enfin, si les indicateurs incluent CLSCTX_REMOTE_SERVER et qu’aucun paramètre COSERVERINFO n’est spécifié et qu’un nom d’ordinateur est donné sous la valeur nommée RemoteServerName de la classe, la demande d’activation est transmise à cet ordinateur distant avec les indicateurs modifiés pour être définis sur CLSCTX_LOCAL_SERVER. Le code de classe s’exécute dans son propre processus sur cet ordinateur spécifique, qui doit être différent de celui de l’appelant.

CLSCTX_ACTIVATE_32_BIT_SERVER et CLSCTX_ACTIVATE_64_BIT_SERVER

Les versions 64 bits de Windows introduisent deux nouveaux indicateurs : CLSCTX_ACTIVATE_32_BIT_SERVER et CLSCTX_ACTIVATE_64_BIT_SERVER. Sur un ordinateur 64 bits, une version 32 bits et 64 bits du même serveur COM peut coexister. Lorsqu’un client demande l’activation d’un serveur hors processus, ces indicateurs CLSCTX permettent au client de spécifier une version 32 bits ou 64 bits du serveur.

En règle générale, un client ne se soucie pas de savoir s’il utilise une version 32 bits ou 64 bits du serveur. Toutefois, si le serveur lui-même charge un serveur in-process supplémentaire, celui-ci et le serveur in-process doivent être 32 bits ou 64 bits. Par exemple, supposons que le client souhaite utiliser un serveur « A », qui charge à son tour un serveur in-process « B ». Si seule une version 32 bits du serveur « B » est disponible, le client doit spécifier la version 32 bits du serveur « A ». Si seule une version 64 bits du serveur « B » est disponible, le client doit spécifier la version 64 bits du serveur « A ».

Un serveur peut spécifier sa propre préférence d’architecture via la clé de Registre PreferredServerBitness, mais la préférence du client, spécifiée via un indicateur CLSCTX_ACTIVATE_32_BIT_SERVER ou CLSCTX_ACTIVATE_64_BIT_SERVER, remplace la préférence du serveur. Si le client ne spécifie pas de préférence, la préférence du serveur est utilisée.

Si ni le client ni le serveur ne spécifient de préférence, alors :

  • Si l’ordinateur qui héberge le serveur exécute Windows Server 2003 avec Service Pack 1 (SP1) ou un système ultérieur, COM essaie de faire correspondre l’architecture du serveur à l’architecture cliente. En d’autres termes, pour un client 32 bits, COM active un serveur 32 bits si disponible ; sinon, il active une version 64 bits du serveur. Pour un client 64 bits, COM active un serveur 64 bits si disponible ; sinon, un serveur 32 bits est activé.
  • Si l’ordinateur qui héberge le serveur exécute Windows XP ou Windows Server 2003 sans SP1 ou version ultérieure installée, COM préférera une version 64 bits du serveur si disponible ; sinon, il active une version 32 bits du serveur.
Si une énumération CLSCTX a les indicateurs CLSCTX_ACTIVATE_32_BIT_SERVER et CLSCTX_ACTIVATE_64_BIT_SERVER définis, elle n’est pas valide et l’activation retourne E_INVALIDARG.

Le tableau suivant montre les résultats des différentes combinaisons d’architectures clientes et de paramètres client, d’architectures de serveur et de paramètres serveur.

Les indicateurs CLSCTX_ACTIVATE_32_BIT_SERVER et CLSCTX_ACTIVATE_64_BIT_SERVER circulent au-delà des limites de l’ordinateur. Si l’ordinateur qui héberge le serveur exécute windows 64 bits, il respecte ces indicateurs ; sinon, il les ignorera.

Client 32 bits, aucun indicateur Client 64 bits, aucun indicateur Client 32 bits, indicateur 32 bits¹ Client 32 bits, indicateur 64 bits² Client 64 bits, indicateur 32 bits¹ Client 64 bits, indicateur 64 bits²
Serveur 32 bits, correspondance de la valeur du Registre client³ Serveur 32 bits Voir ⁸ Serveur 32 bits Voir ⁸ Serveur 32 bits Voir ⁸
Serveur 32 bits, valeur de Registre 32 bits⁴ Serveur 32 bits Serveur 32 bits Serveur 32 bits Voir ⁸ Serveur 32 bits Voir ⁸
Serveur 32 bits, valeur de Registre 64 bits⁵ Voir ⁸ Voir ⁸ Serveur 32 bits Voir ⁸ Serveur 32 bits Voir ⁸
Serveur 32 bits, aucune valeur de Registre⁶ Serveur 32 bits 64/32⁹ Serveur 32 bits Voir ⁸ Serveur 32 bits Voir ⁸
Serveur 32 bits, aucune valeur de Registre (avant Windows Server 2003 avec SP1)⁷ 64/32⁹ 64/32⁹ Serveur 32 bits Voir ⁸ Serveur 32 bits Voir ⁸
Serveur 64 bits, correspondance de la valeur du Registre client³ Voir ⁸ Serveur 64 bits Voir ⁸ Serveur 64 bits Voir ⁸ Serveur 64 bits
Serveur 64 bits, valeur de Registre 32 bits⁴ Voir ⁸ Voir ⁸ Voir ⁸ Serveur 64 bits Voir ⁸ Serveur 64 bits
Serveur 64 bits, valeur de Registre 64 bits⁵ Serveur 64 bits Serveur 64 bits Voir ⁸ Serveur 64 bits Voir ⁸ Serveur 64 bits
Serveur 64 bits, aucune valeur de Registre⁶ 32/64¹⁰ Serveur 64 bits Voir ⁸ Serveur 64 bits Voir ⁸ Serveur 64 bits
Serveur 64 bits, aucune valeur de Registre (avant Windows Server 2003 avec SP1)⁷ Serveur 64 bits Serveur 64 bits Voir ⁸ Serveur 64 bits Voir ⁸ Serveur 64 bits
 

PreferredServerBitnessPreferredServerBitnessPreferredServerBitnessPreferredServerBitnessPreferredServerBitnessPreferredServerBitness

Spécifications

   
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
En-tête wtypesbase.h

Voir aussi

BIND_OPTS2

COSERVERINFO

CoCreateInstance

CoCreateInstanceEx

CoGetClassObject

CoGetInstanceFromFile

CoGetInstanceFromIStorage

CoRegisterClassObject

Création d’un objet par le biais d’un objet Class

IClassActivator::GetClassObject

Localisation d’un objet distant

Inscription d’un serveur EXE en cours d’exécution