Funzione SetupPromptForDiskA (setupapi.h)

Articolo
03/01/2024

[Questa funzione è disponibile per l'uso nei sistemi operativi indicati nella sezione Requisiti. È possibile che in versioni successive sia stata modificata o non sia più disponibile. SetupAPI non deve più essere usato per l'installazione di applicazioni. Usare invece Windows Installer per lo sviluppo di programmi di installazione delle applicazioni. SetupAPI continua a essere usato per l'installazione dei driver di dispositivo.

La funzione SetupPromptForDisk visualizza una finestra di dialogo che richiede all'utente di specificare un disco.

Sintassi

WINSETUPAPI UINT SetupPromptForDiskA(
  [in]      HWND   hwndParent,
  [in]      PCSTR  DialogTitle,
  [in]      PCSTR  DiskName,
  [in]      PCSTR  PathToSource,
  [in]      PCSTR  FileSought,
  [in]      PCSTR  TagFile,
  [in]      DWORD  DiskPromptStyle,
  [in, out] PSTR   PathBuffer,
  [in]      DWORD  PathBufferSize,
  [in, out] PDWORD PathRequiredSize
);

Parametri

[in] hwndParent

Handle nella finestra padre per questa finestra di dialogo.

[in] DialogTitle

Puntatore facoltativo a una stringa con terminazione Null che specifica il titolo della finestra di dialogo. Se questo parametro è NULL, viene usato il valore predefinito ""%s-Files Needed"" (localizzato). "%s" viene sostituito con il testo recuperato dalla finestra padre. Se non viene recuperato alcun testo dalla finestra padre, il titolo è "File necessari".

[in] DiskName

Puntatore facoltativo a una stringa con terminazione Null che specifica il nome del disco da inserire. Se questo parametro è NULL, viene usato il valore predefinito "(Unknown)" (localizzato).

[in] PathToSource

Puntatore facoltativo a una stringa con terminazione Null che specifica la parte del percorso previsto del file, ad esempio F:\x86. Se non specificato, viene usato il percorso in cui setupPromptForDisk trova più di recente un file. Se l'elenco è vuoto, viene utilizzato un valore predefinito di sistema.

[in] FileSought

Puntatore a una stringa con terminazione Null che specifica il nome del file necessario (solo parte del nome file). Il nome file viene visualizzato se l'utente fa clic sul pulsante Sfoglia . Questa routine cerca il file utilizzando i nomi di modulo compressi; pertanto, è possibile passare cmd.exe e non preoccuparsi che il file esista effettivamente come cmd.ex_ nel supporto di origine.

[in] TagFile

Puntatore facoltativo a una stringa con terminazione Null che specifica un file di tag (solo parte del nome file) che identifica la presenza di un determinato volume multimediale rimovibile. Se il percorso attualmente selezionato inserisce il file su supporti rimovibili e viene specificato un file di tag, SetupPromptForDisk cerca il file tag nella radice dell'unità per determinare se continuare.

Ad esempio, se PathToSource è A:\x86, il tagfile è disk1.tag e l'utente digita B:\x86 nel controllo di modifica della finestra di dialogo del prompt, la routine cerca B:\disk1.tag per determinare se continuare. Se il file di tag non viene trovato, la funzione cerca il tagfile usando PathToSource.

Se non si specifica un file di tag, i supporti rimovibili funzionano come supporti non rimovibili e FileSought viene cercato prima di continuare.

[in] DiskPromptStyle

Specifica il comportamento della finestra di dialogo. Questo parametro può essere una combinazione dei flag seguenti.

IDF_CHECKFIRST

Verificare la presenza del file o del disco prima di visualizzare la finestra di dialogo di richiesta e, se presente, restituire immediatamente DPROMPT_SUCCESS.

IDF_NOBEEP

Impedire che la finestra di dialogo venga visualizzata per la prima volta per ottenere l'attenzione dell'utente.

IDF_NOBROWSE

Non visualizzare l'opzione sfoglia.

IDF_NOCOMPRESSED

Non verificare la presenza di versioni compresse del file di origine.

IDF_NODETAILS

Non visualizzare informazioni dettagliate.

IDF_NOFOREGROUND

Impedisci che la finestra di dialogo diventi la finestra in primo piano.

IDF_NOSKIP

Non visualizzare l'opzione skip.

IDF_OEMDISK

Richiedere un disco fornito da un produttore dell'hardware.

IDF_WARNIFSKIP

Avvisare l'utente che ignora un file può influire sull'installazione.

[in, out] PathBuffer

Puntatore facoltativo a un buffer che, al momento della restituzione, riceve il percorso (nessun nome file) del percorso specificato dall'utente tramite la finestra di dialogo. È consigliabile usare una stringa con terminazione Null. La stringa con terminazione Null non deve superare le dimensioni del buffer di destinazione. È possibile chiamare la funzione una sola volta per ottenere le dimensioni del buffer necessarie, allocare la memoria necessaria e quindi chiamare la funzione una seconda volta per recuperare i dati. Usando questa tecnica, è possibile evitare errori dovuti a dimensioni del buffer insufficienti. Vedere la sezione relativa alle osservazioni.

[in] PathBufferSize

Dimensioni del buffer a cui punta PathBuffer, in caratteri. Dovrebbe essere almeno MAX_PATH lungo. Ciò include il carattere di terminazione Null .

[in, out] PathRequiredSize

Puntatore facoltativo a una variabile che riceve le dimensioni necessarie per PathBuffer, in caratteri. Ciò include il carattere di terminazione Null .

Valore restituito

La funzione restituisce uno dei valori seguenti.

Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Se questa funzione viene chiamata con pathBuffernull epathBufferSize pari a zero, la funzione inserisce le dimensioni del buffer necessarie per contenere i dati specificati nella variabile a cui punta PathRequiredSize. Se la funzione ha esito positivo, il valore restituito è NO_ERROR. In caso contrario, il valore restituito è uno dei valori descritti nella sezione Valori restituiti.

Nota

L'intestazione setupapi.h definisce SetupPromptForDisk 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	setupapi.h
Libreria	Setupapi.lib
DLL	Setupapi.dll