IDebugAdvanced2 ::FindSourceFileAndToken, méthode (dbgeng.h)

Article
02/06/2025

La méthode FindSourceFileAndToken retourne le nom de fichier d’un fichier source sur le chemin d’accès source ou retourne la valeur d’une variable associée à un jeton de fichier.

Syntaxe

HRESULT FindSourceFileAndToken(
  [in]            ULONG   StartElement,
  [in]            ULONG64 ModAddr,
  [in]            PCSTR   File,
  [in]            ULONG   Flags,
  [in, optional]  PVOID   FileToken,
  [in]            ULONG   FileTokenSize,
  [out, optional] PULONG  FoundElement,
  [out, optional] PSTR    Buffer,
  [in]            ULONG   BufferSize,
  [out, optional] PULONG  FoundSize
);

Paramètres

[in] StartElement

Spécifie l’index d’un élément dans le chemin d’accès source à partir duquel commencer la recherche. Tous les éléments du chemin source avant StartElement sont exclus de la recherche. L’index du premier élément est égal à zéro. Si startElement est supérieur ou égal au nombre d’éléments dans le chemin source, le système de classement est activé directement.

Ce paramètre peut être utilisé avec FoundElement pour rechercher plusieurs correspondances dans le chemin source.

StartElement est ignoré si l’indicateur DEBUG_FIND_SOURCE_TOKEN_LOOKUP est défini dans indicateurs.

[in] ModAddr

Spécifie un emplacement dans l’allocation de mémoire du module dans la cible à laquelle le fichier source est associé. ModAddr est utilisé pour mettre en cache les résultats de la recherche et lors de l’interrogation des serveurs sources pour le fichier. ModAddr peut être NULL.

modAddr est ignoré si l’indicateur DEBUG_FIND_SOURCE_TOKEN_LOOKUP est défini dans indicateurs. Il n’est pas utilisé pour interroger des serveurs sources si FileToken n’est pas NULL.

[in] File

Spécifie le chemin d’accès et le nom de fichier à rechercher.

Si l’indicateur DEBUG_FIND_SOURCE_TOKEN_LOOKUP est défini, le fichier est déjà spécifié par le jeton dans FileToken. Dans ce cas, fichier spécifie le nom d’une variable sur le serveur source associé au fichier. La variable doit commencer et se terminer par le signe de pourcentage (%), par exemple, %SRCSRVCMD%. La valeur de cette variable est retournée.

[in] Flags

Spécifie les indicateurs qui contrôlent le comportement de cette méthode. Pour obtenir une description de ces indicateurs, consultez Remarques.

[in, optional] FileToken

Spécifie un jeton de fichier représentant un fichier sur un serveur source. Un jeton de fichier peut être obtenu en définissant Qui à DEBUG_SRCFILE_SYMBOL_TOKEN dans la méthode GetSourceFileInformation.

Si l’indicateur DEBUG_FIND_SOURCE_TOKEN_LOOKUP est défini, FileToken ne doit pas être NULL.

[in] FileTokenSize

Spécifie la taille en octets du jeton FileToken. Si FileToken est NULL, ce paramètre est ignoré.

[out, optional] FoundElement

Reçoit l’index de l’élément dans le chemin d’accès source qui contenait le fichier. Si le fichier a été trouvé directement sur le système de classement (pas à l’aide du chemin d’accès source), -1 est retourné à FoundElement. Si FoundElement est NULL ou Indicateurs contiennent DEBUG_SRCFILE_SYMBOL_TOKEN, ces informations ne sont pas retournée s.

[out, optional] Buffer

Reçoit le nom du fichier trouvé. Si le fichier n’est pas sur un serveur source, il s’agit du nom du fichier dans le cache source local. Si l’indicateur DEBUG_FIND_SOURCE_FULL_PATH est défini, il s’agit du nom complet du chemin canonique du fichier. Sinon, il s’agit de la concaténation du répertoire dans le chemin source avec la fin de Fichier utilisé pour rechercher le fichier.

Si l’indicateur DEBUG_SRCFILE_SYMBOL_TOKEN est défini dans Indicateurs, tampon reçoit la valeur de la variable nommée File associée au jeton de fichier FileToken.

Si tampon est NULL, ces informations ne sont pas retournées.

