Funzione SetupGetLineTextA (setupapi.h)

Articolo
03/15/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 delle applicazioni. SetupAPI continua a essere usato per l'installazione dei driver di dispositivo.

La funzione SetupGetLineText restituisce il contenuto di una riga in un file INF in un formato compatto. La riga da recuperare può essere specificata da una struttura INFCONTEXT restituita da una funzione SetupFindLineXXX o passando in modo esplicito l'handle INF, la sezione e la chiave della riga desiderata.

Sintassi

WINSETUPAPI BOOL SetupGetLineTextA(
  [in]      PINFCONTEXT Context,
  [in]      HINF        InfHandle,
  [in]      PCSTR       Section,
  [in]      PCSTR       Key,
  [in, out] PSTR        ReturnBuffer,
  [in]      DWORD       ReturnBufferSize,
  [in, out] PDWORD      RequiredSize
);

Parametri

[in] Context

Contesto per una riga in un file INF il cui testo deve essere recuperato. Questo parametro può essere NULL. Se Context è NULL, InfHandle, Section e Key devono essere specificati tutti.

[in] InfHandle

Gestire il file INF per eseguire query. Questo parametro può essere NULL. Questo parametro viene usato solo se Context è NULL. Se Context è NULL, InfHandle, Section e Key devono essere specificati tutti.

[in] Section

Puntatore a una stringa con terminazione Null che specifica la sezione che contiene il nome della chiave della riga di cui recuperare il testo. Questo parametro può essere NULL. Questo parametro viene usato solo se Context è NULL. Se Context è NULL, è necessario specificare InfHandle, Section e Key .

[in] Key

Puntatore a una stringa con terminazione Null contenente il nome della chiave la cui stringa associata deve essere recuperata. Questo parametro può essere NULL. Questo parametro viene usato solo se Context è NULL. Se Context è NULL, è necessario specificare InfHandle, Section e Key .

[in, out] ReturnBuffer

Se non è NULL, ReturnBuffer punta a un buffer in cui questa funzione restituisce il contenuto della riga. 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. Questo parametro può essere NULL.

[in] ReturnBufferSize

Dimensioni del buffer a cui punta il parametro ReturnBuffer , in caratteri. Ciò include il carattere di terminazione Null .

[in, out] RequiredSize

Se non è NULL, punta a una variabile in cui questa funzione restituisce le dimensioni necessarie per il buffer a cui punta il parametro ReturnBuffer , in caratteri. Ciò include il carattere di terminazione Null . Se viene specificato ReturnBuffer e le dimensioni necessarie sono maggiori del valore specificato nel parametro ReturnBufferSize , la funzione ha esito negativo e non archivia i dati nel 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.

Commenti

Se questa funzione viene chiamata con returnBuffer di NULL e 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 le informazioni sull'errore estese possono essere ottenute chiamando GetLastError.

Questa funzione restituisce il contenuto di una linea in formato compatto. Tutti gli spazi vuoti estranei vengono rimossi e i valori su più righe vengono convertiti in una singola stringa contigua. Ad esempio, questa riga:

HKLM, , PointerClass0, 1 \
; This is a comment
01, 02, 03

verrebbe restituito come:

HKLM,,PointerClass0,1,01,02,03

Nota

L'intestazione setupapi.h definisce SetupGetLineText 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
Set di API	ext-ms-win-setupapi-inf-l1-1-0 (introdotto in Windows 8)