3.2.4.14 R_DhcpEnumMScopeClients (Opnum 13)

  • Article

The R_DhcpEnumMScopeClients method enumerates all MADCAP clients serviced from the specified IPv4 multicast subnet. The caller of this function can free the memory pointed to by the ClientInfo parameter and other client parameters by calling the function midl_user_free (section 3).

 DWORD R_DhcpEnumMScopeClients(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in, ref, string] LPWSTR* MScopeName,
   [in, out] DHCP_RESUME_HANDLE* ResumeHandle,
   [in] DWORD PreferredMaximum,
   [out] LPDHCP_MCLIENT_INFO_ARRAY* ClientInfo,
   [out] DWORD* ClientsRead,
   [out] DWORD* ClientsTotal
 );

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

MScopeName: This is a pointer to a Unicode string that contains the name of the multicast subnet from which IPv4 multicast subnet elements are enumerated. There is no restriction on the length of this field.

ResumeHandle: This is a pointer of type DHCP_RESUME_HANDLE (section 2.2.1.2.6) 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. This field contains the last IPv4 multicast address retrieved.

PreferredMaximum: This is of type DWORD, specifying the preferred maximum number of bytes to return. The minimum value is 1,024 bytes (1 kilobyte), and the maximum value is 65,536 bytes (64 kilobytes). If the input value is greater or less than this range, it MUST be set to the maximum or minimum value, respectively. To retrieve all the MADCAP clients serviced by a specific multicast scope, 0xFFFFFFFF is specified.

ClientInfo: This is a pointer of type LPDHCP_MCLIENT_INFO_ARRAY that points to the location that contains the MADCAP lease record array.

ClientsRead: This is a pointer to a DWORD that specifies the number of MADCAP client lease records read in ClientInfo. The caller MUST allocate memory for this parameter equal to the size of a DWORD data type.

ClientsTotal: This is a pointer to a DWORD that specifies the number of MADCAP client lease records remaining from the current position. The caller MUST allocate memory for this parameter equal to the size of a DWORD data type. For example, if there are 100 MADCAP lease record clients for an IPv4 multicast subnet, and if 10 MADCAP lease records are enumerated per call, then for the first time this would have a value of 90.<47>

Return Values: A 32-bit unsigned integer value that indicates return status. A return value of 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.

0x000000EA

ERROR_MORE_DATA

There are more elements available to enumerate.

0x00000103

ERROR_NO_MORE_ITEMS

There are no more elements left to enumerate.

0x00004E25

ERROR_DHCP_SUBNET_NOT_PRESENT

The specified IPv4 subnet does not exist.

0x00004E2D

ERROR_DHCP_JET_ERROR

An error occurred while accessing the MADCAP server database.

The opnum field value for this method is 13.

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

  • Validate if this method is authorized for read access per section 3.5.4. If not, return ERROR_ACCESS_DENIED.

  • Retrieve the DHCPv4MScope ADM element entry corresponding to the MScopeName parameter from the server ADM element DHCPv4MScopesList. If the DHCPv4MScope entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.

  • Retrieve the DHCPv4MClientsList member of the DHCPv4MScope entry corresponding to MScopeName from the server ADM element DHCPv4MScopesList.

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

  • If the ResumeHandle parameter points to 0x00000000, and there are no entries in DHCPv4MClientsList of all the DHCPv4MScope entries present in the DHCPv4MScopesList, then return ERROR_NO_MORE_ITEMS. If there are no entries in the DHCPv4MClientsList of the DHCPv4MScope entry corresponding to the specified MScopeName, but there are DHCPv4MClient entries in DHCPv4MClientsList of other DHCPv4MScope entries configured on the server, then return ERROR_SUCCESS.

  • If the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If the IPv4 address contained in ResumeHandle does not match ClientIpAddress of any DHCPv4MClient of the DHCPv4MScope entry corresponding to the MScopeName input parameter, then return ERROR_DHCP_JET_ERROR.

  • The PreferredMaximum parameter specifies the maximum number of bytes that the server can allocate and return to the caller containing the data related to the MADCAP client lease records.

  • If PreferredMaximum is less than 1024, it is assigned 1024; and if PreferredMaximum is greater than 65536, it is assigned 65536.

  • The actual number of records that correspond to a given PreferredMaximum value can be determined only at run time.

  • Allocate memory for PreferredMaximum number of bytes.

  • Copy the DHCPv4Client entry from the DHCPv4ClientsList entries in the allocated memory, and then proceed to the next record.

  • If the retrieve operation has reached the maximum number of DHCPv4MClient entries that can be accommodated in PreferredMaximum and there are still more DHCPv4MClient entries in any DHCPv4MClientsList, set ClientsTotal to the number of DHCPv4MClient entries that are not yet enumerated, and set ClientsRead to the number of DHCPv4MClient entries that are enumerated in this retrieve operation. Set ResumeHandle to the ClientIpAddress member of the last DHCPv4MClient entry read, and return ERROR_MORE_DATA.

  • If the number of bytes specified by PreferredMaximum is more than the total memory occupied by DHCPv4MClient entries, set ClientsTotal to the total number of DHCPv4MClient entries enumerated in that retrieve operation and ClientsRead to the number of DHCPv4MClient entries that are enumerated in this retrieve operation. Set ResumeHandle to 0, and return ERROR_SUCCESS.

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