gp

Documentation

Overview

Package gp contains Group Policy-related functions and types.

Index

• Variables
• func RefreshMachinePolicy(force bool) error
• func RefreshUserPolicy(token windows.Token, force bool) error
• type ChangeWatcher
  • func NewChangeWatcher(scope Scope, handler func()) (*ChangeWatcher, error)
  • func (w *ChangeWatcher) Close() error
• type PolicyLock
  • func NewMachinePolicyLock() *PolicyLock
  • func NewUserPolicyLock(token windows.Token) (*PolicyLock, error)
  • func (l *PolicyLock) Close() error
  • func (l *PolicyLock) Lock() error
  • func (l *PolicyLock) Unlock()
• type Scope

Variables

var (
	// ErrInvalidLockState is returned by (*PolicyLock).Lock if the lock has a zero value or has already been closed.
	ErrInvalidLockState = errors.New("the lock has not been created or has already been closed")
)

Functions

func RefreshMachinePolicy

func RefreshMachinePolicy(force bool) error

RefreshUserPolicy triggers a machine policy refresh, but does not wait for it to complete. When the force parameter is true, it causes the Group Policy to reapply policy even if no policy change was detected.

func RefreshUserPolicy

func RefreshUserPolicy(token windows.Token, force bool) error

RefreshUserPolicy triggers a user policy refresh, but does not wait for it to complete. When the force parameter is true, it causes the Group Policy to reapply policy even if no policy change was detected.

The token indicates user whose policy should be refreshed. If specified, the token must be either a primary token with TOKEN_QUERY and TOKEN_DUPLICATE access, or an impersonation token with TOKEN_QUERY and TOKEN_IMPERSONATE access, and the specified user must be logged in interactively.

Otherwise, a zero token value indicates the current user. It should not be used by services or other applications running under system identities.

The function fails with windows.ERROR_ACCESS_DENIED if the user represented by the token is not logged in interactively at the time of the call.

Types

type ChangeWatcher

type ChangeWatcher struct {
	// contains filtered or unexported fields
}

ChangeWatcher calls the handler whenever a policy in the specified scope changes.

func NewChangeWatcher

func NewChangeWatcher(scope Scope, handler func()) (*ChangeWatcher, error)

NewChangeWatcher creates an instance of ChangeWatcher that invokes handler every time Windows notifies it of a group policy change in the specified scope.

func (*ChangeWatcher) Close

func (w *ChangeWatcher) Close() error

Close unsubscribes from further Group Policy notifications, waits for any running handlers to complete, and releases any remaining resources associated with w.

type PolicyLock

type PolicyLock struct {
	// contains filtered or unexported fields
}

PolicyLock allows pausing the application of policy to safely read Group Policy settings. A PolicyLock is an R-lock that can be held by multiple readers simultaneously, preventing the Group Policy Client service (which maintains its W-counterpart) from modifying policies while they are being read.

It is not possible to pause group policy processing for longer than 10 minutes. If the system needs to apply policies and the lock is being held for more than that, the Group Policy Client service will release the lock and continue policy processing.

To avoid deadlocks when acquiring both machine and user locks, acquire the user lock before the machine lock.

func NewMachinePolicyLock

func NewMachinePolicyLock() *PolicyLock

NewMachinePolicyLock creates a PolicyLock that facilitates pausing the application of computer policy. To avoid deadlocks when acquiring both machine and user locks, acquire the user lock before the machine lock.

func NewUserPolicyLock

func NewUserPolicyLock(token windows.Token) (*PolicyLock, error)

NewUserPolicyLock creates a PolicyLock that facilitates pausing the application of the user policy for the specified user. To avoid deadlocks when acquiring both machine and user locks, acquire the user lock before the machine lock.

The token indicates which user's policy should be locked for reading. If specified, the token must have TOKEN_DUPLICATE access, the specified user must be logged in interactively. and the caller retains ownership of the token.

Otherwise, a zero token value indicates the current user. It should not be used by services or other applications running under system identities.

func (*PolicyLock) Close

func (l *PolicyLock) Close() error

Close releases resources associated with l. It is a no-op for the machine policy lock.

func (*PolicyLock) Lock

func (l *PolicyLock) Lock() error

Lock locks l. It returns ErrNotInitialized if l has a zero value or has already been closed, or an Errno if the underlying Group Policy lock cannot be acquired.

As a special case, it fails with windows.ERROR_ACCESS_DENIED if l is a user policy lock, and the corresponding user is not logged in interactively at the time of the call.

func (*PolicyLock) Unlock

func (l *PolicyLock) Unlock()

Unlock unlocks l. It panics if l is not locked on entry to Unlock.

type Scope

type Scope int

Scope is a user or machine policy scope.

const (
	// MachinePolicy indicates a machine policy.
	// Registry-based machine policies reside in HKEY_LOCAL_MACHINE.
	MachinePolicy Scope = iota
	// UserPolicy indicates a user policy.
	// Registry-based user policies reside in HKEY_CURRENT_USER of the corresponding user.
	UserPolicy
)