winutil

Documentation

Overview

Package winutil contains misc Windows/Win32 helper functions.

Index

• Constants
• Variables
• func CreateAppMutex(name string) (windows.Handle, error)
• func DeleteRegValue(name string) error
• func EnableCurrentThreadPrivilege(name string) error
• func GetDesktopPID() (uint32, error)
• func GetPolicyInteger(name string) (uint64, error)
• func GetPolicyString(name string) (string, error)
• func GetRegInteger(name string) (uint64, error)
• func GetRegString(name string) (string, error)
• func GetRegStrings(name string, defval []string) []string
• func IsCurrentProcessElevated() bool
• func IsSIDValidPrincipal(uid string) bool
• func LogSvcState(logf logger.Logf, rootSvcName string)
• func LookupPseudoUser(uid string) (*user.User, error)
• func OpenKeyWait(k registry.Key, path RegistryPath, access uint32) (registry.Key, error)
• func RegisterForRestart(opts RegisterForRestartOpts) error
• func SetRegStrings(name string, values []string) error
• func StartProcessAsChild(parentPID uint32, exePath string, extraEnv []string) error
• func StartProcessAsCurrentGUIUser(exePath string, extraEnv []string) error
• func WTSGetActiveConsoleSessionId() uint32
• type RegisterForRestartOpts
• type RegistryPath
• type RegistryPathPrefix
  • func (p RegistryPathPrefix) WithSuffix(suf string) RegistryPath
• type UserSIDs
  • func GetCurrentUserSIDs() (*UserSIDs, error)

Constants

