3.1.4.15 R_DhcpEnumOptionValues (Opnum 14)

  • Article

The R_DhcpEnumOptionValues method enumerates all the option values for the default user class and vendor class pair. The values can be enumerated at a specified level (that is, default, server, scope, multicast scope, or reservation level) defined by the ScopeInfo parameter. The extension of this API is R_DhcpEnumOptionValuesV5 (section 3.2.4.23), which retrieves the option values for a specific user class and vendor class at a specific scope defined by the ScopeInfo parameter. The caller of this function can free the memory pointed to by the OptionValues parameter and its member the Values array by calling the function midl_user_free (section 3).

 DWORD R_DhcpEnumOptionValues(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in, ref] LPDHCP_OPTION_SCOPE_INFO ScopeInfo,
   [in, out] DHCP_RESUME_HANDLE* ResumeHandle,
   [in] DWORD PreferredMaximum,
   [out] LPDHCP_OPTION_VALUE_ARRAY* OptionValues,
   [out] DWORD* OptionsRead,
   [out] DWORD* OptionsTotal
 );

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

ScopeInfo: This is a pointer to a DHCP_OPTION_SCOPE_INFO (section 2.2.1.2.41) structure that contains information describing the level (that is, default, server, scope, multicast scope, or IPv4 reservation level) at which the option values are enumerated on.

ResumeHandle: This is a pointer of type DHCP_RESUME_HANDLE (section 2.2.1.2.6) that identifies whether the enumeration operation is a continuation of a previous 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 option values are stored on the DHCPv4 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 option values (in bytes) is less than this value, all option values are returned. To retrieve all the option values for the default user class and vendor class at the desired level, 0xFFFFFFFF is specified.

OptionValues: This is a pointer of type LPDHCP_OPTION_VALUE_ARRAY in which all the option values for the default user class and vendor class are retrieved at a specific level (that is, default, server, scope, multicast scope, or IPv4 reservation level) corresponding to the ScopeInfo parameter.

OptionsRead: This is a pointer to a DWORD value that specifies the number of option values read in the OptionValues parameter. The caller MUST allocate memory for this parameter equal to the size of data type DWORD.

OptionsTotal: This is a pointer to a DWORD value that specifies the number of option values that have not yet been read. 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.

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 on the DHCP server.

0x00004E32

ERROR_DHCP_NOT_RESERVED_CLIENT

The specified DHCP client is not a reserved client.

