3.2.4.23 R_DhcpEnumOptionValuesV5 (Opnum 22)

  • Article

The R_DhcpEnumOptionValuesV5 method enumerates all the option values for the specific user class and vendor class at a specified scope defined by ScopeInfo. If the user class or the vendor class is not specified, the option values are retrieved from the default user class or vendor class. The caller of this function can free the memory pointed to by OptionValues and the Values member of OptionValues by calling the function midl_user_free (section 3).

 DWORD R_DhcpEnumOptionValuesV5(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DWORD Flags,
   [in, string, unique] WCHAR* ClassName,
   [in, string, unique] WCHAR* VendorName,
   [in] 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.

Flags: This is of type DWORD that specifies that the option values are enumerated for a specific or default vendor class.

Value

Meaning

DHCP_FLAGS_OPTION_DEFAULT

0x00000000

Option values are enumerated for a default vendor class.

DHCP_FLAGS_OPTION_IS_VENDOR

0x00000003

If a bitwise AND operation with this bitmask yields a nonzero value, it indicates that the option values are enumerated for a specific vendor class.

ClassName: A pointer to a null-terminated Unicode string that contains the name of the user class to which the option values are enumerated. This parameter is optional.

VendorName: A pointer to a null-terminated Unicode string that contains the name of the vendor class to which the option values are enumerated. This parameter is optional. If the vendor class is not specified, the option values are enumerated for a default vendor class.

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

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 PreferredMaximum 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 defined for a specific vendor and user class for a specific scope, 0xFFFFFFFF is specified.

OptionValues: This is a pointer of type LPDHCP_OPTION_VALUE_ARRAY (section 2.2.1.2.43) in which all the options values for a specific user and vendor class are enumerated at a specific DHCPv4 scope corresponding to ScopeInfo.

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

0x00004E4C

ERROR_DHCP_CLASS_NOT_FOUND

The class name being used is unknown or incorrect.

The opnum field value for this method is 22.

When processing this call, the DHCP 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.

  • The Flags parameter MUST pass one of the validations given in the Flags field description. Otherwise, the method returns ERROR_INVALID_PARAMETER.

  • If ClassName is not NULL, retrieve the DHCPv4ClassDef entry corresponding to the ClassName from the server ADM element DHCPv4ClassDefList. If the DHCPv4ClassDef entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. If ClassName is NULL, it refers to the default user class (see section 3.1.1.11).

  • If VendorName is not NULL, retrieve the DHCPv4ClassDef entry corresponding to the VendorName from the server ADM element DHCPv4ClassDefList. If the DHCPv4ClassDef entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. If VendorName is NULL, it refers to the default vendor class (see section 3.1.1.11).

  • If ScopeInfo contains DhcpDefaultOptions, iterate through the server ADM element DHCPv4OptionDefList and retrieve DHCPv4OptionDef.DHCPv4ClassedOptDefList corresponding to the user and vendor class specified by ClassName and VendorName respectively. If there is no DHCPv4OptionDef entry corresponding to the specified user and vendor classes, return ERROR_NO_MORE_ITEMS.

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

    • 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, return ERROR_NO_MORE_ITEMS.

    • If PreferredMaximum is 0 and the number of DHCPv4ClassedOptDef entries retrieved based on ScopeInfo is greater than 0, return ERROR_MORE_DATA.

    • If PreferredMaximum is 0 and the number of DHCPv4ClassedOptDef entries retrieved based on ScopeInfo is 0, 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 option values. If PreferredMaximum is unable to hold all the entries being retrieved, the server must store as many entries as will fit into the OptionValues parameter.

    • Allocate the memory for the DHCP_OPTION_VALUE_ARRAY option for the total number of DHCPv4ClassedOptDef entries available in the retrieved list starting from the index specified by ResumeHandle to the end of the option list, if PreferredMaximum is 0xFFFFFFFF or if the PreferredMaximum parameter can hold all the entries, else allocate memory for the DHCP_OPTION_VALUE_ARRAY option equal to PreferredMaximum.

    • Read the DHCPv4ClassedOptDef entries, starting from the index specified by ResumeHandle and continuing to the end of the list or to as many as can be saved in PreferredMaximum. Copy the information in the retrieved DHCPv4ClassedOptDef entries in OptionValues, copy the number of read DHCPv4ClassedOptDef entries in OptionsRead, and copy the number of the DHCPv4ClassedOptDef entries not yet enumerated in OptionsTotal. Update ResumeHandle to the index of the DHCPv4ClassedOptDef entry read plus one (+ 1).

    • If all entries in the list were copied to OptionValues, return ERROR_NO_MORE_ITEMS, else return ERROR_MORE_DATA.

  • If ScopeInfo contains DhcpGlobalOptions, iterate through the server ADM element DHCPv4ServerOptValueList and retrieve the DHCPv4OptionValue.DHCPv4ClassedOptValueList corresponding to the user and vendor class specified by ClassName and VendorName respectively. If DHCPv4OptionValue.DHCPv4ClassedOptValueList is not found, return ERROR_NO_MORE_ITEMS.

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

    • 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 DHCPv4OptionValue.DHCPv4ClassedOptValueList, return ERROR_NO_MORE_ITEMS.

    • If PreferredMaximum is 0 and the number of DHCPv4ClassedOptValue entries retrieved based on ScopeInfo is greater than 0, return ERROR_MORE_DATA.

    • If PreferredMaximum is 0 and the number of DHCPv4ClassedOptValue entries retrieved based on ScopeInfo is 0, 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 option values. If PreferredMaximum is unable to hold all the entries being retrieved, the server must store as many entries as will fit into the OptionValues parameter.

    • Allocate the memory for the DHCP_OPTION_VALUE_ARRAY option for the total number of DHCPv4ClassedOptValue entries available in the retrieved list starting from the index specified by ResumeHandle to the end of the option list, if PreferredMaximum is 0xFFFFFFFF or if the PreferredMaximum parameter can hold all the entries, else allocate memory for the DHCP_OPTION_VALUE_ARRAY option equal to PreferredMaximum.

    • Read the DHCPv4ClassedOptValue entries starting from the index specified by ResumeHandle to the end of the list or to as many as can be saved in PreferredMaximum. Copy the information in retrieved DHCPv4ClassedOptValue entries in OptionValues, copy the number of read DHCPv4ClassedOptValue entries in OptionsRead, and copy the number of DHCPv4ClassedOptValue entries not yet enumerated in OptionsTotal. Update ResumeHandle to the index of the last DHCPv4ClassedOptValue entry read plus one (+ 1).

    • If all entries in the list were copied to OptionValues, return ERROR_NO_MORE_ITEMS, else return ERROR_MORE_DATA.

  • If ScopeInfo contains DhcpSubnetOptions, retrieve the DHCPv4Scope entry corresponding to the field SubnetScopeInfo of parameter ScopeInfo from the server ADM element DHCPv4ScopesList. If the DHCPv4Scope entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.

    • Iterate through DHCPv4Scope.DHCPv4ScopeOptValuesList and retrieve DHCPv4OptionValue.DHCPv4ClassedOptValueList corresponding to the user and vendor class specified by ClassName and VendorName respectively. If DHCPv4OptionValue.DHCPv4ClassedOptValueList is not found, return ERROR_NO_MORE_ITEMS.

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

    • 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 DHCPv4OptionValue.DHCPv4ClassedOptValueList, return ERROR_NO_MORE_ITEMS.

    • If PreferredMaximum is 0 and the number of DHCPv4ClassedOptValue entries retrieved based on ScopeInfo is greater than 0, return ERROR_MORE_DATA.

    • If PreferredMaximum is 0 and the number of DHCPv4ClassedOptValue entries retrieved based on ScopeInfo is 0, 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 option values. If PreferredMaximum is unable to hold all the entries being retrieved, the server must store as many entries as will fit into the OptionValues parameter.

    • Allocate the memory for the DHCP_OPTION_VALUE_ARRAY option for the total number of DHCPv4ClassedOptValue entries available in the retrieved list starting from the index specified by ResumeHandle to the end of the option list, if PreferredMaximum is 0xFFFFFFFF or if the PreferredMaximum parameter can hold all the entries, else allocate memory for the DHCP_OPTION_VALUE_ARRAY option equal to PreferredMaximum.

    • Read the DHCPv4ClassedOptValue entries starting from the index specified by ResumeHandle to the end of the list or to as many as can be saved in PreferredMaximum. Copy the information in retrieved DHCPv4ClassedOptValue entries in OptionValues, copy the number of read DHCPv4ClassedOptValue entries in OptionsRead and copy the number of DHCPv4ClassedOptValue entries not yet enumerated in OptionsTotal. Update ResumeHandle to the index of the last DHCPv4ClassedOptValue entry read plus one (+ 1).

    • If all entries in the list were copied to OptionValues, return ERROR_NO_MORE_ITEMS, else return ERROR_MORE_DATA.

  • If ScopeInfo contains DhcpMScopeOptions, retrieve the DHCPv4MScope entry corresponding to the field MScopeInfo of parameter ScopeInfo from the server ADM element DHCPv4MScopesList. If DHCPv4MScope entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.

    • Iterate through DHCPv4MScope.DHCPv4MScopeOptValueList and retrieve DHCPv4OptionValue.DHCPv4ClassedOptValueList corresponding to the user and vendor class specified by ClassName and VendorName respectively. If the DHCPv4ClassedOptValueList is not found, return ERROR_NO_MORE_ITEMS.

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

    • 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 DHCPv4ClassedOptValueList, return ERROR_NO_MORE_ITEMS.

    • If PreferredMaximum is 0 and the number of DHCPv4ClassedOptValue entries retrieved based on ScopeInfo is greater than 0, then return ERROR_MORE_DATA.

    • If PreferredMaximum is 0 and the number of DHCPv4ClassedOptValue entries retrieved based on ScopeInfo is 0, 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 option values. If PreferredMaximum is unable to hold all the entries being retrieved, then the server must store as many entries as will fit into the OptionValues parameter.

    • Allocate the memory for the DHCP_OPTION_VALUE_ARRAY option for the total number of DHCPv4ClassedOptValue entries available in the retrieved list starting from the index specified by ResumeHandle to the end of the option list, if PreferredMaximum is 0xFFFFFFFF or if the PreferredMaximum parameter can hold all the entries, else allocate memory for the DHCP_OPTION_VALUE_ARRAY option equal to PreferredMaximum.

    • Read the DHCPv4ClassedOptValue entries starting from the index specified by ResumeHandle to the end of the list or to as many as can be saved in PreferredMaximum. Copy the information in retrieved DHCPv4ClassedOptValue entries in OptionValues, copy the number of read DHCPv4ClassedOptValue entries in OptionsRead, and copy the number of DHCPv4ClassedOptValue entries not yet enumerated in OptionsTotal. Update ResumeHandle to the index of the last DHCPv4ClassedOptValue entry read plus one (+ 1).

    • If all entries in the list were copied to OptionValues, return ERROR_NO_MORE_ITEMS, else return ERROR_MORE_DATA.

  • If ScopeInfo contains DhcpReservedOptions, retrieve the DHCPv4Scope entry from the server ADM element DHCPv4ScopesList that contains the ReservedIpAddress field of the ScopeInfo parameter. Retrieve the DHCPv4Reservation entry from DHCPv4Scope.DHCPv4ReservationsList corresponding to the ReservedIpAddress.

    • If the ReservedIpAddress is not part of any of the DHCPv4Scope, or if there is no DHCPv4Reservation corresponding to the ReservedIpAddress, return ERROR_DHCP_NOT_RESERVED_CLIENT.

    • If the DHCPv4Scope entry is found, and if ScopeInfo.SubnetAddress does not match with ScopeInfo's ReservedIpSubnetAddress field, return ERROR_DHCP_SUBNET_NOT_PRESENT.

    • Iterate through DHCPv4Reservation.DHCPv4ResvOptValuesList and retrieve DHCPv4OptionValue.DHCPv4ClassedOptValuesList corresponding to the user and vendor class specified by ClassName and VendorName respectively. If DHCPv4OptionValue.DHCPv4ClassedOptValueList is not found, return ERROR_NO_MORE_ITEMS.

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

    • 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 DHCPv4OptionValue.DHCPv4ClassedOptValueList, return ERROR_NO_MORE_ITEMS.

    • If PreferredMaximum is 0 and the number of DHCPv4ClassedOptValue entries retrieved based on ScopeInfo is greater than 0, return ERROR_MORE_DATA.

    • If PreferredMaximum is 0 and the number of DHCPv4ClassedOptValue entries retrieved based on ScopeInfo is 0, 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 option values. If PreferredMaximum is unable to hold all the entries being retrieved, the server must store as many entries as will fit into the OptionValues parameter.

    • Allocate the memory for the DHCP_OPTION_VALUE_ARRAY option for the total number of DHCPv4ClassedOptValue entries available in the retrieved list starting from the index specified by ResumeHandle to the end of the option list, if PreferredMaximum is 0xFFFFFFFF or if the PreferredMaximum parameter can hold all the entries, else allocate memory for the DHCP_OPTION_VALUE_ARRAY option equal to PreferredMaximum.

    • Read the DHCPv4ClassedOptValue entries starting from index specified by ResumeHandle to the end of the list or to as many as can be saved in PreferredMaximum. Copy the information in retrieved DHCPv4ClassedOptValue entries in OptionValues, copy the number of read DHCPv4ClassedOptValue entries in OptionsRead, and copy the number of DHCPv4ClassedOptValue entries not yet enumerated in OptionsTotal. Update ResumeHandle to the index of the last DHCPv4ClassedOptValue entry read plus one (+ 1).

    • If all entries in the list were copied to OptionValues, return ERROR_NO_MORE_ITEMS, else return ERROR_MORE_DATA.