IGPMDomain::RestoreGPO method (gpmgmt.h)

Article
10/13/2021

Restores a Group Policy object (GPO) from a GPMBackup object. You can only restore a GPO to the domain in which the GPO was originally created because the operation restores the GPO with its original GPO ID, policy settings, access control lists (ACLs), and links to Windows Management Instrumentation (WMI) filters.

Syntax

HRESULT RestoreGPO(
  [in]            IGPMBackup *pIGPMBackup,
  [in]            long       lDCFlags,
  [in, optional]  VARIANT    *pvarGPMProgress,
  [out, optional] VARIANT    *pvarGPMCancel,
  [out]           IGPMResult **ppIGPMResult
);

Parameters

[in] pIGPMBackup

Pointer to the GPMBackup object to restore.

[in] lDCFlags

Flags to use for validation. If this parameter is set to zero, the method validates the domain controller to determine whether the restore operation can be performed. If you specify GPM_DONOT_VALIDATEDC, the method does not validate the DC. This parameter is ignored for GPOs that do not include software policy settings. For more information about validation, see the "Remarks" section.

[in, optional] pvarGPMProgress

Specifies a pointer to an IGPMAsyncProgress interface that allows the client to receive status notifications about the progress of the restore operation. To receive asynchronous notifications, the caller must create this interface and then pass the interface pointer in this parameter. This parameter must be NULL if the client should not receive asynchronous notifications. The method will run asynchronously if this parameter is not NULL and will run synchronously if NULL.

[out, optional] pvarGPMCancel

Receives a pointer to an IGPMAsyncCancel interface that the client can use to cancel the restore operation. This parameter is not returned if pvarGPMProgress is NULL.

[out] ppIGPMResult

Address of a pointer to the IGPMResult interface that represents the result of the restore operation. That interface contains pointers to an IGPMGPO interface and an IGPMStatusMsgCollection interface.

Return value

C++

Returns S_OK if successful. Returns a failure code if an error occurs. Returns E_OPERATION_NOT_SUPPORTED_ONDC if the current domain controller is running an old Windows Server version and the backed-up GPO contains software policy settings.

JScript

Returns a reference to a GPMResult object.

VB

Returns a reference to a GPMResult object.

Remarks

A restore operation returns the contents of a specific GPO to the status it had when the backup was performed. A restore operation does not modify links to the GPO because they are attributes of a scope of management (SOM). A restore operation also does not modify WMI filters. However, because the link to a WMI filter is an attribute of the GPO, the restore operation restores the link to the WMI filter.

You must check the code that is returned by the IGPMResult::OverallStatus method as well as the one returned by this method to determine whether the operation succeeded. OverallStatus returns an overall status code for the operation. If no error occurred during the operation, it returns a success code. Otherwise, it returns a failure code.

As a best practice, we recommend that you validate the DC in a restore operation.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	gpmgmt.h
DLL	Gpmgmt.dll