dhcprequestParams 函数 (dhcpcsdk.h)

  • 项目

DhcpRequestParams 函数使调用方能够从 DHCP 服务器同步或同步且持久地获取 DHCP 数据。

语法

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

参数

[in] Flags

指定所请求数据的标志。 此参数是可选的。 支持以下可能的值，并且不互斥：

Value 含义
DHCPCAPI_REQUEST_PERSISTENT
 请求将持久保存，但不会提取任何选项。
DHCPCAPI_REQUEST_SYNCHRONOUS
 将从服务器中提取选项。

[in] Reserved

保留供将来使用。 必须设置为 NULL。

[in] AdapterName

正在对其生成请求数据的适配器的 GUID。 长度必须低于 256 个字符。

[in] ClassId

类标识符 (在 DHCP INFORM 消息传输到网络上时应使用的 ID) 。 此参数是可选的。

[in] SendParams

除 RecdParams 数组中请求的数据外，要请求的可选数据。 SendParams 参数不能包含 DHCP 客户端默认发送的任何标准选项。

[in, out] RecdParams

调用方想要接收的 DHCP 数据数组。 在 调用 DhcpRequestParams 函数之前，此数组必须为空。

[in] Buffer

用于存储与 RecdParams 中发出的请求关联的数据的缓冲区。

[in, out] pSize

缓冲区的大小。

缓冲区的所需大小（如果大小不足以容纳数据），否则指示已成功填充的缓冲区的大小。

[in] RequestIdStr

应用程序标识符 (ID) 用于促进持久请求。 必须是无特殊字符的可打印字符串， (逗号、反斜杠、冒号或其他非法字符不得用于) 。 指定的应用程序标识符 (ID) 在后续 DhcpUndoRequestParams 函数调用中使用，以根据需要清除永久性请求。

返回值

成功完成后返回ERROR_SUCCESS。

返回后， RecdParams 将用指向请求数据的指针填充，相应的数据放置在 Buffer 中。 如果 pSize 指示 Buffer 没有足够的空间来存储返回的数据， 则 DhcpRequestParams 函数将返回ERROR_MORE_DATA，并在 pSize 中返回所需的缓冲区大小。 请注意，在初始函数调用的返回和后续调用之间，所需的缓冲区大小可能会增加;因此，pSize) 中指示的缓冲区 (所需大小指示缓冲区所需的近似大小，而不是保证如果 Buffer 设置为 pSize 中指示的大小，后续调用将成功返回。

其他错误返回相应的 Windows 错误代码。

返回代码 说明
ERROR_INVALID_PARAMETER
 如果 AdapterName 参数的长度超过 256 个字符，则返回 。
ERROR_BUFFER_OVERFLOW
 如果 AdapterName 参数的长度超过 256 个字符，则返回 。

备注

DHCP 客户端将从 DHCP 服务器获取的数据存储在其本地缓存中。 如果 DHCP 客户端缓存包含 DhcpRequestParams 函数调用的 RecdParams 数组中请求的所有数据，则客户端会从其缓存中返回数据。 如果请求的数据在客户端缓存中不可用，则客户端通过向 DHCP 服务器提交 DHCP-INFORM 消息来处理 DhcpRequestParams 函数调用。

当客户端将 DHCP-INFORM 消息提交到 DHCP 服务器时，它将包括可选 SendParams 参数中提供的任何请求，并提供 ClassId 参数中指定的类标识符 (ID) （如果提供）。

客户端还可以指定每次 DHCP 客户端启动时从 DHCP 服务器检索 DHCP 数据，这被视为永久性请求。 若要启用永久性请求，调用方必须指定 RequestIdStr 参数，并在 dwFlags 参数中指定其他 DHCPAPI_REQUEST_PERSISTENT 标志。 当客户端需要在每次启动时自动请求应用程序关键信息时，这种持久请求功能特别有用。 若要禁用持久化请求，客户端必须调用 函数。

注意 此 API 的调用方不得对此 API 进行阻止调用，因为最多可能需要 2 分钟才能返回代码或状态。 UI 行为尤其不应阻止此调用的返回，因为它可能会显著延迟 UI 响应时间。
 
有关 DHCP INFORM 消息的详细信息，以及有关 DHCP 的其他基于标准的信息，请参阅 DHCP 标准。

若要查看正在使用的 DhcpRequestParams 函数，请参阅 DHCP 示例。

要求

   
最低受支持的客户端 Windows 2000 专业版 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows 2000 Server [桌面应用 |UWP 应用]
目标平台 Windows
标头 dhcpcsdk.h
Library Dhcpcsvc.lib
DLL Dhcpcsvc.dll

请参阅

DHCP 函数

DHCPCAPI_PARAMS_ARRAY

DhcpCApiInitialize

DhcpUndoRequestParams