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

Artículo
08/07/2023

El método FindSourceFile busca en la ruta de acceso de origen un archivo de origen especificado.

Sintaxis

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

Parámetros

[in] StartElement

Especifica el índice de un elemento dentro de la ruta de acceso de origen desde la que empezar a buscar. Todos los elementos de la ruta de acceso de origen antes de Que StartElement se excluyan de la búsqueda. El índice del primer elemento es cero. Si StartElement es mayor o igual que el número de elementos de la ruta de acceso de origen, el sistema de archivado se comprueba directamente.

Este parámetro se puede usar con FoundElement para comprobar si hay varias coincidencias en la ruta de acceso de origen.

[in] File

Especifica la ruta de acceso y el nombre de archivo del archivo que se va a buscar.

[in] Flags

Especifica las marcas de búsqueda. Para obtener una descripción de estas marcas, consulte DEBUG_FIND_SOURCE_XXX.

No se debe establecer la marca DEBUG_FIND_SOURCE_TOKEN_LOOKUP. La marca DEBUG_FIND_SOURCE_NO_SRCSRV se omite porque este método no incluye servidores de origen en la búsqueda.

[out, optional] FoundElement

Recibe el índice del elemento dentro de la ruta de acceso de origen que contiene el archivo. Si el archivo se encontró directamente en el sistema de presentación (no mediante la ruta de acceso de origen), -1 se devuelve a FoundElement. Si FoundElement es NULL, esta información no se devuelve.

[out, optional] Buffer

Recibe la ruta de acceso y el nombre del archivo encontrado. Si se establece la marca DEBUG_FIND_SOURCE_FULL_PATH, se trata del nombre completo de la ruta de acceso canónica del archivo. De lo contrario, es la concatenación del directorio en la ruta de acceso de origen con el final del archivo que se usó para buscar el archivo. Si Buffer es NULL, no se devuelve esta información.

[in] BufferSize

Especifica el tamaño, en caracteres, del búfer de búfer .

[out, optional] FoundSize

Especifica el tamaño, en caracteres, del nombre del archivo. Si FoundSize es NULL, esta información no se devuelve.

Valor devuelto

Este método también puede devolver valores de error. Consulte Valores devueltos para obtener más detalles.

Código devuelto	Descripción
S_OK	Método realizado correctamente.
E_NOINTERFACE	No se encontró el archivo en la ruta de acceso de origen.

Comentarios

El motor usa los pasos siguientes para buscar el archivo:

Para cada directorio de la ruta de acceso de origen, se intenta buscar una superposición entre el final de la ruta de acceso del directorio y el principio de la ruta de acceso del archivo. Por ejemplo, si la ruta de acceso de origen contiene un directorio C:\a\b\c\d y File es c\d\e\samplefile.c, el archivo C:\a\b\c\d\e\samplefile.c es una coincidencia.
Si se establece la marca DEBUG_FIND_SOURCE_BEST_MATCH, se devuelve la coincidencia con la superposición más larga; de lo contrario, se devuelve la primera coincidencia.
Para cada directorio de la ruta de acceso de origen, el archivo se anexa al directorio. Si no se encuentra ninguna coincidencia, este proceso se repite y cada vez que se quita el primer directorio desde el principio de la ruta de acceso del archivo. Por ejemplo, si la ruta de acceso de origen contiene un directorio C:\a\b y File es c\d\e\samplefile.c, el archivo C:\a\b\e\samplefile.c es una coincidencia.
Se devuelve la primera coincidencia encontrada.
El archivo se busca directamente en el sistema de archivo.

Nota Se omiten los servidores de origen de la ruta de acceso de origen. Para incluir los servidores de origen en la búsqueda, use FindSourceFileAndToken con una dirección de módulo especificada en ModAddr.

Para obtener más información sobre el uso de la ruta de acceso de origen, consulte Uso de archivos de origen. Para obtener información general sobre la ruta de acceso de origen y su sintaxis, consulte Ruta de acceso de origen.