Funzione DhcpRequestParams (dhcpcsdk.h)

Articolo
08/23/2023

La funzione DhcpRequestParams consente ai chiamanti di ottenere in modo sincrono i dati DHCP da un server DHCP in modo sincrono o sincrono.

Sintassi

DWORD DhcpRequestParams(
  [in]      DWORD                 Flags,
  [in]      LPVOID                Reserved,
  [in]      LPWSTR                AdapterName,
  [in]      LPDHCPCAPI_CLASSID    ClassId,
  [in]      DHCPCAPI_PARAMS_ARRAY SendParams,
  [in, out] DHCPCAPI_PARAMS_ARRAY RecdParams,
  [in]      LPBYTE                Buffer,
  [in, out] LPDWORD               pSize,
  [in]      LPWSTR                RequestIdStr
);

Parametri

[in] Flags

Flag che specificano i dati richiesti. Questo parametro è facoltativo e, I valori possibili seguenti sono supportati e non si escludono a vicenda:

Valore	Significato
DHCPCAPI_REQUEST_PERSISTENT	La richiesta viene salvata in modo permanente, ma non viene recuperata alcuna opzione.
DHCPCAPI_REQUEST_SYNCHRONOUS	Le opzioni verranno recuperate dal server.

[in] Reserved

Riservato per utilizzi futuri. Deve essere impostato su NULL.

[in] AdapterName

GUID dell'adattatore in cui vengono eseguiti i dati richiesti. Deve contenere meno di 256 caratteri.

[in] ClassId

Identificatore di classe (ID) da usare se i messaggi DHCP INFORM vengono trasmessi alla rete. Questo parametro è facoltativo e,

[in] SendParams

Dati facoltativi da richiedere, oltre ai dati richiesti nella matrice RecdParams . Il parametro SendParams non può contenere alcuna delle opzioni standard inviate dal client DHCP per impostazione predefinita.

[in, out] RecdParams

Matrice di dati DHCP che il chiamante è interessato a ricevere. Questa matrice deve essere vuota prima della chiamata di funzione DhcpRequestParams .

[in] Buffer

Buffer usato per archiviare i dati associati alle richieste effettuate in RecdParams.

[in, out] pSize

Dimensioni del buffer.

Dimensioni necessarie del buffer, se non sono sufficienti per contenere i dati, in caso contrario indica le dimensioni del buffer che è stato riempito correttamente.

[in] RequestIdStr

Identificatore applicazione (ID) usato per facilitare una richiesta permanente. Deve essere una stringa stampabile senza caratteri speciali (non è possibile utilizzare virgole, barre rovesciata, due punti o altri caratteri non validi). L'identificatore di applicazione specificato (ID) viene usato in una successiva chiamata di funzione DhcpUndoRequestParams per cancellare la richiesta permanente, se necessario.

Valore restituito

Restituisce ERROR_SUCCESS al completamento.

Al termine della restituzione, RecdParams viene riempito con puntatori ai dati richiesti, con i dati corrispondenti inseriti in Buffer. Se pSize indica che Buffer ha spazio insufficiente per archiviare i dati restituiti, la funzione DhcpRequestParams restituisce ERROR_MORE_DATA e restituisce le dimensioni del buffer necessarie in pSize. Si noti che le dimensioni necessarie di Buffer possono aumentare durante il tempo trascorso tra la restituzione della chiamata di funzione iniziale e una chiamata successiva; pertanto, la dimensione richiesta di Buffer (indicata in pSize) fornisce un'indicazione delle dimensioni approssimative necessarie di Buffer, invece di garantire che le chiamate successive vengano restituite correttamente se Buffer è impostato sulla dimensione indicata in pSize.

Altri errori restituiscono i codici di errore di Windows appropriati.

Codice restituito	Descrizione
ERROR_INVALID_PARAMETER	Restituito se il parametro AdapterName ha una lunghezza superiore a 256 caratteri.
ERROR_BUFFER_OVERFLOW	Restituito se il parametro AdapterName ha una lunghezza superiore a 256 caratteri.

Commenti

I client DHCP archiviano i dati ottenuti da un server DHCP nella cache locale. Se la cache del client DHCP contiene tutti i dati richiesti nella matrice RecdParams di una chiamata di funzione DhcpRequestParams , il client restituisce i dati dalla cache. Se i dati richiesti non sono disponibili nella cache client, il client elabora la chiamata di funzione DhcpRequestParams inviando un messaggio DHCP-INFORM al server DHCP.

Quando il client invia un messaggio DHCP-INFORM al server DHCP, include tutte le richieste fornite nel parametro Facoltativo SendParams e fornisce l'identificatore di classe (ID) specificato nel parametro ClassId , se specificato.

I client possono anche specificare che i dati DHCP vengano recuperati dal server DHCP ogni volta che il client DHCP viene avviato, considerato una richiesta persistente. Per abilitare le richieste persistenti, il chiamante deve specificare il parametro RequestIdStr e specificare anche il flag di DHCPAPI_REQUEST_PERSISTENT aggiuntivo nel parametro dwFlags . Questa funzionalità di richiesta permanente è particolarmente utile quando i client devono richiedere automaticamente informazioni critiche dall'applicazione in ogni avvio. Per disabilitare una richiesta persistente, i client devono chiamare la funzione .

Nota I chiamanti di questa API non devono effettuare chiamate bloccanti a questa API, perché possono essere necessari fino a un massimo di 2 minuti per restituire un codice o uno stato. I comportamenti dell'interfaccia utente in particolare non devono bloccarsi sulla restituzione di questa chiamata, perché può introdurre un ritardo significativo nel tempo di risposta dell'interfaccia utente.

Per altre informazioni sui messaggi DHCP INFORM e altre informazioni basate su standard su DHCP, vedere Standard DHCP.

Per visualizzare la funzione DhcpRequestParams in uso, vedere Esempi DHCP.

Requisiti


Client minimo supportato	Windows 2000 Professional [app desktop \| App UWP]
Server minimo supportato	Windows 2000 Server [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	dhcpcsdk.h
Libreria	Dhcpcsvc.lib
DLL	Dhcpcsvc.dll

Vedi anche

Funzioni DHCP

DHCPCAPI_PARAMS_ARRAY

DhcpCApiInitialize

DhcpUndoRequestParams

Condividi tramite