3.1.4.4 R_DhcpEnumSubnets (Opnum 3)

The R_DhcpEnumSubnets method enumerates IPv4 subnets configured on the DHCPv4 server. The caller of this function can free the memory pointed to by the EnumInfo parameter and its member the Elements array by calling the function midl_user_free (section 3).

 DWORD R_DhcpEnumSubnets(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in, out] DHCP_RESUME_HANDLE* ResumeHandle,
   [in] DWORD PreferredMaximum,
   [out] LPDHCP_IP_ARRAY* EnumInfo,
   [out] DWORD* ElementsRead,
   [out] DWORD* ElementsTotal
 );

ServerIpAddress: The IP address/host name of the DHCP server. This parameter is unused.

ResumeHandle: This is a pointer of type DHCP_RESUME_HANDLE (section 2.2.1.2.6), a DWORD that identifies the enumeration operation. Initially, this value MUST be set to zero, with a successful call returning the handle value used for subsequent enumeration requests. For example, if PreferredMaximum is set to 100, and 200 IPv4 subnet addresses are stored on the DHCPv4 server, the resume handle can be used after the first 100 IPv4 subnets are retrieved to obtain the next 100 on a subsequent call.

PreferredMaximum: This is of type DWORD, specifying the preferred maximum number of IPv4 subnet addresses to return. If the number of remaining unenumerated IPv4 subnets is less than this value, all the IPv4 subnets configured on DHCPv4 server are returned. To retrieve all the IPv4 subnets defined on the DHCPv4 server, 0xFFFFFFFF is specified.

EnumInfo: This is a pointer of type LPDHCP_IP_ARRAY that points to the location in which the IPv4 subnet configured on the DHCPv4 server is returned.

ElementsRead: This is a pointer to a DWORD value that specifies the number of IPv4 subnet addresses returned in EnumInfo. The caller MUST allocate memory for this parameter equal to the size of data type DWORD.

ElementsTotal: This is a pointer to a DWORD value that specifies the number of IPv4 subnets defined on the DHCPv4 server that have not yet been enumerated with respect to the resume handle that is returned. The caller MUST allocate memory for this parameter equal to the size of data type DWORD.

Return Values: A 32-bit unsigned integer value that indicates return status. A return value ERROR_SUCCESS (0x00000000) indicates that the operation was completed successfully, else it contains a Win32 error code, as specified in [MS-ERREF]. This error code value can correspond to a DHCP-specific failure, which takes a value between 20000 and 20099, or any generic failure.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The call was successful.

0x00000103

ERROR_NO_MORE_ITEMS

There are no more elements left to enumerate.

The opnum field value for this method is 3.

When processing this call, the DHCP server MUST do the following:

  • Validate that this method is authorized for read access as specified in section 3.5.4. If not, return the error ERROR_ACCESS_DENIED.

  • Retrieve all the entries in the server ADM element DHCPv4ScopesList as specified in section 3.1.1.1.

  • If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of the DHCPv4ScopesList ADM element.

  • If the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of the ResumeHandle parameter. If the ResumeHandle parameter is equal to or greater than the number of entries in the DHCPv4ScopesList ADM element, return ERROR_NO_MORE_ITEMS.

  • The PreferredMaximum parameter specifies the maximum number of IPv4 subnets that the server can allocate and assign to the output parameter EnumInfo, which will be used by the client to enumerate the IPv4 subnets.

  • If the PreferredMaximum parameter is 0, ERROR_NO_MORE_ITEMS is returned.

  • If the PreferredMaximum parameter is less than the number of remaining entries in the DHCPv4ScopesList ADM element, allocate memory for that number of subnets; otherwise, allocate memory for all remaining subnets and assign to the output parameter EnumInfo.

  • Fill the information from DHCPv4Scope ADM element entries in the EnumInfo parameter, fill numbers of read DHCPv4Scope ADM element entries in the ElementsRead parameter, and fill the numbers of DHCPv4Scope ADM element entries in the DHCPv4ScopesList ADM elements that have not been enumerated in the ElementsTotal parameter. Update the ResumeHandle parameter to the index of the last DHCPv4Scope ADM element entry read plus one.

  • Return ERROR_SUCCESS.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].