IDebugClient5 ::CreateProcessAndAttach2, méthode (dbgeng.h)

Article
02/26/2024

La méthode CreateProcessAndAttach2 crée un processus à partir d’une ligne de commande spécifiée, puis s’attache à ce processus ou à un autre processus en mode utilisateur.

Syntaxe

HRESULT CreateProcessAndAttach2(
  [in]           ULONG64 Server,
  [in, optional] PSTR    CommandLine,
  [in]           PVOID   OptionsBuffer,
  [in]           ULONG   OptionsBufferSize,
  [in, optional] PCSTR   InitialDirectory,
  [in, optional] PCSTR   Environment,
  [in]           ULONG   ProcessId,
  [in]           ULONG   AttachFlags
);

Paramètres

[in] Server

Spécifie le serveur de processus à utiliser pour l’attacher au processus. Si le serveur est égal à zéro, le moteur se connecte au processus local sans utiliser de serveur de processus.

[in, optional] CommandLine

Spécifie la ligne de commande à exécuter pour créer le nouveau processus. Si CommandLine a la valeur NULL, aucun processus n’est créé et ces méthodes utilisent ProcessId pour l’attacher à un processus existant.

[in] OptionsBuffer

Spécifie les options de création de processus. OptionsBuffer est un pointeur vers une structure DEBUG_CREATE_PROCESS_OPTIONS .

[in] OptionsBufferSize

Spécifie la taille de la mémoire tampon OptionsBuffer. Cette valeur doit être définie sur sizeof(DEBUG_CREATE_PROCESS_OPTIONS).

[in, optional] InitialDirectory

Spécifie le répertoire de départ du processus. Ce paramètre est utilisé uniquement si CommandLine n’a pas la valeur NULL. Si InitialDirectory a la valeur NULL, le répertoire actif du serveur de processus est utilisé.

[in, optional] Environment

Spécifie un bloc d’environnement pour le nouveau processus. Un bloc d’environnement se compose d’un bloc null de chaînes terminées par null. Chaque chaîne est de la forme suivante :

name=value

Notez que les deux derniers caractères du bloc d’environnement sont à la fois NULL : l’un pour arrêter la chaîne et l’autre pour terminer le bloc.

Si Environnement a la valeur NULL, le nouveau processus hérite du bloc d’environnement du serveur de processus. Si l’indicateur DEBUG_CREATE_PROCESS_THROUGH_RTL est défini dans OptionsBuffer, l’environnement doit avoir la valeur NULL.

[in] ProcessId

Spécifie l’ID de processus du processus cible auquel le débogueur doit attacher. Si ProcessID est égal à zéro, le débogueur s’attache au processus qu’il a créé à partir de CommandLine.

[in] AttachFlags

Spécifie les indicateurs qui contrôlent la façon dont le débogueur s’attache au processus cible. Pour plus d’informations sur ces indicateurs, consultez DEBUG_ATTACH_XXX.

Valeur retournée

Cette méthode peut également retourner des valeurs d’erreur. Pour plus d’informations, consultez Valeurs de retour .

Code de retour	Description
S_OK	La méthode a réussi.
E_INVALIDARG	Cette valeur est retournée si CommandLine a la valeur NULL et que ProcessId est égal à zéro.

Remarques

Cette méthode est disponible uniquement pour le débogage en mode utilisateur actif.

Si CommandLine n’a pas la valeur NULL et que ProcessId n’est pas zéro, le moteur crée le processus dans un état suspendu. Le moteur reprend ce processus nouvellement créé une fois qu’il s’est connecté au processus spécifié dans ProcessId.

Note Le moteur ne s’attache pas complètement au processus tant que la méthode WaitForEvent n’a pas été appelée. Ce n’est qu’une fois que le processus a généré un événement (par exemple, l’événement create-process) qu’il devient disponible dans la session du débogueur.

Pour plus d’informations sur la création et l’attachement à des cibles en mode utilisateur en direct, consultez Cibles de User-Mode en direct.