Metodo IDebugAdvanced3::FindSourceFileAndToken (dbgeng.h)

Articolo
03/08/2023

Il metodo FindSourceFileAndToken restituisce il nome file di un file di origine nel percorso di origine o restituisce il valore di una variabile associata a un token di file.

Sintassi

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

Parametri

[in] StartElement

Specifica l'indice di un elemento all'interno del percorso di origine da cui iniziare la ricerca. Tutti gli elementi nel percorso di origine prima che StartElement vengano esclusi dalla ricerca. L'indice del primo elemento è zero. Se StartElement è maggiore o uguale al numero di elementi nel percorso di origine, il sistema di archiviazione viene controllato direttamente.

Questo parametro può essere usato con FoundElement per verificare la presenza di più corrispondenze nel percorso di origine.

StartElement viene ignorato se il flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP è impostato in Flag.

[in] ModAddr

Specifica un percorso all'interno dell'allocazione di memoria del modulo nella destinazione a cui è correlato il file di origine. ModAddr viene usato per memorizzare nella cache i risultati della ricerca e quando si esegue una query sui server di origine per il file. ModAddr può essere NULL.

ModAddr viene ignorato se il flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP è impostato in Flag. E non viene usato per eseguire query sui server di origine se FileToken non è NULL.

[in] File

Specifica il percorso e il nome file del file da cercare.

Se il flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP è impostato, il file è già specificato dal token in FileToken. In questo caso, File specifica il nome di una variabile nel server di origine correlato al file. La variabile deve iniziare e terminare con il segno percentuale ( % ), ad esempio %SRCSRVCMD%. Viene restituito il valore di questa variabile.

[in] Flags

Specifica i flag che controllano il comportamento di questo metodo. Per una descrizione di questi flag, vedere Osservazioni.

[in, optional] FileToken

Specifica un token di file che rappresenta un file in un server di origine. È possibile ottenere un token di file impostando Quale DEBUG_SRCFILE_SYMBOL_TOKEN nel metodo GetSourceFileInformation.

Se il flag DEBUG_FIND_SOURCE_TOKEN_LOOKUP è impostato, FileToken non deve essere NULL.

[in] FileTokenSize

Specifica le dimensioni in byte del token FileToken . Se FileToken è NULL, questo parametro viene ignorato.

[out, optional] FoundElement

Riceve l'indice dell'elemento all'interno del percorso di origine che contiene il file. Se il file è stato trovato direttamente nel sistema di archiviazione (non usando il percorso di origine), -1 viene restituito a FoundElement. Se FoundElement è NULL o Flags contengono DEBUG_SRCFILE_SYMBOL_TOKEN, queste informazioni non vengono restituite.

[out, optional] Buffer

Riceve il nome del file trovato. Se il file non è in un server di origine, questo è il nome del file nella cache di origine locale. Se il flag DEBUG_FIND_SOURCE_FULL_PATH è impostato, si tratta del nome del percorso canonico completo per il file. In caso contrario, è la concatenazione della directory nel percorso di origine con la parte finale di File usata per trovare il file.

Se il flag DEBUG_SRCFILE_SYMBOL_TOKEN è impostato in Flag, buffer riceve il valore della variabile denominata File associata al file file FileToken.

Se buffer è NULL, queste informazioni non vengono restituite.

[in] BufferSize

Specifica le dimensioni in caratteri del buffer del buffer. Questa dimensione include lo spazio per il carattere di terminazione '\0'. Se buffer è NULL, questo parametro viene ignorato.

[out, optional] FoundSize

Specifica le dimensioni in caratteri del nome del file. Questa dimensione include lo spazio per il carattere di terminazione '\0'. Se foundSize è NULL, queste informazioni non vengono restituite.

Valore restituito

Questo metodo può anche restituire valori di errore. Per altre informazioni, vedere Valori restituiti .

Codice restituito	Descrizione
S_OK	Il metodo è stato eseguito correttamente.
S_FALSE	Il metodo è stato eseguito correttamente. Tuttavia, il buffer buffer era troppo piccolo per contenere il nome del file o il valore della variabile, quindi la stringa è stata troncata per adattarsi al buffer.

Commenti

Quando il flag DEBUG_SRCFILE_SYMBOL_TOKEN è impostato in Flag, questo metodo non cerca un file nel percorso di origine. Cerca invece una variabile associata al token di file fornito in FileToken. Queste variabili sono documentate nell'argomento Specifica del linguaggio 1. Ad esempio, per recuperare il valore della variabile SRCSRVCMD--il comando per estrarre il file di origine dal controllo del codice sorgente (restituito anche dalla funzione DEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE di GetSourceFileInformation)-set File su %SRCSRVCMD%.

Il motore usa i passaggi seguenti per cercare il file:

Se il percorso di origine contiene qualsiasi server di origine e il flag DEBUG_FIND_SOURCE_NO_SRCSRV non è impostato, il server di origine nel percorso di origine viene eseguito prima di tutto.
Viene restituita la prima corrispondenza trovata.
Per ogni directory nel percorso di origine, viene eseguito un tentativo di trovare una sovrapposizione tra la fine del percorso della directory e l'inizio del percorso del file. Ad esempio, se il percorso di origine contiene una directory C:\a\b\c\d e File è c\d\e\foo.c, il file C:\a\b\c\d\e\foo.c è una corrispondenza.
Se il flag DEBUG_FIND_SOURCE_BEST_MATCH è impostato, viene restituita la corrispondenza con la sovrapposizione più lunga; in caso contrario, viene restituita la prima corrispondenza.
Per ogni directory nel percorso di origine, il file viene aggiunto alla directory. Se non viene trovata alcuna corrispondenza, questo processo viene ripetuto e ogni volta che la prima directory viene rimossa dall'inizio del percorso del file. Ad esempio, se il percorso di origine contiene una directory C:\a\b e File è c\d\e\foo.c, il file C:\a\b\e\foo.c è una corrispondenza.
Viene restituita la prima corrispondenza trovata.
Il file viene cercato direttamente nel sistema di archiviazione.

Per altre informazioni sui file di origine, vedere Uso di file di origine. Per una panoramica del percorso di origine e della relativa sintassi, vedere Percorso di origine.

I flag a bit DEBUG_FIND_SOURCE_XXX vengono usati per controllare il comportamento dei metodi FindSourceFile e FindSourceFileAndToken durante la ricerca di file di origine.

I flag possono essere qualsiasi combinazione di valori della tabella seguente.

Costante	Descrizione
DEBUG_FIND_SOURCE_FULL_PATH	Restituisce sempre il nome del percorso canonico completo per il file trovato. Se non è impostato e il percorso di origine contiene directory relative, è possibile restituire i nomi dei percorsi relativi.
DEBUG_FIND_SOURCE_BEST_MATCH	Continuare la ricerca dopo che è stata trovata una corrispondenza per cercare una corrispondenza migliore.
DEBUG_FIND_SOURCE_NO_SRCSRV	Non includere server di origine nella ricerca.
DEBUG_FIND_SOURCE_TOKEN_LOOKUP	Restituire una variabile associata a un token di file. Se questo flag è impostato, gli altri flag vengono ignorati. Questo flag non può essere usato nel metodo FindSourceFile .