Share via

3.2.4.2 R_DhcpSetMScopeInfo (Opnum 1)

  • Article

The R_DhcpSetMScopeInfo method creates/modifies an IPv4 multicast subnet on the MADCAP server. The behavior of this method is dependent on parameter NewScope.

 DWORD R_DhcpSetMScopeInfo(
   [in, unique, string] DHCP_SRV_HANDLE ServerIpAddress,
   [in, ref, string] LPWSTR* MScopeName,
   [in, ref] LPDHCP_MSCOPE_INFO MScopeInfo,
   [in] BOOL NewScope
 );

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

MScopeName: This is a pointer to a Unicode string that contains the name of the IPv4 multicast subnet that has to be created or modified. The size of the name is limited to MAX_PATH, including the terminating NULL character. MAX_PATH is defined as 260 characters.

MScopeInfo: This is a pointer of type LPDHCP_MSCOPE_INFO (section 2.2.1.2.71), providing the IPv4 multicast subnet information that is to be created or modified.

NewScope: This is of type BOOL. A TRUE value indicates that the IPv4 multicast subnet needs to be created, and a FALSE value indicates that the existing IPv4 multicast subnet needs to be modified.

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.

0x00004E2D

ERROR_DHCP_JET_ERROR

An error occurred while accessing the MADCAP server database.

0x00004E4E

ERROR_DHCP_SCOPE_NAME_TOO_LONG

The specified scope name is too long. The name is limited to a maximum of 256 characters.

0x00004E24

ERROR_DHCP_SUBNET_EXISTS

The specified IPv4 multicast subnet already exists.

0x00004E55

ERROR_DHCP_MSCOPE_EXISTS

The multicast scope parameters are incorrect. Either the scope already exists or its properties are inconsistent with the properties of another existing scope.

The opnum field value for this method is 1.

When processing this call, the MADCAP 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.

  • Validate the MScopeInfo and MScopeName input variables. If they are passed as NULL, return ERROR_INVALID_PARAMETER.

  • Validate the MScopeName input parameter for length. If the length (inclusive of the terminating NULL character) is greater than MAX_PATH, return ERROR_DHCP_SCOPE_NAME_TOO_LONG.

  • Validate MScopeInfo's MscopeId value. If it is 0, return ERROR_INVALID_PARAMETER.

  • If the value of NewScope is set to TRUE, create the new IPv4 multicast subnet:

    • Iterate through the server ADM element DHCPv4MScopesList and if there exists any entry corresponding to the MScopeName field of MScopeInfo input parameter or any entry corresponding to the MScopeId field of MScopeInfo input parameter, return the error ERROR_DHCP_MSCOPE_EXISTS.

    • Create a DHCPv4MScope object and insert it into the DHCPv4MScopesList. The DHCPv4MScope.MScopeInfo object is initialized with information in MScopeInfo input parameter as follows:

      • DHCPv4MScope.DHCPv4IpRangesList is set to empty list.

      • DHCPv4MScope.DHCPv4ExclusionRangesList is set to empty list.

      • DHCPv4MScope.DHCPv4ReservationsList is set to empty list.

      • DHCPv4MScope.DHCPv4MClientsList is set to empty list.

      • DHCPv4MScope.DHCPv4MScopeOptValuesList is set to empty list.

  • Return ERROR_SUCCESS.

  • If the value of NewScope is set to FALSE, modify the existing IPv4 multicast subnet:

    • Retrieve the DHCPv4MScope entry corresponding to the MScopeName from the server ADM element DHCPv4MScopesList. If the DHCPv4MScope entry is not found, return ERROR_DHCP_SUBNET_NOT_PRESENT.

    • If the MScopeInfo.MScopeId value of the retrieved DHCPv4MScope entry is different from the MscopeId field of the MScopeInfo input parameter and there exists another DHCPv4MScope entry in the DHCPv4MScopesList that has MScopeInfo.MScopeId equal to the MscopeId field of the MScopeInfo input parameter, return ERROR_DHCP_SUBNET_EXISTS.

    • If the MScopeInfo.MScopeId value of the retrieved DHCPv4MScope entry is different from the MScopeId field of the MScopeInfo input parameter and there exists no DHCHv4MScope entry in the DHCPv4MScopesList that has MScopeInfo.MScopeId equal to the MscopeId field of the MScopeInfo input parameter, then, for all the entries in the DHCPv4MClientsList, modify the DHCPv4MClient.MscopeId field.

    • If there are no entries in the DHCPv4MScope.DHCPv4MClientsList, return ERROR_NO_MORE_ITEMS. Otherwise, for all the entries in DHCPv4MClientsList, set the DHCPMClient.MScopeId to the MscopeId field of the MScopeInfo input parameter.

    • If the MScopeName parameter differs from the MScopeName field of the MScopeInfo parameter, this indicates that the IPv4 multicast subnet is to be renamed. If there exists a DHCPv4MScope entry with MScopeInfo.MScopeName matching the MScopeName field of the MScopeInfo input parameter, return ERROR_DHCP_SUBNET_EXISTS.

    • Modify this DHCPv4MScope.MScopeInfo with information from the MScopeInfo input parameter, and return ERROR_SUCCESS.

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