SymFindFileInPathW, fonction (dbghelp.h)

Article
11/20/2024

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

Syntaxe

BOOL IMAGEAPI SymFindFileInPathW(
  [in]           HANDLE                   hprocess,
  [in, optional] PCWSTR                   SearchPath,
  [in]           PCWSTR                   FileName,
  [in, optional] PVOID                    id,
  [in]           DWORD                    two,
  [in]           DWORD                    three,
  [in]           DWORD                    flags,
  [out]          PWSTR                    FoundFile,
  [in, optional] PFINDFILEINPATHCALLBACKW 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 d’accès 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 est 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

Premier des trois paramètres d’identification (voir Remarques).

[in] two

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

[in] three

Troisième de trois paramètres d’identification (voir Remarques).

[in] flags

Format du paramètre id de . Ce paramètre peut être l’une des valeurs suivantes.

Valeur	Signification
SSRVOPT_DWORD 0x0002	Le paramètre id est unDWORD .
SSRVOPT_DWORDPTR 0x0004	Le paramètre id est un pointeur vers unDWORD .
SSRVOPT_GUIDPTR 0x0008	Le paramètre ID est un pointeur vers unGUID .

[out] FoundFile

Pointeur vers une mémoire tampon qui reçoit le chemin complet du fichier de symboles. Cette mémoire tampon doit être 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 de retour

Si le serveur localise un fichier de symboles valide, il retourne TRUE; sinon, elle retourne FALSE et GetLastError retourne 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, l’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 deux spécifie l’âge PDB. Le paramètre trois 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 deux spécifie le champ SizeOfImage, également extrait de l’en-tête PE. Le paramètre trois 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, comme celle-ci, sont monothread. Par conséquent, les appels de plusieurs threads à cette fonction entraîneront probablement une altération inattendue du comportement ou 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.

Note

L’en-tête dbghelp.h définit SymFindFileInPath comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.