Función SymFindFileInPath (dbghelp.h)

Artículo
08/23/2023

Busca un archivo de símbolos o una imagen ejecutable.

Sintaxis

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
);

Parámetros

[in] hprocess

Identificador del proceso que se pasó originalmente a la función SymInitialize .

[in, optional] SearchPath

Ruta de búsqueda. Puede ser varias rutas de acceso separadas por punto y coma. Puede incluir tanto directorios como servidores de símbolos. Si este parámetro es NULL, la función usa la ruta de acceso de búsqueda establecida mediante la función SymSetSearchPath o SymInitialize .

[in] FileName

Nombre del archivo. Puede especificar una ruta de acceso; sin embargo, solo se usa el nombre de archivo.

[in, optional] id

El primero de tres parámetros de identificación (vea Comentarios).

[in] two

El segundo de tres parámetros de identificación (vea Comentarios).

[in] three

El tercero de tres parámetros de identificación (vea Comentarios).

[in] flags

Formato del parámetro id . Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
SSRVOPT_DWORD 0x0002	El parámetro id es un DWORD.
SSRVOPT_DWORDPTR 0x0004	El parámetro id es un puntero a un DWORD.
SSRVOPT_GUIDPTR 0x0008	El parámetro id es un puntero a un GUID.

[out] FoundFile

Puntero a un búfer que recibe la ruta de acceso completa al archivo de símbolos. Este búfer debe tener al menos MAX_PATH caracteres.

[in, optional] callback

Una función de devolución de llamada SymFindFileInPathProc .

[in, optional] context

Valor definido por el usuario o NULL. Este valor se pasa simplemente a la función de devolución de llamada. Normalmente, una aplicación usa este parámetro para pasar un puntero a una estructura de datos que proporciona algún contexto para la función de devolución de llamada.

Valor devuelto

Si el servidor busca un archivo de símbolos válido, devuelve TRUE; de lo contrario, devuelve FALSE y GetLastError devuelve un valor que indica por qué no se devolvió el archivo de símbolos.

Comentarios

Los parámetros de identificación se rellenan de la siguiente manera:

Si DbgHelp busca un archivo .pdb, el parámetro id especifica la firma PDB tal como se encuentra en el directorio de depuración de codeview de la imagen original. El parámetro dos especifica la antigüedad de PDB. El parámetro tres no se usa y se establece en cero.
Si DbgHelp busca cualquier otro tipo de imagen, como un archivo ejecutable o un archivo .dbg, el parámetro id especifica timeDateStamp de la imagen original tal como se encuentra en su encabezado PE. El parámetro dos especifica el campo SizeOfImage, que también se extrae del encabezado PE. El parámetro tres no se usa y se establece en cero.

Todos estos valores se pueden obtener llamando a SymSrvGetFileIndexInfo.

Al buscar en un directorio, esta función no comprueba que los identificadores de símbolo coincidan de forma predeterminada. Para asegurarse de que se encuentran los archivos de símbolos coincidentes, llame a la función SymSetOptions con SYMOPT_EXACT_SYMBOLS.

Todas las funciones DbgHelp, como esta, son un único subproceso. Por lo tanto, es probable que las llamadas desde más de un subproceso a esta función producirán un comportamiento inesperado o daños en la memoria. Para evitarlo, debe sincronizar todas las llamadas simultáneas de más de un subproceso a esta función.

Para llamar a la versión Unicode de esta función, defina DBGHELP_TRANSLATE_TCHAR.