3.2.4.78 R_DhcpEnumClassesV6 (Opnum 77)

The R_DhcpEnumClassesV6 method enumerates user or vendor classes configured for the DHCPv6 server. The caller of this function can free the memory pointed to by ClassInfoArray and its Classes member by calling the function midl_user_free (section 3).

 DWORD R_DhcpEnumClassesV6(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DWORD ReservedMustBeZero,
   [in, out] DHCP_RESUME_HANDLE* ResumeHandle,
   [in] DWORD PreferredMaximum,
   [out] LPDHCP_CLASS_INFO_ARRAY_V6* ClassInfoArray,
   [out] DWORD* nRead,
   [out] DWORD* nTotal
 );

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

ReservedMustBeZero: This is of type DWORD and SHOULD be set to 0. Currently it is not used, and any value set to this parameter will not affect the behavior of this method.

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 100 and 200 classes are stored). On the DHCPv6 server, the resume handle can be used after the first 100 classes are retrieved to obtain the next 100 on a subsequent call, and so forth.

PreferredMaximum: This is of type DWORD, specifying the preferred maximum number of bytes to be returned. If the number of bytes required in memory for the remaining unenumerated classes is less than the value of this parameter, then all the classes for the DHCPv6 server are returned. To retrieve all the classes defined on the DHCPv6 server, 0xFFFFFFFF is specified.

ClassInfoArray: This is a pointer of type LPDHCP_CLASS_INFO_ARRAY_V6 in which information of all the classes defined on the DHCPv6 server is retrieved.

nRead: This is a pointer to a DWORD value that specifies the number of classes returned in ClassInfoArray. The caller must allocate memory for this parameter that is equal to the size of data type DWORD.

nTotal: This is a pointer to a DWORD value that specifies the number of classes defined on the DHCPv6 server 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 77.

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

  • If ClassInfoArray, ResumeHandle, nRead, and nTotal are NULL, return ERROR_INVALID_PARAMETER.

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

  • Retrieve the DHCPv6ClassDefList object, and in it, start enumerating from ResumeHandle.

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

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

  • If PreferredMaximum is 0 and the number of entries remaining in DHCPv6ClassDefList is greater than 0, then ERROR_MORE_DATA is returned.

  • If PreferredMaximum is 0 and the number of entries remaining in DHCPv6ClassDefList is 0, then ERROR_NO_MORE_ITEMS is returned.

  • Allocate the memory for DHCP_CLASS_INFO_ARRAY_V6 (section 2.2.1.2.87) and for total number of DHCPv6ClassDef objects type DHCP_CLASS_INFO (section 2.2.1.2.75) from ResumeHandle to the end of DHCPv6ClassDefList.

  • 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 DHCPv6ClassDef objects. In case PreferredMaximum is 0xFFFFFFFF, the server must allocate memory for all remaining DHCPv6ClassDef objects. If PreferredMaximum is unable to hold all the entries being retrieved, the server must store as many entries as will fit into the ClassInfoArray parameter and return ERROR_MORE_DATA.

  • Read the class information from ResumeHandle to the end of DHCPv6ClassDefList, copy it into the allocated memory, and return it to the caller until the copied data length is less than PreferredMaximum.

  • Fill the number of read DHCPv6ClassDef objects in nRead, and fill the number of DHCPv6ClassDef objects in DHCPv6ClassDefList that have not yet been enumerated in nTotal. Update the ResumeHandle to the index of the last DHCPv6ClassDef object read plus one.

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