3.2.4.6 R_DhcpEnumMScopeElements (Opnum 5)

The R_DhcpEnumMScopeElements method enumerates the list of specific types of IPv4 multicast subnet elements (IPv4 range of IPv4 exclusion) from a specific IPv4 multicast subnet. The caller of this function can free the memory pointed to by EnumElementInfo and its member Elements by calling the function midl_user_free (section 3).

 DWORD R_DhcpEnumMScopeElements(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in, ref, string] LPWSTR* MScopeName,
   [in] DHCP_SUBNET_ELEMENT_TYPE EnumElementType,
   [in, out] DHCP_RESUME_HANDLE* ResumeHandle,
   [in] DWORD PreferredMaximum,
   [out] LPDHCP_SUBNET_ELEMENT_INFO_ARRAY_V4* EnumElementInfo,
   [out] DWORD* ElementsRead,
   [out] DWORD* ElementsTotal
 );

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.

EnumElementType: This is of type DHCP_SUBNET_ELEMENT_TYPE (section 2.2.1.1.7), indicating the type of IPv4 multicast subnet element to enumerate.

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. For example, if the PreferredMaximum parameter is set to 1,000 bytes, and 2,000 bytes' worth of IPv4 multicast subnet elements are stored on the MADCAP server, the resume handle can be used after the first 1,000 bytes are retrieved to obtain the next 1,000 on a subsequent call, and so forth.

PreferredMaximum: This is of type DWORD, specifying the preferred maximum number of bytes to return. If the number of remaining unenumerated IPv4 multicast subnet element (in bytes) is less than this value, all IPv4 subnet elements for a specific type are returned. To retrieve all the IPv4 subnet elements of a specific type, 0xFFFFFFFF is specified.

EnumElementInfo: This is a pointer of type LPDHCP_SUBNET_ELEMENT_INFO_ARRAY_V4 in which the IPv4 multicast subnet element of type EnumElementType is returned for a specific IPv4 multicast subnet corresponding to MScopeNames. If no IPv4 multicast subnet element of that specific type is available for enumeration, this value is null.

ElementsRead: This is a pointer to a DWORD value that specifies the number of IPv4 multicast subnet elements read in EnumElementInfo for a specific type of IPv4 multicast subnet element. The caller MUST allocate memory for this parameter equal to the size of a DWORD data type.

ElementsTotal: This is a pointer to a DWORD value that specifies the number of IPv4 multicast subnet elements of a specific type from a specific IPv4 multicast subnet and that is not yet enumerated with respect to the resume handle that is returned. The caller MUST allocate memory for this parameter equal to the size of a DWORD data type.

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.

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.

The opnum field value for this method is 5.

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 the error ERROR_ACCESS_DENIED.

  • If the MScopeName is NULL, return ERROR_INVALID_PARAMETER.

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

  • If the DHCPv4MScope entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.

  • If the EnumElementType field is set to DhcpSecondaryHosts, return ERROR_NOT_SUPPORTED.

  • If EnumElementType is DhcpReservedIps, DhcpIpUsedClusters, DhcpIpRangesDhcpOnly, DhcpIpRangesDhcpBootp, or DhcpIpRangesBootpOnly, return ERROR_INVALID_PARAMETER.

  • If EnumElementType is set to DhcpIpRanges, retrieve all the entries in DHCPv4MScope.DHCPv4IPRangesList starting with the DHCPv4IPRange entry at the index specified by the value in the ResumeHandle parameter and continuing while the total byte size of all retrieved DHCPv4IPRange entries is less than PreferredMaximum.

  • If EnumElementType is set to DhcpIpRanges, and if PreferredMaximum is 0, then ERROR_NO_MORE_ITEMS is returned.

  • If EnumElementType is set to DhcpIpRanges, and if the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of the DHCPv4IpRangesList.

  • If EnumElementType is set to DhcpIpRanges, and if the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If the ResumeHandle is greater than or equal to the number of entries in the DHCPv4IpRangesList, then return ERROR_NO_MORE_ITEMS.

  • 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 multicast subnet ranges. If EnumElementType is set to DhcpIpRanges, and if the PreferredMaximum is unable to hold all the entries being retrieved, then the server must store as many entries that will fit into the EnumElementInfo parameter and return ERROR_MORE_DATA.

  • If EnumElementType is set to DhcpIpRanges, copy the RangeInfo of the retrieved DHCPv4IPRange entries in EnumElementInfo, copy the number of read DHCPv4IPRange entries in ElementsRead, and copy the number of DHCPv4IpRange entries in the DHCPv4MScope.DHCPv4IpRangesList that are not yet enumerated in ElementsTotal. Update the ResumeHandle to the index of the last DHCPv4IpRange entry read plus one, and return ERROR_SUCCESS.

  • If EnumElementType is set toDhcpExcludedIpRanges, retrieve all the entries in DHCPv4MScope.DHCPv4ExclusionRangesList starting with the DHCPv4ExclusionRange entry at the index specified by the value in the ResumeHandle parameter and continuing while the total byte size of all retrieved DHCPv4ExclusionRange entries is less than PreferredMaximum.

  • If EnumElementType is set to DhcpExcludedIpRanges, and if PreferredMaximum is 0 and the number of entries in the DHCPv4ExclusionRangesList retrieved based on EnumElementType is greater than 0, then ERROR_MORE_DATA is returned.

  • If EnumElementType is set to DhcpExcludedIpRanges, and if PreferredMaximum is 0 and the number of entries in the DHCPv4ExclusionRangesList retrieved based on EnumElementType is 0, then ERROR_NO_MORE_ITEMS is returned.

  • If EnumElementType is set to DhcpExcludedIpRanges, and if the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of the DHCPv4ExclusionRangesList.

  • If EnumElementType is set to DhcpExcludedIpRanges, and if the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If the ResumeHandle is greater than or equal to the number of DHCPv4ExclusionRange entries, then return ERROR_NO_MORE_ITEMS.

  • 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 IPv4 exclusions. If EnumElementType is set to DhcpExcludedIpRanges, and if the PreferredMaximum is unable to hold all the entries being retrieved, then the server must store as many entries that will fit into the EnumElementInfo parameter and return ERROR_MORE_DATA.

  • If EnumElementType is set to DhcpExcludedIpRanges, copy the retrieved DHCPv4ExclusionRange entries in EnumElementInfo, copy the number of read DHCPv4ExclusionRange entries in ElementsRead, and copy the number of DHCPv4ExclusionRange entries in the DHCPv4MScope.DHCPv4ExclusionRangesList that are not yet enumerated in ElementsTotal. Update the ResumeHandle to the index of the last DHCPv4ExclusionRange entry read plus one, and return ERROR_SUCCESS.

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