DhcpRequestParams

The DhcpRequestParams function enables callers to synchronously, or synchronously and persistently obtain DHCP data from a DHCP Server.

DWORD
APIENTRY
DhcpRequestParams(
  DWORD dwFlags,
  LPVOID pReserved,
  LPWSTR pszAdapterName,
  LPDHCPCAPI_CLASSID pClassId,
  DHCPCAPI_PARAMS_ARRAY pSendParams,
  DHCPCAPI_PARAMS_ARRAY pRecdParams,
  LPBYTE pbBuffer,
  LPDWORD pdwSize,
  LPWSTR pszRequestIdStr
); 

Parameters

dwFlags

[in] Flags that specify the data being requested. Must be set to DHCPAPI_REQUEST_SYNCHRONOUS, and may optionally be set with the additional DHCPAPI_REQUEST_PERSISTENT flag. This parameter is optional.

pReserved

[in] Reserved for future use. Must be set to NULL.

pszAdapterName

[in] Name of the adapter on which requested data is being made.

pClassId

[in] Class ID that should be used if DHCP INFORM messages are being transmitted onto the network. This parameter is optional.

pSendParams

[in] Optional data to be requested, in addition to the data requested in the pRecdParams array. The pSendParams parameter cannot contain any of the standard options that the DHCP client sends by default. This parameter is optional.

pRecdParams

[in, out] Array of DHCP data the caller is interested in receiving. This array must be empty prior to the DhcpRequestParams function call.

pbBuffer

[in] Buffer used for storing the data associated with requests made in pRecdParams.

pdwSize

[in] Size of pbBuffer.

[out] Required size of the buffer, if pbBuffer is insufficiently sized to hold the data, otherwise indicates size of the successfully filled pbBuffer.

pszRequestIdStr

[in] Application Identifier (ID) used to facilitate a persistent request. Must be a printable string with no special characters (for example, commas, backslashes, colons, or other illegal characters may not be used). The specified application ID is used in a subsequent DhcpUndoRequestParams function call to clear the persistent request, as necessary.

Remarks

DHCP clients store data obtained from a DHCP server in their local cache. If the DHCP client cache contains all data requested in the pRecdParams array of a DhcpRequestParams function call, the client returns data from its cache. If requested data is not available in the client cache, the client processes the DhcpRequestParams function call by submitting a DHCP-INFORM message to the DHCP server.

When the client submits a DHCP-INFORM message to the DHCP server, it includes any requests provided in the optional pSendParams parameter, and provides the Class ID specified in the pClassId parameter, if provided.

Clients can also specify that DHCP data be retrieved from the DHCP server each time the DHCP client boots, which is considered a persistent request. To enable persistent requests, the caller must specify the pszRequestIdStr parameter, and also specify the additional DHCPAPI_REQUEST_PERSISTENT flag in the dwFlags parameter. This persistent request capability is especially useful when clients need to automatically request application-critical information at each boot. To disable a persist request, clients must call the DhcpUndoRequestParams function.

For more information about DHCP INFORM messages, and other standards-based information about DHCP, consult DHCP Standards.

To see the DhcpRequestParams function in use, see DHCP Examples.

Return Values

Returns ERROR_SUCCESS upon successful completion.

Upon return, pRecdParams is filled with pointers to requested data, with corresponding data placed in pbBuffer. If pdwSize indicates that pbBuffer has insufficient space to store returned data, the DhcpRequestParams function returns ERROR_MORE_DATA, and returns the required buffer size in pdwSize. Note that the required size of pbBuffer may increase during the time that elapses between the initial function call's return and a subsequent call; therefore, the required size of pbBuffer (indicated in pdwSize) provides an indication of the approximate size required of pbBuffer, rather than guaranteeing that subsequent calls will return successfully if pbBuffer is set to the size indicated in pdwSize.

Other errors return appropriate Win32 error codes.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Dhcpcsdk.h.
  Library: Use Dhcpcsvc.lib.

See Also

DHCP Overview, DHCP Functions, DhcpCApiInitialize, DhcpUndoRequestParams