3.2.4.31 R_DhcpGetAllOptionValues (Opnum 30)

  • Article

The R_DhcpGetAllOptionValues method retrieves the option values for all the options configured at the DHCPv4 server from the specific scope for all user classes and vendor classes. ScopeInfo defines the scope from which this option values are retrieved. The caller of this method can free the memory pointed to by Values, its Options member, and the members of each element in the Options array, by calling the function midl_user_free (section 3).

 DWORD R_DhcpGetAllOptionValues(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in] DWORD Flags,
   [in] LPDHCP_OPTION_SCOPE_INFO ScopeInfo,
   [out] LPDHCP_ALL_OPTION_VALUES* Values
 );

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

Flags: This is of type DWORD and is reserved for future use. Currently it is not used, and any value set to this parameter will not affect the behavior of this method.

ScopeInfo: This is a pointer to a DHCP_OPTION_SCOPE_INFO (section 2.2.1.2.41) structure that contains information describing the DHCPv4 scope the option values are retrieved on. This value defines that option values are being retrieved from the default, server, multicast scope, or scope level, or for an IPv4 reservation.

Values: This is a pointer to type LPDHCP_ALL_OPTION_VALUES in which a list of vendor-specific option values and default option values 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.

0x00004E25

ERROR_DHCP_SUBNET_NOT_PRESENT

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

0x00004E32

ERROR_DHCP_NOT_RESERVED_CLIENT

The specified DHCP client is not a reserved client.

The opnum field value for this method is 30.

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.

  • If ScopeType is specified as DhcpDefaultOptions, return ERROR_INVALID_PARAMETER.

  • Allocate memory to the address pointed to by Values, which is equal to the size of the data type DHCP_ALL_OPTION_VALUES. Initialize its members as: Flags equal to zero, NumElements equal to zero, and Options equal to NULL.

  • If ScopeType is specified as DhcpGlobalOptions, retrieve the server ADM element DHCPv4ServerOptValueList.

  • If ScopeType is specified as DhcpSubnetOptions, retrieve the DHCPv4Scope entry corresponding to the ScopeInfo parameter from the server ADM element DHCPv4ScopesList. If the DHCPv4Scope entry is not present, free the memory allocated to the address pointed to by Values and return ERROR_DHCP_SUBNET_NOT_PRESENT. Otherwise retrieve DHCPv4ScopeOptValueList from the DHCPv4Scope entry.

  • If ScopeType is specified as DhcpMScopeOptions, retrieve the DHCPv4MScope entry corresponding to the ScopeInfo parameter from the server ADM element DHCPv4MScopesList. If the DHCPv4MScope entry is not present, free the memory allocated to the address pointed to by Values and return ERROR_DHCP_SUBNET_NOT_PRESENT. Otherwise retrieve DHCPv4ScopeOptValueList from the DHCPv4MScope entry.

  • If ScopeType is specified as DhcpReservedOptions, retrieve the DHCPv4Scope entry from the server ADM element DHCPv4ScopesList that contains the ReservedIpAddress field of the ScopeInfo parameter. Retrieve the DHCPv4Reservation entry from DHCPv4Scope.DHCPv4ReservationsList corresponding to the ReservedIpAddress.

    If the ReservedIpAddress is not part of DHCPv4Scope, or if there is no DHCPv4Reservation corresponding to ReservedIpAddress, free the memory allocated to the address pointed to by Values and return ERROR_DHCP_NOT_RESERVED_CLIENT.

    If the DHCPv4Scope entry is found and if ScopeInfo.SubnetAddress does not match with ScopeInfo's ReservedIpSubnetAddress field, free the memory allocated to the address pointed to by Values and then return ERROR_DHCP_SUBNET_NOT_PRESENT.

    Retrieve DHCPv4ResvOptValueList from the DHCPv4Reservation entry.

  • Get the number of DHCPv4OptionValue objects in the retrieved list: DHCPv4ServerOptValueList, DHCPv4ScopeOptValueList, DHCPv4MScopeOptValueList, or DHCPv4ResvOptValueList. Allocate memory to Options whose size is equal to (2 * (number of DHCPv4OptionValue objects) * (size of the structure pointed to by Options)).

  • For each DHCPv4OptionValue object in the retrieved list do the following:

    • Get the first two non-filled indices in the array pointed to by Options. Set IsVendor to FALSE for the first one and to TRUE for the second one. For both of them, allocate required memory to ClassName and VendorName and copy values in DHCPv4OptionValue.UserClass and DHCPv4OptionValue.VendorClass objects into them respectively. Also allocate memory to OptionsArray whose size is equal to the size of the data type DHCP_OPTION_VALUE_ARRAY for both of them. Initialize NumElements in OptionsArray to zero and Values to NULL.

    • Go through each DHCPv4ClassedOptValue object in DHCPv4ClassedOptValueList and count the number of such objects that have OptionId less than or equal to 256. For the first non-filled index obtained above, set NumElements in OptionsArray equal to the count and allocate memory to Values in OptionArray whose size is equal to the size of the data type DHCP_OPTION_VALUE multiplied by the count. Copy the DHCPv4ClassedOptValue objects in DHCPv4ClassedOptValueList having OptionId less than or equal to 256 to OptionsArray.

    • Go through each DHCPv4ClassedOptValue object in DHCPv4ClassedOptValueList and count the number of such objects that have OptionId greater than 256. For the second non-filled index obtained above, set NumElements in OptionsArray equal to the count and allocate memory to Values in OptionArray whose size is equal to the size of the data type DHCP_OPTION_VALUE multiplied by the count. Copy the DHCPv4ClassedOptValue objects in DHCPv4ClassedOptValueList having  OptionId greater than 256 to OptionsArray.

  • Return ERROR_SUCCESS.

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