3.2.4.53 R_DhcpSetOptionValueV6 (Opnum 52)

The R_DhcpSetOptionValueV6 method creates option value when called for the first time, else it modifies the option value of a specific option on the DHCPv6 server for a specific user class and vendor class. ScopeInfo defines the scope on which this option value is set. If the user class and vendor class is not provided, the default user class and vendor class is taken.

 DWORD R_DhcpSetOptionValueV6(
     [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,
     [in]    LPDHCP_OPTION_DATA OptionValue
 );

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

Flags: This is of type DWORD, specifying that the option value is set for a specific or default vendor class.

Value

Meaning

DHCP_FLAGS_OPTION_DEFAULT

0x00000000

Option definition is set/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 set/modified 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 set/modified.

ClassName: A pointer to a null-terminated Unicode string that contains the name of the user class to which the option value is being set. This parameter is optional.

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

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

OptionValue: A pointer to DHCP_OPTION_DATA (section 2.2.1.2.24) structure that contains the option value that is set for an option corresponding to the 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.

0x00004E2A

ERROR_DHCP_OPTION_NOT_PRESENT

The option to be modified does not exist.

0x00004E59

ERROR_DHCP_INVALID_PARAMETER_OPTION32

The information refresh time option value is invalid, as it is less than the minimum option value.

The opnum field value for this method is 52.

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

  • Validate if this method is authorized for read/write access per section 3.5.5. 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.

  • Validate the data pointed to by the input parameter OptionValue. If the Elements member of the DHCP_OPTION_DATA (section 2.2.1.2.24) structure is NULL or the NumElements member is 0, return 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).

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

  • If the ScopeInfo parameter contains DhcpDefaultOptions6, retrieve the DHCPv6OptionDef object corresponding to OptionID from DHCPv6ClassedOptionDef.DHCPv6OptionDefList. If it is not found, return ERROR_DHCP_OPTION_NOT_PRESENT.

  • If the option specified is Information Refresh Time Option (option identifier 32) and the value specified is less than the minimum specified ([RFC4242] section 3.1), return ERROR_DHCP_INVALID_PARAMETER_OPTION32.

  • If the ScopeInfo parameter contains DhcpGlobalOptions6 or DhcpDefaultOptions6:

    • Retrieve the DHCPv6ServerClassedOptValueList.DHCPv6ClassedOptValue object corresponding to the user class and vendor class specified. If it is not found, create a new DHCPv6ClassedOptValue object corresponding to the specified user class and vendor class.

    • Retrieve the DHCPv6OptionValue object corresponding to the OptionID parameter from DHCPv6ClassedOptValue.DHCPv6OptionValueList. If found, remove it from DHCPv6OptionValueList.

    • Add a new DHCPv6OptionValue object having DHCPv6OptionValue.OptionData equal to the OptionValue parameter.

  • If the ScopeInfo parameter contains DhcpScopeOptions6:

    • Retrieve the DHCPv6Scope object corresponding to the ScopeInfo parameter from DHCPv6ScopeList. If the corresponding DHCPv6Scope object is not defined, return ERROR_FILE_NOT_FOUND.

    • Retrieve the DHCPv6Scope.DHCPv6ScopeClassedOptValueList.DHCPv6ClassedOptValue object for the specific user and vendor class. If it is not found, create a new DHCPv6ClassedOptValue object corresponding to the specified user class and vendor class.

    • Retrieve the DHCPv6ClassedOptValue.DHCPv6OptionValueList.DHCPv6OptionValue object corresponding to the OptionID parameter. If found, remove it from DHCPv6OptionValueList.

    • Add a new DHCPv6OptionValue object having DHCPv6OptionValue.OptionData equal to Optionvalue.

  • If the ScopeInfo parameter contains DhcpReservedOptions6:

    • Retrieve the DHCPv6Scope object and the DHCPv6Scope.DHCPv6ReservationList.DHCPv6Reservation object corresponding to ScopeInfo. If the corresponding DHCPv6Scope object or the DHCPv6Reservation object is not found, return ERROR_INVALID_PARAMETER.<56>

    • Retrieve the DHCPv6Reservation.DHCPv6ResvClassedOptValueList.DHCPv6ClassedOptValue object for the specific user and vendor class. If it is not found, create a new DHCPv6ClassedOptValue object corresponding to the specified user class and vendor class.

    • Retrieve the DHCPv6ClassedOptValue.DHCPv6OptionValueList.DHCPv6OptionValue object corresponding to the OptionID parameter. If the object is found, remove it from DHCPv6OptionValueList.

    • Add a new DHCPv6OptionValue object having DHCPv6OptionValue.OptionData equal to Optionvalue.

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