3.2.4.104 R_DhcpV4GetOptionValue (Opnum 103)

  • Article

The R_DhcpV4GetOptionValue method gets the option value for the specified PolicyName parameter and OptionID parameter. The memory for the OptionValue parameter is allocated by this method and can be freed by the caller by calling the function midl_user_free (section 3).

 DWORD R_DhcpV4GetOptionValue(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DWORD Flags,
   [in] DHCP_OPTION_ID OptionID,
   [in, string, unique] WCHAR* PolicyName,
   [in, string, unique] WCHAR* VendorName,
   [in] LPDHCP_OPTION_SCOPE_INFO ScopeInfo,
   [out] LPDHCP_OPTION_VALUE* OptionValue
 );

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

Value

Meaning

DHCP_FLAGS_OPTION_DEFAULT

0x00000000

The option definition is set 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 definition is set for a specific vendor class.

OptionID: This is of type DHCP_OPTION_ID data type (section 2.2.1.2.3), containing the option ID of the option being set or modified.

PolicyName: A pointer to a null-terminated Unicode string that contains the name of the policy inside the subnet identified by the SubnetScopeInfo member of the ScopeInfo parameter for which the option value is being set.

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 the vendor class is not specified, the option value is set for a default vendor class.

ScopeInfo: This is a pointer to a type DHCP_OPTION_SCOPE_INFO structure (section 2.2.1.2.41) that contains information describing the DHCPv4 scope for which this option value is set. This value contains the server or scope level at which the option values are set.

OptionValue: A pointer of type LPDHCP_OPTION_VALUE (section 2.2.1.2.42) that contains the option value that is set for an option corresponding to the OptionId parameter. For Dynamic DNS update settings, see section 3.3.1.

The method does not perform any checks to ensure that the OptionValue parameter passed in is of the same OptionType member value as that of the option corresponding to the OptionId parameter passed in. It is the responsibility of the caller to ensure that the correct OptionType member value is used for the OptionValue parameter passed in. In case the OptionType member value of the OptionValue parameter passed in is different from that of the option corresponding to the OptionId parameter, the behavior is undefined.

Return Values: A 32-bit unsigned integer value that indicates return status. A return value of ERROR_SUCCESS (0x00000000) indicates that the operation was completed successfully. Otherwise, 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 to any generic failure.

Return value/code

Description

0x00000000

ERROR_SUCCESS

The call was successful.

0x00004E25

ERROR_DHCP_SUBNET_NOT_PRESENT

The specified IPv4 subnet does not exist on the DHCP server.

0x00004E2A

ERROR_DHCP_OPTION_NOT_PRESENT

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

0x00004E4C

ERROR_DHCP_CLASS_NOT_FOUND

The class name being used is unknown or incorrect.

0x00004E8F

ERROR_DHCP_POLICY_NOT_PRESENT

The specified policy name does not exist.