The opnum field value for this method is 14.

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

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

  • If the value of the ScopeType member of the ScopeInfo parameter is not as specified in DHCP_OPTION_SCOPE_TYPE (section 2.2.1.1.4), return ERROR_INVALID_PARAMETER.

  • If the ScopeInfo parameter contains DhcpDefaultOptions, iterate through the server Abstract Data Model (ADM) element DHCPv4OptionDefList, and retrieve the DHCPv4ClassedOptDefList ADM element corresponding to the DHCPv4OptionDef ADM element entry if the UserClass and VendorClass ADM element fields are NULL. If DHCPv4ClassedOptDefList ADM element is not found, return ERROR_NO_MORE_ITEMS; otherwise, read the DHCPv4ClassedOptDef ADM element entries, starting from the index specified by the ResumeHandle parameter and continuing to the end of the list.

    If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of DHCPv4ClassedOptDefList ADM element. Otherwise, if the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If ResumeHandle is greater than or equal to the number of entries in DHCPv4ClassedOptDefList ADM element, 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 DHCPv4ClassedOptDef ADM element objects retrieved. If PreferredMaximum is 0xFFFFFFFF, the server MUST allocate the memory and store all the DHCPv4ClassedOptDef ADM element entries to be retrieved. Otherwise, if the PreferredMaximum parameter is unable to hold all the entries being retrieved, then the server must allocate the PreferredMaximum number of bytes for the OptionValues parameter and store as many DHCPv4ClassedOptDef ADM element entries as will fit into the OptionValues parameter; else, allocate the memory for the DHCP_OPTION_VALUE_ARRAY for the total number of DHCPv4ClassedOptDef ADM element entries available in the retrieved list, starting from the index specified by the ResumeHandle parameter and continuing to the end of the option list.

    Copy the information in the retrieved DHCPv4ClassedOptDef ADM element entries in the OptionValues parameter, allocate memory for the output parameters OptionsRead and OptionsTotal, copy the number of read DHCPv4ClassedOptDef ADM element entries in the OptionsRead parameter, and copy the number of the DHCPv4ClassedOptDef ADM element entries not yet enumerated in the OptionsTotal parameter. Update the ResumeHandle parameter to the value obtained by adding 1 to the index of the DHCPv4ClassedOptDef ADM element entry read.

    If the PreferredMaximum parameter was able to hold all the entries being retrieved, return ERROR_NO_MORE_ITEMS, else return ERROR_MORE_DATA.

  • If the ScopeInfo parameter contains DhcpGlobalOptions, iterate through the server ADM element DHCPv4ServerOptValueList and retrieve DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element corresponding to the DHCPv4OptionValue ADM element entry if UserClass and VendorClass ADM element fields are NULL. If the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element entry is not found, return ERROR_NO_MORE_ITEMS; otherwise, read the DHCPv4ClassedOptValue ADM element entries starting from the index specified by the ResumeHandle parameter to the end of the list.

    If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element; else, if the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If ResumeHandle is greater than or equal to the number of entries in the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element, 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 DHCPv4ClassedOptDef ADM element objects retrieved. If PreferredMaximum is 0xFFFFFFFF, the server MUST allocate the memory and store all the DHCPv4ClassedOptDef ADM element entries to be retrieved. Otherwise, if the PreferredMaximum parameter is unable to hold all the entries being retrieved, then the server must allocate PreferredMaximum number of bytes for the OptionValues parameter and store as many DHCPv4ClassedOptDef ADM element entries as will fit into the OptionValues parameter; else, allocate the memory for the DHCP_OPTION_VALUE_ARRAY for the total number of DHCPv4ClassedOptDef ADM element entries available in the retrieved list, starting from the index specified by the ResumeHandle parameter and continuing to the end of the option list.

    Copy the information in retrieved DHCPv4ClassedOptValue ADM element entries in the OptionValues parameter, copy the number of read DHCPv4ClassedOptValue ADM element entries in the OptionsRead parameter, and copy the number of DHCPv4ClassedOptValue ADM element entries not yet enumerated in the OptionsTotal parameter. Update the ResumeHandle parameter to the value obtained by adding 1 to the index of the last DHCPv4ClassedOptValue ADM element entry read.

    If the PreferredMaximum parameter was able to hold all the entries being retrieved, return ERROR_NO_MORE_ITEMS, else return ERROR_MORE_DATA.

  • If the ScopeInfo parameter contains DhcpSubnetOptions, retrieve the DHCPv4Scope ADM element entry corresponding to the SubnetScopeInfo member of the ScopeInfo parameter from the server ADM element DHCPv4ScopesList. If the DHCPv4Scope ADM element entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT; otherwise, iterate through DHCPv4Scope.DHCPv4ScopeOptValuesList ADM element and retrieve DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element corresponding to the DHCPv4OptionValue ADM element entry if the UserClass and VendorClass ADM element fields are NULL. If DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element is not found, return ERROR_NO_MORE_ITEMS; otherwise, read the DHCPv4ClassedOptValue ADM element entries, starting from the index specified by the ResumeHandle parameter to the end of the list.

    If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element; otherwise, if the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If ResumeHandle is greater than or equal to the number of entries in the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element, 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 DHCPv4ClassedOptDef ADM element objects retrieved. If PreferredMaximum is 0xFFFFFFFF, the server MUST allocate the memory and store all the DHCPv4ClassedOptDef ADM element entries to be retrieved. Otherwise, if the PreferredMaximum parameter is unable to hold all the entries being retrieved, then the server must allocate PreferredMaximum number of bytes for the OptionValues parameter and store as many DHCPv4ClassedOptDef ADM element entries as will fit into the OptionValues parameter; else, allocate the memory for the DHCP_OPTION_VALUE_ARRAY for the total number of DHCPv4ClassedOptDef ADM element entries available in the retrieved list, starting from the index specified by the ResumeHandle parameter and continuing to the end of the option list.

    Copy the information in the retrieved DHCPv4ClassedOptValue ADM element entries in the OptionValues parameter, copy the number of read DHCPv4ClassedOptValue ADM element entries in the OptionsRead parameter, and copy the number of the DHCPv4ClassedOptValue ADM element entries not yet enumerated in the OptionsTotal parameter. Update the ResumeHandle parameter to the value obtained by adding 1 to the index of the last DHCPv4ClassedOptValue ADM element entry read.

    If the PreferredMaximum parameter was able to hold all the entries being retrieved, return ERROR_NO_MORE_ITEMS, else return ERROR_MORE_DATA.

  • If the ScopeInfo parameter contains DhcpMScopeOptions, retrieve the DHCPv4MScope ADM element entry corresponding to the MScopeInfo member of ScopeInfo from the server ADM element DHCPv4MScopesList ADM element. If the DHCPv4MScope ADM element entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT; otherwise, iterate through DHCPv4MScope.DHCPv4MScopeOptValueList ADM element and retrieve the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element corresponding to the DHCPv4OptionValue ADM element entry if the UserClass and VendorClass ADM element fields are NULL. If the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element is not found, return ERROR_NO_MORE_ITEMS, else read the DHCPv4ClassedOptValue ADM element entries, starting from the index specified by the ResumeHandle parameter and continuing to the end of the list.

    If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element. Otherwise, if the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If the ResumeHandle parameter is greater than or equal to the number of entries in the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element, 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 DHCPv4ClassedOptDef ADM element objects retrieved. If PreferredMaximum is 0xFFFFFFFF, the server MUST allocate the memory and store all the DHCPv4ClassedOptDef ADM element entries to be retrieved. Otherwise, if the PreferredMaximum parameter is unable to hold all the entries being retrieved, then the server must allocate the PreferredMaximum number of bytes for the OptionValues parameter and store as many DHCPv4ClassedOptDef ADM element entries as will fit into the OptionValues parameter; else, allocate the memory for the DHCP_OPTION_VALUE_ARRAY for the total number of DHCPv4ClassedOptDef ADM element entries available in the retrieved list, starting from the index specified by the ResumeHandle parameter and continuing to the end of the option list.

    Copy the information in the retrieved DHCPv4ClassedOptValue ADM element entries in the OptionValues parameter, copy the number of read DHCPv4ClassedOptValue ADM element entries in the OptionsRead parameter, and copy the number of DHCPv4ClassedOptValue ADM element entries not yet enumerated in the OptionsTotal parameter. Update the ResumeHandle parameter to the value obtained by adding 1 to the index of the last DHCPv4ClassedOptValue ADM element entry read.

    If the PreferredMaximum parameter was able to hold all the entries being retrieved, return ERROR_NO_MORE_ITEMS, else return ERROR_MORE_DATA.

  • If the ScopeInfo parameter contains DhcpReservedOptions, retrieve the DHCPv4Scope ADM element entry from the server ADM element DHCPv4ScopesList that contains the ReservedIpAddress member of the ScopeInfo parameter. If the DHCPv4Scope ADM element entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT; otherwise, if the ScopeInfo.SubnetAddress ADM element does not match the ScopeInfoReservedIpAddress member, return ERROR_DHCP_SUBNET_NOT_PRESENT. Otherwise, retrieve the DHCPv4Reservation ADM element entry from the DHCPv4Scope.DHCPv4ReservationsList ADM element corresponding to ReservedIpAddress.

    If the ReservedIpAddress member is not part of any of DHCPv4Scope ADM element, or if there is no DHCPv4Reservation ADM element corresponding to ReservedIpAddress, return ERROR_DHCP_NOT_RESERVED_CLIENT. Otherwise, iterate through DHCPv4Reservation.DHCPv4ResvOptValuesList ADM element and retrieve DHCPv4OptionValue.DHCPv4ClassedOptValuesList ADM element corresponding to the DHCPv4OptionValue ADM element entry if the UserClass and VendorClass ADM element fields are NULL. If DHCPv4OptionValue.DHCPv4ClassedOptValuesList ADM element is not found, return ERROR_NO_MORE_ITEMS. Otherwise, read the DHCPv4ClassedOptValue ADM element entries, starting from the index specified by the ResumeHandle parameter and continuing to the end of the list.

    If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element. Otherwise, if the ResumeHandle parameter points to a nonzero value, the server MUST continue enumeration based on the value of ResumeHandle. If ResumeHandle is greater than or equal to the number of entries in the DHCPv4OptionValue.DHCPv4ClassedOptValueList ADM element, 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 DHCPv4ClassedOptDef ADM element objects retrieved. If PreferredMaximum is 0xFFFFFFFF, the server MUST allocate the memory and store all the DHCPv4ClassedOptDef ADM element entries to be retrieved. Otherwise, if the PreferredMaximum parameter is unable to hold all the entries being retrieved, then the server must allocate PreferredMaximum number of bytes for the OptionValues parameter and store as many DHCPv4ClassedOptDef ADM element entries as will fit into the OptionValues parameter; else, allocate the memory for the DHCP_OPTION_VALUE_ARRAY for the total number of DHCPv4ClassedOptDef ADM element entries available in the retrieved list, starting from the index specified by ResumeHandle and continuing to the end of the option list.

    Copy the information in the retrieved DHCPv4ClassedOptValue ADM element entries in the OptionValues parameter, copy the number of read DHCPv4ClassedOptValue ADM element entries in the OptionsRead parameter, and copy the number of DHCPv4ClassedOptValue ADM element entries not yet enumerated in the OptionsTotal parameter. Update the ResumeHandle parameter to the value obtained by adding 1 to the index of the last DHCPv4ClassedOptValue ADM element entry read.

    If the PreferredMaximum parameter was able to hold all the entries being retrieved, return ERROR_NO_MORE_ITEMS, else return ERROR_MORE_DATA.

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