Funzione SetupGetStringFieldA (setupapi.h)
[Questa funzione è disponibile per l'uso nei sistemi operativi indicati nella sezione Requisiti. Potrebbe essere modificato o non disponibile nelle versioni successive. SetupAPI non deve più essere usata 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 SetupGetStringField recupera una stringa dal campo specificato di una riga in un file INF.
Sintassi
WINSETUPAPI BOOL SetupGetStringFieldA(
[in] PINFCONTEXT Context,
[in] DWORD FieldIndex,
[in, out] PSTR ReturnBuffer,
[in] DWORD ReturnBufferSize,
[out] PDWORD RequiredSize
);
Parametri
[in] Context
Puntatore al contesto di una riga in un file INF.
[in] FieldIndex
Indice in base 1 del campo all'interno della riga specificata da cui deve essere recuperata la stringa. Usare un FieldIndex pari a 0 per recuperare una chiave stringa, se presente.
[in, out] ReturnBuffer
Puntatore facoltativo a un buffer che riceve il nullstringa con terminazione. È necessario assicurarsi che il buffer di destinazione sia la stessa dimensione o maggiore del buffer di origine. Questo parametro può essere NULL. Vedere la sezione Osservazioni.
[in] ReturnBufferSize
Dimensioni del buffer a cui punta ReturnBuffer, in caratteri . Ciò include il carattere di terminazione null
[out] RequiredSize
Puntatore facoltativo a una variabile che riceve le dimensioni necessarie per il buffer a cui punta il parametro ReturnBuffer, in caratteri. Se viene specificato ReturnBuffer e le dimensioni effettive necessarie sono maggiori del valore specificato da ReturnBufferSize, la funzione non riesce e non archivia la stringa nel buffer. In questo caso, una chiamata a GetLastError restituisce ERROR_INSUFFICIENT_BUFFER. Per la versione Unicode di questa funzione, le dimensioni necessarie sono in caratteri. Ciò include il carattere di terminazione null
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un valore diverso da zero.
Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.
Osservazioni
Se questa funzione viene chiamata con un ReturnBuffer di NULL e un ReturnBufferSize pari a zero, la funzione inserisce le dimensioni del buffer necessarie per contenere i dati specificati nella variabile a cui punta RequiredSize. Se la funzione ha esito positivo, il valore restituito è un valore diverso da zero. In caso contrario, il valore restituito è zero e è possibile ottenere informazioni estese sull'errore chiamando GetLastError.
È possibile chiamare la funzione una 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 a causa di dimensioni del buffer insufficienti.
Si noti che la lunghezza massima di una singola stringa specificata in una sezione Stringhe INF è di 512 caratteri, inclusa la terminazione NULL. Se la lunghezza della stringa è maggiore di 512, verrà troncata e non verrà restituito alcun errore. La lunghezza massima di qualsiasi stringa concatenata creata da uno o più token di %strkey% è di 4096 caratteri.
Nota
L'intestazione setupapi.h definisce SetupGetStringField 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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP [solo app desktop] |
| server minimo supportato | Windows Server 2003 [solo app desktop] |
| piattaforma di destinazione | Finestre |
| intestazione |
setupapi.h |
| libreria |
Setupapi.lib |
| dll | Setupapi.dll |
| set di API | ext-ms-win-setupapi-inf-l1-1-1 (introdotto in Windows 10, versione 10.0.14393) |