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

Article
02/23/2024

La méthode FindSourceFileAndToken retourne le nom de 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 d’accès 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 vérifié directement.

Ce paramètre peut être utilisé avec FoundElement pour case activée pour plusieurs correspondances dans le chemin d’accès 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 lié. 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. Et il n’est pas utilisé pour interroger les serveurs sources si FileToken n’a pas la valeur NULL.

[in] File

Spécifie le chemin d’accès et le nom du 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, File 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. Vous pouvez obtenir un jeton de fichier en définissant Lequel sur DEBUG_SRCFILE_SYMBOL_TOKEN dans la méthode GetSourceFileInformation.

Si l’indicateur DEBUG_FIND_SOURCE_TOKEN_LOOKUP est défini, FileToken ne doit pas avoir la valeur NULL.

[in] FileTokenSize

Spécifie la taille en octets du jeton FileToken . Si FileToken a la valeur 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 (sans utiliser le chemin d’accès source), -1 est retourné à FoundElement. Si FoundElement a la valeur NULL ou si les indicateurs contiennent des DEBUG_SRCFILE_SYMBOL_TOKEN, ces informations ne sont pas retournées.

[out, optional] Buffer

Reçoit le nom du fichier trouvé. Si le fichier ne se trouve 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 de chemin d’accès canonique complet du fichier. Sinon, il s’agit de la concaténation du répertoire dans le chemin d’accès source avec la fin du fichier qui a été utilisée pour trouver le fichier.

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

Si Buffer a la valeur NULL, ces informations ne sont pas retournées.

[in] BufferSize

Spécifie la taille en caractères de la mémoire tampon . Cette taille inclut l’espace pour le caractère de fin « \0 ». Si Buffer a la valeur 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 pour le caractère de fin « \0 ». Si foundSize a la valeur NULL, ces informations ne sont pas retournées.

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.
S_FALSE	La méthode a réussi. Toutefois, la mémoire tampon étant trop petite pour contenir le nom de fichier ou la valeur de la variable, la chaîne a été tronquée pour tenir dans 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 d’accès 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)--définissez File sur %SRCSRVCMD%.

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

Si le chemin d’accès 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 du répertoire et le 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\c\d et file 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 dans le chemin d’accès source, File 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 du fichier. Par exemple, si le chemin d’accès source contient un répertoire C :\a\b et file 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 de chemin d’accès canonique complet pour le 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 une fois 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 le jeu d’indicateurs par défaut, ce qui signifie que tous les indicateurs de la table précédente sont désactivés.