Funzione SetupGetBinaryField (setupapi.h)

Articolo
08/26/2023

[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 di applicazioni. SetupAPI continua a essere usato per l'installazione dei driver di dispositivo.

La funzione SetupGetBinaryField recupera i dati binari da una riga in un file INF, dal campo specificato alla fine della riga.

Sintassi

WINSETUPAPI BOOL SetupGetBinaryField(
  [in]      PINFCONTEXT Context,
  [in]      DWORD       FieldIndex,
  [in, out] PBYTE       ReturnBuffer,
  [in]      DWORD       ReturnBufferSize,
  [in, out] LPDWORD     RequiredSize
);

Parametri

[in] Context

Contesto INF per la riga.

[in] FieldIndex

Indice basato su 1 del campo iniziale all'interno della riga specificata da cui recuperare i dati binari. I dati binari vengono compilati da ogni campo, a partire da questo punto alla fine della riga. Ogni campo corrisponde a 1 byte ed è in notazione esadecimale. FieldIndex di zero non è valido con questa funzione.

[in, out] ReturnBuffer

Puntatore facoltativo a un buffer che riceve i dati binari. È necessario assicurarsi che il buffer di destinazione sia la stessa dimensione o maggiore del buffer di origine. È 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. Vedere la sezione relativa alle osservazioni.

[in] ReturnBufferSize

Dimensioni del buffer a cui punta returnBuffer, in caratteri. Questo numero include il terminatore Null .

[in, out] RequiredSize

Puntatore facoltativo a una variabile che riceve le dimensioni necessarie per il buffer che punta a ReturnBuffer, in caratteri. Questo numero include il terminatore Null . Se le dimensioni necessarie sono maggiori del valore specificato da ReturnBufferSize, la funzione ha esito negativo e una chiamata a GetLastError restituisce ERROR_INSUFFICIENT_BUFFER.

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 informazioni dettagliate sull'errore, chiamare GetLastError.

GetLastError restituisce ERROR_INVALID_DATA se un campo recuperato da SetupGetBinaryField non è un numero esadecimale valido nell'intervallo 0-FF.

Commenti

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 puntata a RequiredSize. Se la funzione ha esito positivo in questo caso, il valore restituito è un valore diverso da zero. In caso contrario, il valore restituito è zero e le informazioni di errore estese possono essere ottenute chiamando GetLastError.

Per comprendere meglio il funzionamento di questa funzione, considerare la riga seguente da un file INF.

X=34,FF,00,13

Se SetupGetBinaryField è stato chiamato nella riga precedente, i valori binari 34, FF, 00 e 13 verranno inseriti nel buffer specificato da ReturnBuffer.

Per la versione Unicode di questa funzione, le dimensioni del buffer ReturnBufferSize e RequiredSize vengono specificate nel numero di caratteri. Questo numero include il terminatore Null . Per la versione ANSI di questa funzione, le dimensioni vengono specificate nel numero di byte.

È quindi 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.

Requisiti


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