The opnum field value for this method is 103.

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

  • The Flags parameter MUST pass one of the validations given in the Flags parameter description. Otherwise, the method returns ERROR_INVALID_PARAMETER.

  • If the ScopeType member in the ScopeInfo parameter is DhcpReservedOptions enumeration value or DhcpMScopeOptions enumeration value and the PolicyName parameter is not NULL, the method returns ERROR_INVALID_PARAMETER.

  • Validate whether this method is authorized for read/write access as specified in section 3.5.5. If not, return ERROR_ACCESS_DENIED.

  • Validate the data pointed to by the input parameter OptionValue. If the Elements member of the DHCP_OPTION_DATA structure is NULL or the NumElements member is 0, return ERROR_INVALID_PARAMETER.

  • If the VendorName parameter is not NULL, retrieve the DHCPv4ClassDef ADM element entry corresponding to the VendorName parameter from the server ADM element DHCPv4ClassDefList. If the DHCPv4ClassDef ADM element entry is not found, return ERROR_DHCP_CLASS_NOT_FOUND. If the VendorName parameter is NULL, it refers to the default vendor class (see section 3.1.1.11).

  • If the ScopeType member in the ScopeInfo parameter is set to DhcpDefaultOptions:

    • Iterate through the DHCPv4OptionDefList server ADM element and retrieve the DHCPv4OptionDef.DHCPv4ClassedOptDefList corresponding to the default user class and vendor class specified by the VendorName parameter.

    • If there is no DHCPv4OptionDef.DHCPv4ClassedOptDefList entry corresponding to this set of user and vendor classes, return ERROR_DHCP_OPTION_NOT_PRESENT.

    • If there is no DHCPv4ClassedOptDef entry in DHCPv4ClassedOptDefList corresponding to OptionID, return ERROR_DHCP_OPTION_NOT_PRESENT.

    • Copy the information in DHCPv4ClassedOptDef into the OptionValue parameter and return it to the caller.

  • If the ScopeType member in the ScopeInfo parameter contains the DhcpGlobalOptions enumeration value:

    • Retrieve the server ADM element DHCPv4ServerPolicyList. Retrieve the DHCPv4Policy ADM element from the DHCPv4ServerPolicyList ADM element that has the same name as the PolicyName parameter. If there is no policy with the specified name, return ERROR_DHCP_POLICY_NOT_FOUND.

    • Retrieve each DHCPv4PolicyOptionValue ADM element from the server ADM element DHCPv4ServerPolicyOptionValuesList. Get the DHCPv4PolicyOptionValue ADM element for which the DHCPv4PolicyOptionValue.PolicyName ADM element and the DHCPv4PolicyOptionValue.VendorName ADM element match the PolicyName parameter and the VendorName parameter passed to the method.

    • From the DHCPv4PolicyOptionValue.DHCPv4ClassedOptionValues ADM element list, if there is no DHCPv4ClassedOptValue ADM element that contains the same OptionID ADM element as the OptionId parameter, return ERROR_DHCP_OPTION_NOT_PRESENT.

    • If there is a DHCPv4ClassedOptValue ADM element that contains the same OptionID ADM element as the OptionId parameter passed to the method, allocate memory for a DHCP_OPTION_VALUE structure and populate the structure with the OptionID ADM element and Value ADM element in the DHCPv4ClassedOptValue ADM element. Return ERROR_SUCCESS.

  • If the ScopeType member of the ScopeInfo parameter contains the SubnetScopeInfo enumeration value:

    • Retrieve the server ADM element DHCPv4ScopesList. Retrieve the DHCPv4Scope ADM element that contains the same IP address as the IP address in the SubnetScopeInfo member. If there is no scope with the specified IP address, return ERROR_DHCP_SUBNET_NOT_PRESENT.

    • Retrieve the DHCPv4Scope.DHCPv4ScopePolicyList ADM element. Retrieve the DHCPv4Policy ADM element from the DHCPv4Scope.DHCPv4ScopePolicyList ADM element with the specified PolicyName parameter. If there is no policy with the specified name, return ERROR_DHCP_POLICY_NOT_FOUND.

    • Retrieve each DHCPv4PolicyOptionValue ADM element from the scope ADM element DHCPv4Scope.DHCPv4ScopePolicyOptionValuesList. Get the DHCPv4PolicyOptionValue ADM element for which the DHCPv4PolicyOptionValue.PolicyName ADM element and the DHCPv4PolicyOptionValue.VendorName ADM element match the PolicyName parameter and the VendorName parameter passed to the method.

    • From the DHCPv4PolicyOptionValue.DHCPv4ClassedOptionValues ADM element list, if there is no DHCPv4ClassedOptValue ADM element that contains the same OptionID ADM element as the OptionId parameter, return ERROR_DHCP_OPTION_NOT_PRESENT.

    • If there is a DHCPv4ClassedOptValue ADM element that contains the same OptionID ADM element as the OptionId parameter passed to the method, allocate memory for a DHCP_OPTION_VALUE structure and populate the structure with the OptionID ADM element and the Value ADM element in the DHCPv4ClassedOptValue ADM element.

  • Return ERROR_SUCCESS.

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