DhcpRequestParams-Funktion (dhcpcsdk.h)

  • Artikel

Mit der DhcpRequestParams-Funktion können Aufrufer DHCP-Daten synchron oder synchron und dauerhaft von einem DHCP-Server abrufen.

Syntax

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
);

Parameter

[in] Flags

Flags, die die angeforderten Daten angeben. Dieser Parameter ist optional. Die folgenden möglichen Werte werden unterstützt und schließen sich nicht gegenseitig aus:

Wert Bedeutung
DHCPCAPI_REQUEST_PERSISTENT
 Die Anforderung wird beibehalten, aber es werden keine Optionen abgerufen.
DHCPCAPI_REQUEST_SYNCHRONOUS
 Optionen werden vom Server abgerufen.

[in] Reserved

Für die zukünftige Verwendung reserviert. Muss auf NULL festgelegt werden.

[in] AdapterName

GUID des Adapters, auf dem angeforderte Daten erstellt werden. Muss unter 256 Zeichen sein.

[in] ClassId

Klassenbezeichner (ID), die verwendet werden soll, wenn DHCP-INFORM-Nachrichten in das Netzwerk übertragen werden. Dieser Parameter ist optional.

[in] SendParams

Optionale Daten, die zusätzlich zu den im RecdParams-Array angeforderten Daten angefordert werden sollen. Der Parameter SendParams kann keine der Standardoptionen enthalten, die der DHCP-Client standardmäßig sendet.

[in, out] RecdParams

Array von DHCP-Daten, an denen der Aufrufer interessiert ist. Dieses Array muss vor dem DhcpRequestParams-Funktionsaufruf leer sein.

[in] Buffer

Puffer, der zum Speichern der Daten verwendet wird, die anforderungen in RecdParams zugeordnet sind.

[in, out] pSize

Größe des Puffers.

Erforderliche Größe des Puffers, wenn er nicht ausreicht, um die Daten aufzunehmen, andernfalls gibt die Größe des Puffers an, der erfolgreich gefüllt wurde.

[in] RequestIdStr

Anwendungsbezeichner (ID), die verwendet wird, um eine persistente Anforderung zu ermöglichen. Muss eine druckbare Zeichenfolge ohne Sonderzeichen sein (Kommas, umgekehrte Schrägstriche, Doppelpunkte oder andere unzulässige Zeichen dürfen nicht verwendet werden). Der angegebene Anwendungsbezeichner (ID) wird in einem nachfolgenden DhcpUndoRequestParams-Funktionsaufruf verwendet, um die persistente Anforderung nach Bedarf zu löschen.

Rückgabewert

Gibt nach erfolgreichem Abschluss ERROR_SUCCESS zurück.

Nach der Rückgabe wird RecdParams mit Zeigern auf angeforderte Daten gefüllt, wobei die entsprechenden Daten im Puffer platziert werden. Wenn pSize angibt, dass puffer nicht über genügend Speicherplatz zum Speichern zurückgegebener Daten verfügt, gibt die DhcpRequestParams-Funktion ERROR_MORE_DATA zurück und gibt die erforderliche Puffergröße in pSize zurück. Beachten Sie, dass die erforderliche Größe von Buffer während der Zeit zwischen der Rückgabe des anfänglichen Funktionsaufrufs und einem nachfolgenden Aufruf zunehmen kann. Daher liefert die erforderliche Größe von Buffer (angegeben in pSize) einen Hinweis auf die ungefähre Erforderliche Größe von Buffer, anstatt zu gewährleisten, dass nachfolgende Aufrufe erfolgreich zurückgegeben werden, wenn Buffer auf die in pSize angegebene Größe festgelegt ist.

Andere Fehler geben entsprechende Windows-Fehlercodes zurück.

Rückgabecode Beschreibung
ERROR_INVALID_PARAMETER
 Wird zurückgegeben, wenn der AdapterName-Parameter mehr als 256 Zeichen lang ist.
ERROR_BUFFER_OVERFLOW
 Wird zurückgegeben, wenn der AdapterName-Parameter mehr als 256 Zeichen lang ist.

Hinweise

DHCP-Clients speichern Daten, die von einem DHCP-Server in ihrem lokalen Cache abgerufen wurden. Wenn der DHCP-Clientcache alle daten enthält, die im RecdParams-Array eines DhcpRequestParams-Funktionsaufrufs angefordert werden, gibt der Client Daten aus seinem Cache zurück. Wenn angeforderte Daten im Clientcache nicht verfügbar sind, verarbeitet der Client den DhcpRequestParams-Funktionsaufruf , indem er eine DHCP-INFORM-Nachricht an den DHCP-Server übermittelt.

Wenn der Client eine DHCP-INFORM-Nachricht an den DHCP-Server übermittelt, enthält er alle Anforderungen, die im optionalen SendParams-Parameter bereitgestellt werden, und stellt den im ClassId-Parameter angegebenen Klassenbezeichner (ID) bereit, sofern angegeben.

Clients können auch angeben, dass DHCP-Daten jedes Mal vom DHCP-Server abgerufen werden, wenn der DHCP-Client gestartet wird, was als persistente Anforderung gilt. Um persistente Anforderungen zu aktivieren, muss der Aufrufer den Parameter RequestIdStr und auch das zusätzliche DHCPAPI_REQUEST_PERSISTENT-Flag im dwFlags-Parameter angeben. Diese Funktion für persistente Anforderungen ist besonders nützlich, wenn Clients bei jedem Start automatisch anwendungskritische Informationen anfordern müssen. Um eine Persistenzanforderung zu deaktivieren, müssen Clients die Funktion aufrufen.

Hinweis Die Aufrufer dieser API dürfen keine blockierenden Aufrufe an diese API ausführen, da es maximal 2 Minuten dauern kann, bis ein Code oder eine status zurückgegeben wird. Insbesondere das Verhalten der Benutzeroberfläche sollte bei der Rückgabe dieses Aufrufs nicht blockiert werden, da dies zu einer erheblichen Verzögerung der Antwortzeit der Benutzeroberfläche führen kann.
 
Weitere Informationen zu DHCP INFORM-Nachrichten und anderen standardbasierten Informationen zu DHCP finden Sie unter DHCP-Standards.

Informationen zur Verwendung der DhcpRequestParams-Funktion finden Sie unter DHCP-Beispiele.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 2000 Professional [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile dhcpcsdk.h
Bibliothek Dhcpcsvc.lib
DLL Dhcpcsvc.dll

Weitere Informationen

DHCP-Funktionen

DHCPCAPI_PARAMS_ARRAY

DhcpCApiInitialize

DhcpUndoRequestParams