Méthode IDebugSymbols ::FindSourceFile (dbgeng.h)

Article
08/07/2023

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

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 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.

[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 (sans utiliser le chemin d’accès source), -1 est retourné à FoundElement. Si FoundElement a la valeur 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 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 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 .

[out, optional] FoundSize

Spécifie la taille, en caractères, du nom du fichier. 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.
E_NOINTERFACE	Le fichier est introuvable 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 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\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 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\samplefile.c, le fichier C :\a\b\e\samplefile.c est une correspondance.
La première correspondance trouvée est retournée.
Le fichier est recherché directement dans le système de classement.

Note 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 d’accès 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.