3.2.4.79 R_DhcpGetOptionValueV6 (Opnum 78)

  • Article

The R_DhcpGetOptionValueV6 method retrieves the option value for a specific option on the DHCPv6 server for specific user and vendor class. ScopeInfo defines the scope from which the option value needs to be retrieved. The caller of this function can free the memory pointed by OptionValue by calling the function midl_user_free (section 3).

 DWORD R_DhcpGetOptionValueV6(
     [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,
     [in]    LPDHCP_OPTION_SCOPE_INFO6 ScopeInfo,
     [out]      LPDHCP_OPTION_VALUE OptionValue
 );

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

Flags: A value that indicates if the option whose value is retrieved is for a specific vendor class or default vendor class.

Value

Meaning

DHCP_FLAGS_OPTION_DEFAULT

0x00000000

Option value is retrieved for the 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 value is retrieved for the specified 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 value is being requested. 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 value is being requested. If the vendor class is not specified, the default vendor class is used.

ScopeInfo: This is a pointer to a DHCP_OPTION_SCOPE_INFO6 (section 2.2.1.2.30) that contains information describing the DHCPv6 scope this option value is retrieved on. This value defines that option is being retrieved from the default, server, or scope level or for an IPv6 reservation.

OptionValue: This is a pointer of type LPDHCP_OPTION_VALUE in which the option value is retrieved corresponding to OptionID. For dynamic DNS update settings, see section 3.3.2.

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.

0x00004E25

ERROR_DHCP_SUBNET_NOT_PRESENT

The specified subnet is not defined on the DHCP server.

0x00004E2A

ERROR_DHCP_OPTION_NOT_PRESENT

The specified option is not defined at the specified level in the DHCP server.

0x00004E32

ERROR_DHCP_NOT_RESERVED_CLIENT

The reserved IPv6 client is not defined on the DHCP server.

The opnum field value for this method is 78.

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 parameter 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, it refers to the default user class (section 3.1.1.17).

  • 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, it refers to the default vendor class (section 3.1.1.17).

  • Allocate memory for the OptionValue parameter equal to the size of the DHCP_OPTION_VALUE structure.

  • If the enumeration in the ScopeInfo parameter is DhcpDefaultOptions6, retrieve the DHCPv6ClassedOptionDef object from DHCPv6ClassedOptionDefList for the specified user class and vendor class. If the object is not found, free the memory allocated to OptionValue, and return ERROR_DHCP_OPTION_NOT_PRESENT.

  • If the enumeration in the ScopeInfo parameter is DhcpDefaultOptions6, fill the OptionValue parameter with the OptionId, OptVal, and OptValLen fields of the DHCPv6ClassedOptionDef object retrieved, and return ERROR_SUCCESS to the caller.

  • If the enumeration in the ScopeInfo parameter is DhcpGlobalOptions6, retrieve the DHCPv6ClassedOptValue object from the DHCPv6ServerClassedOptValueList corresponding to the specific user class and vendor class. If it is not found, free the memory allocated to OptionValue, and return ERROR_FILE_NOT_FOUND.<71>

  • If the enumeration in the ScopeInfo parameter is DhcpGlobalOptions6, retrieve the DHCPv6OptionValue object corresponding to the OptionID parameter from DHCPv6ClassedOptValue.DHCPv6OptionValueList. If it is not found, free the memory allocated to OptionValue, and return ERROR_FILE_NOT_FOUND.

  • If the enumeration value in the ScopeInfo parameter is DhcpScopeOptions6, retrieve the DHCPv6Scope object from DHCPv6ScopeList corresponding to ScopeInfo parameter. If the corresponding entry is not present, free the memory allocated to OptionValue, and return ERROR_DHCP_SUBNET_NOT_PRESENT.

  • If the enumeration value in the ScopeInfo parameter is DhcpScopeOptions6, retrieve the DHCPv6ClassedOptValue object from DHCPv6Scope.DHCPv6ScopeClassedOptValueList corresponding to the specific user class and vendor class. If it is not found, free the memory allocated to OptionValue, and return ERROR_FILE_NOT_FOUND.

  • If the enumeration value in the ScopeInfo parameter is DhcpScopeOptions6, retrieve the DHCPv6OptionValue object corresponding to the OptionID parameter from DHCPv6ClassedOptValue.DHCPv6OptionValueList. If it is not found, free the memory allocated to OptionValue, and return ERROR_FILE_NOT_FOUND.

  • If ScopeInfo parameter contains DhcpReservedOptions6 enumeration value, retrieve the DHCPv6Scope object and then retrieve the DHCPv6Scope.DHCPv6ReservationList.DHCPv6Reservation object corresponding to ScopeInfo parameter. If the corresponding DHCPv6Scope object or the corresponding DHCPv6Reservation object is not present, free the memory allocated to OptionValue, and return ERROR_DHCP_NOT_RESERVED_CLIENT.

  • If ScopeInfo parameter contains DhcpReservedOptions6 enumeration value, retrieve the DHCPv6ClassedOptValue object from DHCPv6Reservation.DHCPv6ResvClassedOptValueList corresponding to the specific user class and vendor class. If it is not found, free the memory allocated to OptionValue, and return ERROR_FILE_NOT_FOUND.

  • If ScopeInfo parameter contains DhcpReservedOptions6 enumeration value, retrieve the DHCPv6OptionValue object corresponding to the OptionID parameter from DHCPv6ClassedOptValue.DHCPv6OptionValueList. If it is not found, free the memory allocated to OptionValue, and return ERROR_FILE_NOT_FOUND.

  • Fill the information in the retrieved DHCPv6OptionValue object into the OptionValue parameter, and return ERROR_SUCCESS to the caller.

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