Fonction SymFindFileInPath (dbghelp.h)

Article
08/23/2023

Recherche un fichier de symboles ou une image exécutable.

Syntaxe

BOOL IMAGEAPI SymFindFileInPath(
  [in]           HANDLE                  hprocess,
  [in, optional] PCSTR                   SearchPath,
  [in]           PCSTR                   FileName,
  [in, optional] PVOID                   id,
  [in]           DWORD                   two,
  [in]           DWORD                   three,
  [in]           DWORD                   flags,
  [out]          PSTR                    FoundFile,
  [in, optional] PFINDFILEINPATHCALLBACK callback,
  [in, optional] PVOID                   context
);

Paramètres

[in] hprocess

Handle du processus qui a été passé à l’origine à la fonction SymInitialize .

[in, optional] SearchPath

Chemin de recherche. Il peut s’agir de plusieurs chemins séparés par des points-virgules. Il peut inclure à la fois des répertoires et des serveurs de symboles. Si ce paramètre a la valeur NULL, la fonction utilise le chemin de recherche défini à l’aide de la fonction SymSetSearchPath ou SymInitialize .

[in] FileName

Nom du fichier. Vous pouvez spécifier un chemin d’accès ; toutefois, seul le nom de fichier est utilisé.

[in, optional] id

Le premier des trois paramètres d’identification (voir les remarques).

[in] two

Deuxième des trois paramètres d’identification (voir remarques).

[in] three

Troisième des trois paramètres d’identification (voir remarques).

[in] flags

Format du paramètre id . Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
SSRVOPT_DWORD 0x0002	Le paramètre id est un DWORD.
SSRVOPT_DWORDPTR 0x0004	Le paramètre id est un pointeur vers un DWORD.
SSRVOPT_GUIDPTR 0x0008	Le paramètre id est un pointeur vers un GUID.

[out] FoundFile

Pointeur vers une mémoire tampon qui reçoit le chemin complet du fichier de symboles. Cette mémoire tampon doit comporter au moins MAX_PATH caractères.

[in, optional] callback

Fonction de rappel SymFindFileInPathProc .

[in, optional] context

Valeur définie par l’utilisateur ou NULL. Cette valeur est simplement passée à la fonction de rappel. Ce paramètre est généralement utilisé par une application pour passer un pointeur vers une structure de données qui fournit un contexte pour la fonction de rappel.

Valeur retournée

Si le serveur localise un fichier de symboles valide, il retourne TRUE ; sinon, elle retourne FALSE et GetLastError renvoie une valeur qui indique pourquoi le fichier de symboles n’a pas été retourné.

Remarques

Les paramètres d’identification sont renseignés comme suit :

Si DbgHelp recherche un fichier .pdb, le paramètre id spécifie la signature PDB telle qu’elle se trouve dans le répertoire de débogage codeview de l’image d’origine. Le paramètre 2 spécifie l’âge PDB. Le paramètre 3 est inutilisé et défini sur zéro.
Si DbgHelp recherche un autre type d’image, tel qu’un fichier exécutable ou un fichier .dbg, le paramètre id spécifie le TimeDateStamp de l’image d’origine, tel qu’il se trouve dans son en-tête PE. Le paramètre 2 spécifie le champ SizeOfImage, également extrait de l’en-tête PE. Le paramètre 3 est inutilisé et défini sur zéro.

Toutes ces valeurs peuvent être obtenues en appelant SymSrvGetFileIndexInfo.

Lors de la recherche dans un répertoire, cette fonction ne vérifie pas que les identificateurs de symboles correspondent par défaut. Pour vous assurer que les fichiers de symboles correspondants se trouvent, appelez la fonction SymSetOptions avec SYMOPT_EXACT_SYMBOLS.

Toutes les fonctions DbgHelp, telles que celle-ci, sont à thread unique. Par conséquent, les appels de plusieurs threads à cette fonction entraîneront probablement un comportement inattendu ou une altération de la mémoire. Pour éviter cela, vous devez synchroniser tous les appels simultanés de plusieurs threads vers cette fonction.

Pour appeler la version Unicode de cette fonction, définissez DBGHELP_TRANSLATE_TCHAR.

Configuration requise

Condition requise	Valeur
Plateforme cible	Windows
En-tête	dbghelp.h
Bibliothèque	DbgHelp.lib
DLL	DbgHelp.dll
Composant redistribuable	DbgHelp.dll 5.1 ou version ultérieure