3.2.4.17 R_DhcpGetOptionInfoV5 (Opnum 16)

The R_DhcpGetOptionInfoV5 method retrieves the option definition of a specific option for a specific user class and vendor class at the default option level. If the user class or vendor class is not defined, the option definition is retrieved for the default user class or vendor class. This is an extension method of R_DhcpGetOptionInfo (section 3.1.4.11), which retrieves the option definition of a specific option for the default user and vendor class. The caller of this function can free the memory pointed to by OptionInfo by calling the function midl_user_free (see section 3).

 DWORD R_DhcpGetOptionInfoV5(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DWORD Flags,
   [in] DHCP_OPTION_ID OptionID,
   [in, string, unique] WCHAR* ClassName,
   [in, string, unique] WCHAR* VendorName,
   [out] LPDHCP_OPTION* OptionInfo
 );

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 retrieved for a specific or default vendor class.

Value

Meaning

DHCP_FLAGS_OPTION_DEFAULT

0x00000000

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

OptionID: This is of type DHCP_OPTION_ID (section 2.2.1.2.3), containing the option identifier for the option being retrieved.

ClassName: A pointer to a null-terminated Unicode string that contains the name of the user class for which the option definition is retrieved. This parameter is optional. If the ClassName parameter is not specified, the option definition is retrieved 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 retrieved. This parameter is optional, and if the vendor class name is not specified, the option definition is retrieved for the default vendor class.

OptionInfo: This is a pointer of type DHCP_OPTION (section 2.2.1.2.25) in which the option definition for the option is retrieved.

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.

0x00004E2A

ERROR_DHCP_OPTION_NOT_PRESENT

The specified option definition does not exist on DHCP server database.

0x00004E4C

ERROR_DHCP_CLASS_NOT_FOUND

The class name being used is unknown or incorrect.

The opnum field value for this method is 16.

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 vendor class (see section 3.1.1.9).

  • 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.9).

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

  • Iterate through the DHCPv4ClassedOptDefList and if there is no DHCPv4ClassedOptDef entry corresponding to the OptionID, return ERROR_DHCP_OPTION_NOT_PRESENT.

  • Allocate memory to OptionInfo, which is equal to the size of the data type DHCP_OPTION and to its members as needed by the data in the DHCPv4ClassedOptDef object. Copy the information in DHCPv4ClassedOptDef in the OptionInfo structure and return ERROR_SUCCESS to the caller.

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