Método IDebugAdvanced3::FindSourceFileAndToken (dbgeng.h)

Artículo
08/07/2023

El método FindSourceFileAndToken devuelve el nombre de archivo de un archivo de origen en la ruta de acceso de origen o devuelve el valor de una variable asociada a un token de archivo.

Sintaxis

HRESULT FindSourceFileAndToken(
  [in]            ULONG   StartElement,
  [in]            ULONG64 ModAddr,
  [in]            PCSTR   File,
  [in]            ULONG   Flags,
  [in, optional]  PVOID   FileToken,
  [in]            ULONG   FileTokenSize,
  [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.

StartElement se omite si la marca DEBUG_FIND_SOURCE_TOKEN_LOOKUP está establecida en Marcas.

[in] ModAddr

Especifica una ubicación dentro de la asignación de memoria del módulo en el destino al que está relacionado el archivo de origen. ModAddr se usa para almacenar en caché los resultados de búsqueda y al consultar servidores de origen para el archivo. ModAddr puede ser NULL.

ModAddr se omite si la marca DEBUG_FIND_SOURCE_TOKEN_LOOKUP está establecida en Marcas. Y no se usa para consultar servidores de origen si FileToken no es NULL.

[in] File

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

Si se establece la marca DEBUG_FIND_SOURCE_TOKEN_LOOKUP, el token ya especifica el archivo en FileToken. En este caso, File especifica el nombre de una variable en el servidor de origen relacionado con el archivo. La variable debe comenzar y terminar con el signo de porcentaje ( % ), por ejemplo, %SRCSRVCMD%. Se devuelve el valor de esta variable.

[in] Flags

Especifica las marcas que controlan el comportamiento de este método. Para obtener una descripción de estas marcas, vea Comentarios.

[in, optional] FileToken

Especifica un token de archivo que representa un archivo en un servidor de origen. Un token de archivo se puede obtener estableciendo En qué DEBUG_SRCFILE_SYMBOL_TOKEN en el método GetSourceFileInformation.

Si se establece la marca DEBUG_FIND_SOURCE_TOKEN_LOOKUP, FileToken no debe ser NULL.

[in] FileTokenSize

Especifica el tamaño en bytes del token de FileToken . Si FileToken es NULL, se omite este parámetro.

[out, optional] FoundElement

Recibe el índice del elemento dentro de la ruta de acceso de origen que contenía 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 o Flags contiene DEBUG_SRCFILE_SYMBOL_TOKEN, esta información no se devuelve.

[out, optional] Buffer

Recibe el nombre del archivo que se encontró. Si el archivo no está en un servidor de origen, este es el nombre del archivo en la caché de origen local. 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 la marca DEBUG_SRCFILE_SYMBOL_TOKEN se establece en Marcas, Buffer recibe el valor de la variable denominada File asociada al token de archivo FileToken.

Si Buffer es NULL, no se devuelve esta información.

[in] BufferSize

Especifica el tamaño en caracteres del búfer de búfer . Este tamaño incluye el espacio para el carácter de terminación '\0'. Si Buffer es NULL, este parámetro se omite.

[out, optional] FoundSize

Especifica el tamaño en caracteres del nombre del archivo. Este tamaño incluye el espacio para el carácter de terminación '\0'. 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.
S_FALSE	Método realizado correctamente. Sin embargo , el búfer de búfer era demasiado pequeño para contener el nombre de archivo o el valor de variable, por lo que la cadena se truncaba para caber en el búfer.

Comentarios

Cuando la marca DEBUG_SRCFILE_SYMBOL_TOKEN se establece en Flags, este método no busca un archivo en la ruta de acceso de origen. En su lugar, busca una variable asociada al token de archivo proporcionado en FileToken. Estas variables se documentan en el tema Language Specification 1. Por ejemplo, para recuperar el valor de la variable SRCSRVCMD: el comando para extraer el archivo de código fuente del control de código fuente (también devuelto por la función DEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE de GetSourceFileInformation) establezca Archivo en %SRCSRVCMD%.

El motor usa los pasos siguientes para buscar el archivo:

Si la ruta de acceso de origen contiene servidores de origen y no se establece la marca DEBUG_FIND_SOURCE_NO_SRCSRV, primero se busca en el servidor de origen de la ruta de acceso de origen.
Se devuelve la primera coincidencia encontrada.
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\foo.c, el archivo C:\a\b\c\d\e\foo.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\foo.c, el archivo C:\a\b\e\foo.c es una coincidencia.
Se devuelve la primera coincidencia encontrada.
El archivo File se busca directamente en el sistema de archivado.

Para obtener más información sobre los archivos de origen, vea Uso de archivos de código fuente. Para obtener información general sobre la ruta de acceso de origen y su sintaxis, consulte Ruta de acceso de origen.

Las marcas de bits DEBUG_FIND_SOURCE_XXX se usan para controlar el comportamiento de los métodos FindSourceFile y FindSourceFileAndToken al buscar archivos de origen.

Las marcas pueden ser cualquier combinación de valores de la tabla siguiente.

Constante	Descripción
DEBUG_FIND_SOURCE_FULL_PATH	Devuelve siempre el nombre completo de la ruta de acceso canónica del archivo encontrado. Si no se establece y la ruta de acceso de origen contiene directorios relativos, se pueden devolver nombres de ruta de acceso relativos.
DEBUG_FIND_SOURCE_BEST_MATCH	Continuar buscando después de que se haya encontrado una coincidencia para buscar una mejor coincidencia.
DEBUG_FIND_SOURCE_NO_SRCSRV	No incluya servidores de origen en la búsqueda.
DEBUG_FIND_SOURCE_TOKEN_LOOKUP	Devuelve una variable asociada a un token de archivo. Si se establece esta marca, se omiten las demás marcas. Esta marca no se puede usar en el método FindSourceFile .

El valor DEBUG_FIND_SOURCE_DEFULT define el conjunto predeterminado de marcas, lo que significa que todas las marcas de la tabla anterior están desactivadas.