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

Article
02/23/2024

La méthode FindSourceFile recherche dans le chemin d’accès source 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 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 source.

[in] File

Spécifie le chemin d’accès et le nom de fichier 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 rechercher le fichier. Si La mémoire tampon 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 rechercher un chevauchement entre la fin du chemin d’accès du répertoire et le début du chemin du 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, Le 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é à partir 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 d’accès source et de sa syntaxe, consultez Chemin d’accès source.