IGPMSecurityInfo::Remove method (gpmgmt.h)

Article
02/22/2024

Removes the permission specified in a given GPMPermission object from the GPMSecurityInfo collection.

Syntax

HRESULT Remove(
  [in] IGPMPermission *pPerm
);

Parameters

[in] pPerm

Pointer to the GPMPermission object to remove from the collection.

Return value

JScript

Returns S_OK if successful. Returns a failure code if an error occurs.

VB

Returns S_OK if successful. Returns a failure code if an error occurs.

Remarks

You cannot remove Inherited permissions. To determine if a permission is Inherited, see IGPMPermission Property Methods.

The method checks for the existence of the specified GPMPermission object, which is the pairing of a trustee (which is a user, computer, or security group) and a permission that applies to a single object, for example, to a GPO, SOM, or WMI filter. If the object exists in the collection, the method removes it.

If the permission specified for removal represents a higher level than the permission that exists for the trustee, the method removes the lower level permission. An example of this situation is specifying the removal of the permGPOEditSecurityAndDelete permission when the trustee has the lower permGPOEdit permission instead. In this case, the method removes the permGPOEdit permission.

If the permission specified for removal represents a lower level than the permission that exists for the trustee, the method returns S_FALSE.

On successful removal of a permission, the method updates all enumerators returned by the get__NewEnum method, even if a removal occurs during the enumeration of elements.

For more information about policy-related permissions, see IGPM::CreatePermission.

For more information about security groups, see How Security Groups are Used in Access Control in the Active Directory Programmer's Guide.

Requirements

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