3.2.4.18 R_DhcpEnumOptionsV5 (Opnum 17)

The R_DhcpEnumOptionsV5 method enumerates the option definitions for a specific user class and vendor class for the default option level. If the user class or the vendor class is not defined, the option definitions are enumerated for the default user class or vendor class. This method is an extension of the method in R_DhcpEnumOptions (section 3.1.4.24), which enumerates the option definition for a default user and vendor class. The caller of this function can free the memory pointed to by the Options parameter by calling the function midl_user_free (section 3).

 DWORD R_DhcpEnumOptionsV5(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DWORD Flags,
   [in, string, unique] WCHAR* ClassName,
   [in, string, unique] WCHAR* VendorName,
   [in, out] DHCP_RESUME_HANDLE* ResumeHandle,
   [in] DWORD PreferredMaximum,
   [out] LPDHCP_OPTION_ARRAY* Options,
   [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 definition is enumerated for a specific or default vendor class.

Value

Meaning

DHCP_FLAGS_OPTION_DEFAULT

0x00000000

Option definition is 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 definition is enumerated for a specific vendor class.

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

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

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 definition 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 definitions (in bytes) is less than this value, all option definitions are returned. To retrieve all the option definitions defined for a specific vendor and user class, 0xFFFFFFFF is specified.

Options: This is a pointer of type LPDHCP_OPTION_ARRAY that points to the location where all the option definitions for a specific user and vendor class are retrieved from the DHCPv4 server.

OptionsRead: This is a pointer to a DWORD value that specifies the number of option definitions read in Options. 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 definitions that have not yet been enumerated. The caller must allocate memory for this parameter that is 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.

0x00004E4C

ERROR_DHCP_CLASS_NOT_FOUND

The class name being used is unknown or incorrect.

The opnum field value for this method is 17.

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

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

  • 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 ClassName or VendorName is NULL, it refers to the default user class or vendor class respectively, as specified in section 3.1.1.9. If there is no DHCPv4OptionDef entry corresponding to the specified user and vendor classes, return ERROR_DHCP_CLASS_NOT_FOUND.

  • If there are no entries in the retrieved DHCPv4ClassedOptDefList, return ERROR_NO_MORE_ITEMS.

  • If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the first entry of the 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 DHCPv4ClassedOptDef entries, then return ERROR_NO_MORE_ITEMS.

  • If PreferredMaximum is 0 and the number of DHCPv4ClassedOptDef entries retrieved is greater than 0, then ERROR_MORE_DATA is returned.

  • If PreferredMaximum is 0 and the number of DHCPv4ClassedOptDef entries retrieved is 0, then ERROR_NO_MORE_ITEMS is returned.

  • If PreferredMaximum is 0xFFFFFFFF, then all the DHCPv4ClassedOptDef ADM element entries are retrieved. If the number of DHCPv4ClassedOptDef entries is 0, then ERROR_NO_MORE_ITEMS is returned.

  • The PreferredMaximum parameter specifies the maximum number of bytes of data related to option definitions that the server can allocate and return to the caller. If PreferredMaximum is not 0xFFFFFFFF, allocate the memory for the number of DHCPv4ClassedOptDef ADM element entries available in the retrieved list starting from the index specified by ResumeHandle, and which can fit in the PreferredMaximum amount of memory. Else, if PreferredMaximum is 0xFFFFFFFF, allocate the memory for all remaining DHCPv4ClassedOptDef ADM elements.

  • Start enumerating the DHCPv4ClassedOptDef entries for that specific user and vendor class from ResumeHandle, and copy them in Options until as many DHCPv4ClassedOptDef entries have been copied that PreferredMaximum memory can accommodate, or until the end of the DHCPv4ClassedOptDefList contents, whichever comes first.

  • Copy the number of DHCPv4ClassedOptDef entries read from that list in OptionsRead. Copy the number of DHCPv4ClassedOptDef entries from that list that are not yet enumerated in OptionsTotal. Update ResumeHandle to the index of the last DHCPv4ClassedOptDef plus one.

  • If all DHCPv4ClassedOptDef entries from DHCPv4ClassedOptDefList were copied to OptionsRead, return ERROR_SUCCESS. Otherwise, if the number of DHCPv4ClassedOptDef entries copied to OptionsRead was limited by PreferredMaximum, then return ERROR_MORE_DATA.

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