[in] BufferSize

Spécifie la taille en caractères de la mémoire tampon tampon. Cette taille inclut l’espace du caractère de fin « \0 ». Si tampon est NULL, ce paramètre est ignoré.

[out, optional] FoundSize

Spécifie la taille en caractères du nom du fichier. Cette taille inclut l’espace du caractère de fin « \0 ». Si foundSize est NULL, ces informations ne sont pas retournées.

Valeur de retour

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

Retourner le code	Description
S_OK	La méthode a réussi.
S_FALSE	La méthode a réussi. Toutefois, la mémoire tampon tampon était trop petite pour contenir le nom de fichier ou la valeur de la variable, de sorte que la chaîne était tronquée pour s’adapter à la mémoire tampon.

Remarques

Lorsque l’indicateur DEBUG_SRCFILE_SYMBOL_TOKEN est défini dans indicateurs, cette méthode ne recherche pas de fichier sur le chemin source. Au lieu de cela, il recherche une variable associée au jeton de fichier fourni dans FileToken. Ces variables sont documentées dans la rubrique Language Specification 1. Par exemple, pour récupérer la valeur de la variable SRCSRVCMD- la commande pour extraire le fichier source du contrôle de code source (également retournée par la fonction DEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE de GetSourceFileInformation)-set File à %SRCSRVCMD%.

Le moteur utilise les étapes suivantes : dans l’ordre pour rechercher le fichier :

Si le chemin source contient des serveurs sources et que l’indicateur DEBUG_FIND_SOURCE_NO_SRCSRV n’est pas défini, le serveur source dans le chemin source est d’abord recherché.
La première correspondance trouvée est retournée.
Pour chaque répertoire du chemin d’accès source, une tentative est effectuée pour trouver un chevauchement entre la fin du chemin d’accès au répertoire et le début du chemin d’accès au fichier. Par exemple, si le chemin source contient un répertoire C :\a\b\c\d et Fichier est c\d\e\foo.c, le fichier C :\a\b\c\d\e\foo.c est une correspondance.
Si l’indicateur DEBUG_FIND_SOURCE_BEST_MATCH est défini, la correspondance avec le chevauchement le plus long est retournée ; sinon, la première correspondance est retournée.
Pour chaque répertoire du chemin d’accès source, fichier est ajouté au répertoire. Si aucune correspondance n’est trouvée, ce processus est répété et chaque fois que le premier répertoire est supprimé du début du chemin d’accès au fichier. Par exemple, si le chemin d’accès source contient un répertoire C :\a\b et Fichier est c\d\e\foo.c, le fichier C :\a\b\e\foo.c est une correspondance.
La première correspondance trouvée est retournée.
Le fichier est recherché directement sur le système de classement.

Pour plus d’informations sur les fichiers sources, consultez Utilisation de fichiers sources. Pour obtenir une vue d’ensemble du chemin source et de sa syntaxe, consultez chemin d’accès source.

Les indicateurs de bits DEBUG_FIND_SOURCE_XXX sont utilisés pour contrôler le comportement des méthodes FindSourceFile et FindSourceFileAndToken lors de la recherche de fichiers sources.

Les indicateurs peuvent être n’importe quelle combinaison de valeurs du tableau suivant.

Constant	Description
DEBUG_FIND_SOURCE_FULL_PATH	Retournez toujours le nom complet du chemin canonique du fichier trouvé. S’il n’est pas défini et que le chemin d’accès source contient des répertoires relatifs, les noms de chemin d’accès relatifs peuvent être retournés.
DEBUG_FIND_SOURCE_BEST_MATCH	Poursuivez la recherche après qu’une correspondance a été trouvée pour rechercher une meilleure correspondance.
DEBUG_FIND_SOURCE_NO_SRCSRV	N’incluez pas de serveurs sources dans la recherche.
DEBUG_FIND_SOURCE_TOKEN_LOOKUP	Retourne une variable associée à un jeton de fichier. Si cet indicateur est défini, les autres indicateurs sont ignorés. Cet indicateur ne peut pas être utilisé dans la méthode FindSourceFile.

La valeur DEBUG_FIND_SOURCE_DEFULT définit l’ensemble par défaut d’indicateurs, ce qui signifie que tous les indicateurs du tableau précédent sont désactivés.