Énumération CLSCTX (wtypesbase.h)

Article
11/20/2024

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 des contextes d’exécution dans lesquels un objet de classe doit être mis à la disposition des demandes de construction d’instances.

Syntaxe

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 des 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 des structures côté client de cette classe lorsque des 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 est chargé dans un espace de processus distinct.
`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 des 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 du 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 Active le téléchargement du 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 La CLSCTX_NO_FAILURE_LOG peut être utilisée pour remplacer la journalisation des échecs dans CoCreateInstanceEx. Si l’activationFailureLoggingLevel est créée, les valeurs suivantes peuvent déterminer l’état de la journalisation des événements : 0 = Journalisation discrétionnaire. Journal par défaut, mais les clients peuvent remplacer en spécifiant CLSCTX_NO_FAILURE_LOG dans CoCreateInstanceEx. 1 = Consignez toujours tous les échecs quel que soit le client spécifié. 2 = Ne journaliser jamais les échecs quel que soit le client spécifié. Si l’entrée de 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 fortement 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 activate-as-activateor (AAA) 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’activation (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’application de bibliothèque d’être utilisée dans une attaque de sécurité avec élévation de 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 activate-as-activateor (AAA) 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’activation (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 Commencez cette activation à partir du contexte par défaut de l’appartement actuel.
`CLSCTX_ACTIVATE_X86_SERVER` Valeur : 0x40000
`CLSCTX_ACTIVATE_32_BIT_SERVER` Activez ou connectez-vous à 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. Remarque Cet indicateur est réservé à une utilisation 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 des utilisateurs interactifs pour les serveurs As-Activator. Une application Windows Store Moyenne IL fortement nommée peut utiliser cet indicateur pour lancer un serveur COM « As Activateor » sans nom fort. En outre, vous pouvez utiliser cet indicateur pour établir une liaison à une instance en cours d’exécution du serveur COM lancé par une application de bureau. Le client doit être il moyen, il doit être fortement nommé, 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 qu’il s’agit d’un « 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 machine é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 de DLL proxy/stub. Remarque Cet indicateur est réservé à une utilisation 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, et ainsi de suite) 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 le jeu de contextes d’exécution dans lesquels un objet de classe doit être mis à la disposition des requêtes pour construire des instances (IClassFactory ::CreateInstance).

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

Étant donné un ensemble d’indicateurs de 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.

Si l’appel spécifie l’un des éléments suivants, CLSCTX_REMOTE_SERVER est implicite et est ajouté à la liste des indicateurs :
1. Une structure COSERVERINFO explicite indiquant qu’un ordinateur est différent de l’ordinateur actuel.
2. Aucune structure COSERVERINFO 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ée d’être la configuration des classes pour l’activation à distance à utiliser par les applications clientes disponibles avant DCOM et l’indicateur de CLSCTX_REMOTE_SERVER. Les cas dans lesquels il n’y aurait 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).
Si le paramètre explicite COSERVERINFO 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 la séquence suivante :

Si les indicateurs incluent CLSCTX_REMOTE_SERVER et aucun paramètre COSERVERINFO est spécifié et si la demande d’activation indique un état persistant à partir duquel initialiser l’objet (avec CoGetInstanceFromFile, CoGetInstanceFromIStorageou, pour un moniker de fichier, dans un appel à IMoniker ::BindToObject) et la classe a un ActivateAtStorage sous-clé ou aucune information de Registre de classes, la demande d’activation et d’initialisation est transférée à l’ordinateur où réside l’état persistant. (Reportez-vous aux fonctions d’activation à distance répertoriées dans la section Voir aussi pour plus d’informations.)
Si les indicateurs incluent CLSCTX_INPROC_SERVER, le code de classe dans la DLL figurant 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.
Si les indicateurs incluent CLSCTX_INPROC_HANDLER, le code de classe dans la DLL figurant 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.
Si les indicateurs incluent CLSCTX_LOCAL_SERVER, le code de classe du service trouvé 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é à cet EXE est utilisé. Le code de classe (dans les deux cas) est exécuté dans un processus de service distinct sur le même ordinateur que l’appelant.
Si l’indicateur est défini sur CLSCTX_REMOTE_SERVER et qu’un paramètre COSERVERINFO supplémentaire à la fonction spécifie un ordinateur distant particulier, une demande d’activation est transférée à cet ordinateur distant avec des 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.
Enfin, si les indicateurs incluent CLSCTX_REMOTE_SERVER et qu’aucun paramètre COSERVERINFO est spécifié et si un nom d’ordinateur est donné sous la RemoteServerName valeur nommée de la classe, la demande d’activation est transférée à 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 présentent 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 une 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 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 l'PreferredServerBitness clé de Registre, 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 sera utilisée.

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

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 tente de faire correspondre l’architecture du serveur à l’architecture du client. En d’autres termes, pour un client 32 bits, COM active un serveur 32 bits s’il est disponible ; sinon, il active une version 64 bits du serveur. Pour un client 64 bits, COM active un serveur 64 bits s’il est disponible ; sinon, il active un serveur 32 bits.
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ère une version 64 bits du serveur si disponible ; sinon, il active une version 32 bits du serveur.

Si une énumération CLSCTX a à la fois les indicateurs CLSCTX_ACTIVATE_32_BIT_SERVER et CLSCTX_ACTIVATE_64_BIT_SERVER définis, il n’est pas valide et l’activation retourne E_INVALIDARG.

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

Les indicateurs CLSCTX_ACTIVATE_32_BIT_SERVER et CLSCTX_ACTIVATE_64_BIT_SERVER circulent entre les 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, mettre en correspondance la valeur de Registre du 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, mettre en correspondance la valeur de Registre du 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

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
d’en-tête	wtypesbase.h