Funzione SearchPathW (processenv.h)

Articolo
03/08/2023

Esegue la ricerca di un determinato file in un percorso specificato.

Sintassi

DWORD SearchPathW(
  [in, optional]  LPCWSTR lpPath,
  [in]            LPCWSTR lpFileName,
  [in, optional]  LPCWSTR lpExtension,
  [in]            DWORD   nBufferLength,
  [out]           LPWSTR  lpBuffer,
  [out, optional] LPWSTR  *lpFilePart
);

Parametri

[in, optional] lpPath

Percorso in cui eseguire la ricerca del file.

Se questo parametro è NULL, la funzione cerca un file corrispondente usando un percorso di ricerca del sistema dipendente dal Registro di sistema. Per altre informazioni, vedere la sezione Osservazioni.

[in] lpFileName

Nome del file da ricercare.

[in, optional] lpExtension

Estensione da aggiungere al nome del file durante la ricerca del file. Il primo carattere dell'estensione del nome file deve essere un punto (.). L'estensione viene aggiunta solo se il nome file specificato non termina con un'estensione.

Se un'estensione del nome file non è necessaria o se il nome file contiene un'estensione, questo parametro può essere NULL.

[in] nBufferLength

Dimensioni del buffer che riceve il percorso e il nome file validi (incluso il carattere null di terminazione), in TCHAR.

[out] lpBuffer

Puntatore al buffer per ricevere il percorso e il nome file del file trovato. La stringa è una stringa con terminazione Null.

[out, optional] lpFilePart

Puntatore alla variabile per ricevere l'indirizzo (all'interno di lpBuffer) dell'ultimo componente del percorso e del nome file validi, ovvero l'indirizzo del carattere subito dopo la barra rovesciata finale (\) nel percorso.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è la lunghezza, in TCHARs, della stringa copiata nel buffer, senza includere il carattere Null di terminazione. Se il valore restituito è maggiore di nBufferLength, il valore restituito è la dimensione del buffer necessaria per contenere il percorso, incluso il carattere null di terminazione.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Se il parametro lpPath è NULL, SearchPath cerca un file corrispondente in base al valore corrente del Registro di sistema seguente:

HKEY_LOCAL_MACHINE\SISTEMA\Currentcontrolset\Controllo\\Gestione sessioniSafeProcessSearchMode

Quando il valore di questo REG_DWORD valore del Registro di sistema è impostato su 1, SearchPath cerca innanzitutto le cartelle specificate nel percorso di sistema e quindi esegue la ricerca nella cartella di lavoro corrente. Quando il valore di questo valore del Registro di sistema è impostato su 0, il computer cerca prima la cartella di lavoro corrente e quindi cerca le cartelle specificate nel percorso di sistema. Il valore predefinito di sistema per questa chiave del Registro di sistema è 0.

La modalità di ricerca utilizzata dalla funzione SearchPath può essere impostata anche per processo chiamando la funzione SetSearchPathMode .

La funzione SearchPath non è consigliata come metodo di individuazione di un file .dll se l'uso previsto dell'output è in una chiamata alla funzione LoadLibrary . Ciò può comportare l'individuazione del file di .dll errato perché l'ordine di ricerca della funzione SearchPath è diverso dall'ordine di ricerca usato dalla funzione LoadLibrary . Se è necessario individuare e caricare un file .dll, usare la funzione LoadLibrary .

Mancia A partire da Windows 10, versione 1607, per la versione Unicode di questa funzione (SearchPathW), è possibile acconsentire esplicitamente per rimuovere la limitazione MAX_PATH. Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di Denominazione di file, percorsi e spazi dei nomi .

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia	Supportato
Protocollo SMB (Server Message Block) 3.0	Sì
Failover trasparente SMB 3.0 (TFO)	Sì
SMB 3.0 con condivisioni file di scalabilità orizzontale (SO)	Sì
File system del volume condiviso cluster (CsvFS)	Sì
Resilient File System (ReFS)	Sì

Nota

L'intestazione processenv.h definisce SearchPath come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	processenv.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll