Share via

3.2.4.51 R_DhcpEnumOptionsV6 (Opnum 50)

  • Article

The R_DhcpEnumOptionsV6 method enumerates the option definitions for a specific user class and vendor class at the default option level. If the user class or vendor class is not specified, the default user class or vendor class will be used. The caller of this function can free the memory pointed to by Options by calling the function midl_user_free (section 3).

 DWORD R_DhcpEnumOptionsV6(
   [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, specifying 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.

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 definitions are stored on the DHCPv6 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 option definitions for a specific user and vendor 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 DHCPv6 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.

The opnum field value for this method is 50.

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 DHCPv6ClassDef entry corresponding to the ClassName from the server ADM element DHCPv6ClassDefList. If the DHCPv6ClassDef entry is not found, return ERROR_FILE_NOT_FOUND. If ClassName is NULL, use the default user class (section 3.1.1.20) for the retrieval of DHCPv6ClassedOptionDef.

  • If VendorName is not NULL, retrieve the DHCPv6ClassDef entry corresponding to the VendorName from the server ADM element DHCPv6ClassDefList. If the DHCPv6ClassDef entry is not found, return ERROR_FILE_NOT_FOUND. If VendorName is NULL, use the default vendor class (section 3.1.1.20) for the retrieval of DHCPv6ClassedOptionDef.

  • Retrieve the DHCPv6ClassedOptionDef object from DHCPv6ClassedOptionDefList for a specific user and vendor class. If it is not found, return ERROR_FILE_NOT_FOUND.<55>

  • If DHCPv6ClassedOptionDef.DHCPv6OptionDefList is an empty list, return the error ERROR_NO_MORE_ITEMS.

  • If the ResumeHandle parameter points to 0x00000000, the enumeration MUST start from the beginning of DHCPv6OptionDefList.

  • 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 DHCPv6OptionDef objects in DHCPv6OptionDefList, then return ERROR_NO_MORE_ITEMS.

  • If PreferredMaximum is 0 and the number of DHCPv6OptionDef objects remaining in DHCPv6OptionDefList is greater than 0, then ERROR_MORE_DATA is returned.

  • If PreferredMaximum is 0 and the number of DHCPv6OptionDef objects retrieved is 0, then ERROR_NO_MORE_ITEMS is returned.

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

  • If PreferredMaximum is not 0xFFFFFFFF, allocate the memory for the DHCPv6OptionDef objects in DHCPv6OptionDefList counting from ResumeHandle. Else, if PreferredMaximum is 0xFFFFFFFF, allocate the memory for all remaining DHCPv6OptionDef ADM elements.

  • 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 DHCPv6OptionDef objects. If PreferredMaximum cannot hold all the entries being retrieved, the server must store as many entries as will fit into the Options parameter and return ERROR_MORE_DATA.

  • Start enumerating the DHCPv6OptionDef objects in DHCPv6OptionDefList from ResumeHandle, and copy them in Options until it is less than PreferredMaximum.

  • Copy the number of read entries in OptionsRead, and copy the number of entries that are not yet enumerated in OptionsTotal. Update the ResumeHandle to the index of the last entry read plus one, and return ERROR_SUCCESS.

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