IDebugSymbols3 ::FindSourceFile, méthode (dbgeng.h)

Article
02/06/2025

La méthode FindSourceFile recherche le chemin d’accès source d’un fichier source spécifié.

Syntaxe

HRESULT FindSourceFile(
  [in]            ULONG  StartElement,
  [in]            PCSTR  File,
  [in]            ULONG  Flags,
  [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.

[in] File

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

[in] Flags

Spécifie les indicateurs de recherche. Pour obtenir une description de ces indicateurs, consultez DEBUG_FIND_SOURCE_XXX.

L’indicateur DEBUG_FIND_SOURCE_TOKEN_LOOKUP ne doit pas être défini. L’indicateur DEBUG_FIND_SOURCE_NO_SRCSRV est ignoré, car cette méthode n’inclut pas les serveurs sources dans la recherche.

[out, optional] FoundElement

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

[out, optional] Buffer

Reçoit le chemin d’accès et le nom du fichier trouvé. 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 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.

[out, optional] FoundSize

Spécifie la taille, en caractères, du nom du fichier. 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.
E_NOINTERFACE	fichier n’a pas été trouvé sur le chemin d’accès source.

Remarques

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

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 d’accès source contient un répertoire C :\a\b\c\d et Fichier est c\d\e\samplefile.c, le fichier C :\a\b\c\d\e\samplefile.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\samplefile.c, le fichier C :\a\b\e\samplefile.c est une correspondance.
La première correspondance trouvée est retournée.
fichier est recherché directement sur le système de classement.

Remarque Tous les serveurs sources dans le chemin d’accès source sont ignorés. Pour inclure les serveurs sources dans la recherche, utilisez FindSourceFileAndToken avec une adresse de module spécifiée dans ModAddr.

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