4.5 Querying the List of IPv4 Multicast Subnets from the DHCP Server

In this example, the DHCP server is configured with 150 IPv4 multicast scopes. The example illustrates the use of the RPC methods defined in this specification to enumerate the list of IPv4 multicast scopes configured on the DHCP server.

The client calls the RPC method R_DhcpEnumMScopes (section 3.2.4.4) with the following parameters:

  • The endpoint of the DHCP server as the server IP address. This parameter is optional and can be passed as a pointer to a null Unicode string.

  • Zero as the handle to the location within the DHCP server's data from which the RPC method will return data, in order to request data from the beginning of the data set. This can be set to zero. A successful call to the RPC method will return an updated handle to the location from which the data will be read in the next call to the RPC method.

  • One hundred as the preferred maximum number of IPv4 multicast scope addresses to return.

  • A pointer of type LPDHCP_MSCOPE_TABLE (section 2.2.1.2.72) to a structure that contains the number of elements in the array and a pointer to an array in which the scope names identifying the DHCPv4 multicast scopes configured on the server will be returned by the DHCP server.

  • An allocated pointer, the ElementsRead parameter, to a DWORD in which the number of multicast scope addresses returned by the API is returned.

  • An allocated pointer, the ElementsTotal parameter, to a DWORD in which the total number of IPv4 scopes configured on the DHCP server that are still to be returned by the RPC method is specified.

When the client calls the RPC method as described in the preceding list, it returns ERROR_SUCCESS and additionally the following parameter values are updated:

  • The pointer of type LPDHCP_MSCOPE_TABLE to a structure that contains the number of elements in the array and a pointer to an array will contain the scope names of the first 100 of the 150 IPv4 multicast scopes configured on the DHCP server.

  • The handle to the location on the DHCP server from which the DHCP server will return data in a subsequent invocation of this RPC method will be updated.

  • A DWORD, the ElementsRead parameter, containing the number of multicast scope names returned by the API; will be set to 100.

  • A DWORD, the ElementsTotal parameter, containing the total number of IPv4 multicast scopes configured on the DHCP server; is set to 50.

The client then calls the RPC method R_DhcpEnumMScopes again with the following parameters:

  • The endpoint of the DHCP server as the server IP address.

  • The updated handle received from the previous call to the RPC method is passed in as the handle to the location from which the DHCP server will return data in this invocation.

  • One hundred as the preferred maximum number of IPv4 subnet addresses to return.

  • A pointer of type LPDHCP_MSCOPE_TABLE to a structure that contains the number of elements in the array and a pointer to an array in which the scope names identifying the DHCPv4 multicast scopes configured on the server will be returned.

  • A pointer to a DWORD, the ElementsRead parameter, in which the number of scope addresses returned by the API is returned.

  • A pointer to a DWORD, the ElementsTotal parameter, in which the total number of IPv4 scopes configured on the DHCP server that are still to be returned by the RPC method is specified.

This second call to the RPC method returns ERROR_SUCCESS, and additionally the following parameter values are updated:

  • The pointer of type DHCP_MSCOPE_TABLE to a structure that contains the number of elements in the array and a pointer to an array will contain the scope names of the remaining 50 IPv4 multicast scopes configured on the DHCP server.

  • The handle to the location on the DHCP server from which the DHCP server will return data in a subsequent invocation of this RPC method will be updated to the end of the server's data set.

  • A DWORD, the ElementsRead parameter, containing the number of multicast scope names returned by the API; is set to 50.

  • A DWORD, the ElementsTotal parameter, containing the total number of IPv4 multicast scopes configured on the DHCP server; is set to 0.

If the client uses the same pointer of type LPDHCP_MSCOPE_TABLE for both calls to the RPC method R_DhcpEnumMScopes, the memory needs to be deallocated before the second call. In all cases, after the client no longer needs the list of enumerated IPv4 multicast scopes, the client frees the memory pointed to by the pointer of type LPDHCP_MSCOPE_TABLE by calling the function midl_user_free (section 3).