4.8 Enumerating the MADCAP Client in a Multicast Scope

In this example, the DHCP server has assigned 120 IPv4 multicast address leases to MADCAP clients from a specific DHCPv4 multicast scope. This example illustrates how to enumerate the list of MADCAP clients that have been assigned an active IP address lease from a multicast scope by the DHCP server.

The client calls the RPC method R_DhcpEnumMScopeClients (section 3.2.4.14) with the following parameters:

  • An 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.

  • The name of multicast scope is set as the subnet preference. An example of an MScopeName parameter is a pointer to a WCHAR initialized with "DCHPv4 Multicast Scope Example".

  • Zero as the handle to the location in the list of MADCAP clients assigned an address from the specified scope in order to request data from the beginning of the data set.

  • The next field can be set to 1,024 bytes as the preferred maximum amount of data to return.

  • A pointer, ClientInfo, of type LPDHCP_MCLIENT_INFO_ARRAY (section 2.2.1.2.84) to a structure that contains the number of elements in the array and a pointer to an array of DHCP_MCLIENT_INFO in which the information about the MADCAP clients will be returned.

  • An allocated pointer, ClientsRead, to a DWORD that will contain the number of MADCAP clients whose information is being returned.

  • An allocated pointer, ClientsTotal, to a DWORD that will contain the number of MADCAP clients remaining that have an active IP address lease obtained from the specified multicast scope whose information is still to be returned.

The client calls the RPC method, which returns ERROR_SUCCESS and updates the following parameters:

  • The ClientInfo pointer of type LPDHCP_MCLIENT_INFO_ARRAY is updated with a buffer containing 1,024 bytes of information about clients that have obtained an IP address lease from the specified multicast scope.

  • The handle to the location on the DHCP server from which the DHCP server will return data about the remaining clients whose information is still to be retrieved.

  • The ClientsRead parameter pointer to a DWORD is updated with the number of DHCP clients whose information is included in the buffer of type LPDHCP_MCLIENT_INFO_ARRAY.

  • The ClientsTotal parameter pointer to a DWORD is updated with the value (150 – ClientsRead), which is the number of clients whose information is still to be retrieved.

The client frees the memory pointed to by the pointer ClientInfo of type LPDHCP_MCLIENT_INFO_ARRAY by calling the function midl_user_free (section 3).

The client again invokes the RPC method R_DhcpEnumMScopeClients with the same parameters as before except for the following:

  • 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.

In this manner, the client can retrieve information about all the DHCP clients that have obtained an IP address lease from the specified multicast scope on the DHCP server.

Upon a successful call, after the client no longer needs the list of enumerated MADCAP clients, the client frees the memory pointed to by the pointer ClientInfo of type LPDHCP_MCLIENT_INFO_ARRAY by calling the function midl_user_free (section 3).