const (
	IPv4TCPIPBase RegistryPath = `SYSTEM\CurrentControlSet\Services\Tcpip\Parameters`
	IPv6TCPIPBase RegistryPath = `SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters`
	NetBTBase     RegistryPath = `SYSTEM\CurrentControlSet\Services\NetBT\Parameters`

	IPv4TCPIPInterfacePrefix RegistryPathPrefix = `SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\Interfaces\`
	IPv6TCPIPInterfacePrefix RegistryPathPrefix = `SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters\Interfaces\`
	NetBTInterfacePrefix     RegistryPathPrefix = `SYSTEM\CurrentControlSet\Services\NetBT\Parameters\Interfaces\Tcpip_`
)

const RegBase = regBase

RegBase is the registry path inside HKEY_LOCAL_MACHINE where registry settings are stored. This constant is a non-empty string only when GOOS=windows.

Variables

var ErrKeyWaitTimeout = errors.New("timeout waiting for registry key")

ErrKeyWaitTimeout is returned by OpenKeyWait when calls timeout.

var ErrNoShell = errors.New("no Shell process is present")

ErrNoShell is returned when the shell process is not found.

var ErrNoValue = registry.ErrNotExist

ErrNoValue is returned when the value doesn't exist in the registry.

Functions

func CreateAppMutex

func CreateAppMutex(name string) (windows.Handle, error)

CreateAppMutex creates a named Windows mutex, returning nil if the mutex is created successfully or an error if the mutex already exists or could not be created for some other reason.

func DeleteRegValue

func DeleteRegValue(name string) error

DeleteRegValue removes a registry value in the local machine path.

func EnableCurrentThreadPrivilege

func EnableCurrentThreadPrivilege(name string) error

EnableCurrentThreadPrivilege enables the named privilege in the current thread access token.

func GetDesktopPID

func GetDesktopPID() (uint32, error)

GetDesktopPID searches the PID of the process that's running the currently active desktop. Returns ErrNoShell if the shell is not present. Usually the PID will be for explorer.exe.

func GetPolicyInteger

func GetPolicyInteger(name string) (uint64, error)

GetPolicyInteger looks up a registry value in the local machine's path for system policies, or returns 0 and the associated error. Use this function to read values that may be set by sysadmins via the MSI installer or via GPO. For registry settings that you do *not* want to be visible to sysadmin tools, use GetRegInteger instead.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return 0 and ErrNoValue. If value does not exist or another error happens, returns 0 and error.

func GetPolicyString

func GetPolicyString(name string) (string, error)

GetPolicyString looks up a registry value in the local machine's path for system policies, or returns empty string and the error. Use this function to read values that may be set by sysadmins via the MSI installer or via GPO. For registry settings that you do *not* want to be visible to sysadmin tools, use GetRegString instead.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return an empty string and ErrNoValue. If value does not exist or another error happens, returns empty string and error.

func GetRegInteger

func GetRegInteger(name string) (uint64, error)

GetRegInteger looks up a registry path in the local machine path, or returns 0 and the error.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return 0 and ErrNoValue. If value does not exist or another error happens, returns 0 and error.

func GetRegString

func GetRegString(name string) (string, error)

GetRegString looks up a registry path in the local machine path, or returns an empty string and error.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return an empty string and ErrNoValue. If value does not exist or another error happens, returns empty string and error.

func GetRegStrings

func GetRegStrings(name string, defval []string) []string

GetRegStrings looks up a registry value in the local machine path, or returns the given default if it can't.

func IsCurrentProcessElevated

func IsCurrentProcessElevated() bool

IsCurrentProcessElevated returns true when the current process is running with an elevated token, implying Administrator access.

func IsSIDValidPrincipal

func IsSIDValidPrincipal(uid string) bool

IsSIDValidPrincipal determines whether the SID contained in uid represents a type that is a valid security principal under Windows. This check helps us work around a bug in the standard library's Windows implementation of LookupId in os/user. See https://github.com/tailscale/tailscale/issues/869

This function will only work on GOOS=windows. Trying to run it on any other OS will always return false.

func LogSvcState

func LogSvcState(logf logger.Logf, rootSvcName string)

LogSvcState obtains the state of the Windows service named rootSvcName and all of its dependencies, and then emits that state to logf.

func LookupPseudoUser

func LookupPseudoUser(uid string) (*user.User, error)

LookupPseudoUser attempts to resolve the user specified by uid by checking against well-known pseudo-users on Windows. This is a temporary workaround until https://github.com/golang/go/issues/49509 is resolved and shipped.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return an error.

func OpenKeyWait

func OpenKeyWait(k registry.Key, path RegistryPath, access uint32) (registry.Key, error)

OpenKeyWait opens a registry key, waiting for it to appear if necessary. It returns the opened key, or ErrKeyWaitTimeout if the key does not appear within 20s. The caller must call Close on the returned key.

func RegisterForRestart

func RegisterForRestart(opts RegisterForRestartOpts) error

RegisterForRestart registers the current process' restart preferences with the Windows Restart Manager. This enables the OS to intelligently restart the calling executable as requested via opts. This should be called by any programs which need to be restarted by the installer post-update.

This function may be called multiple times; the opts from the most recent call will override those from any previous invocations.

This function will only work on GOOS=windows. Trying to run it on any other OS will always return nil.

func SetRegStrings

func SetRegStrings(name string, values []string) error

SetRegStrings sets a MULTI_SZ value in the in the local machine path to the strings specified by values.

func StartProcessAsChild

func StartProcessAsChild(parentPID uint32, exePath string, extraEnv []string) error

StartProcessAsChild starts exePath process as a child of parentPID. StartProcessAsChild copies parentPID's environment variables into the new process, along with any optional environment variables in extraEnv.

func StartProcessAsCurrentGUIUser

func StartProcessAsCurrentGUIUser(exePath string, extraEnv []string) error

StartProcessAsCurrentGUIUser is like StartProcessAsChild, but if finds current logged in user desktop process (normally explorer.exe), and passes found PID to StartProcessAsChild.

func WTSGetActiveConsoleSessionId

func WTSGetActiveConsoleSessionId() uint32

TODO(crawshaw): replace with x/sys/windows... one day. https://go-review.googlesource.com/c/sys/+/331909

Types

type RegisterForRestartOpts

type RegisterForRestartOpts struct {
	RestartOnCrash   bool     // When true, this program will be restarted after a crash.
	RestartOnHang    bool     // When true, this program will be restarted after a hang.
	RestartOnUpgrade bool     // When true, this program will be restarted after an upgrade.
	RestartOnReboot  bool     // When true, this program will be restarted after a reboot.
	UseCmdLineArgs   bool     // When true, CmdLineArgs will be used as the program's arguments upon restart. Otherwise no arguments will be provided.
	CmdLineArgs      []string // When UseCmdLineArgs == true, contains the command line arguments, excluding the executable name itself. If nil or empty, the arguments from the current process will be re-used.
}

RegisterForRestartOpts supplies options to RegisterForRestart.

type RegistryPath

type RegistryPath string

RegistryPath represents a path inside a root registry.Key.

type RegistryPathPrefix

type RegistryPathPrefix string

RegistryPathPrefix specifies a RegistryPath prefix that must be suffixed with another RegistryPath to make a valid RegistryPath.

func (RegistryPathPrefix) WithSuffix

func (p RegistryPathPrefix) WithSuffix(suf string) RegistryPath

WithSuffix returns a RegistryPath with the given suffix appended.

type UserSIDs

type UserSIDs struct {
	User         *windows.SID
	PrimaryGroup *windows.SID
}

UserSIDs contains the SIDs for a Windows NT token object's associated user as well as its primary group.

func GetCurrentUserSIDs

func GetCurrentUserSIDs() (*UserSIDs, error)

GetCurrentUserSIDs returns a UserSIDs struct containing SIDs for the current process' user and primary group.