desktop

Documentation

Overview

Package desktop facilitates interaction with the desktop environment and user sessions. As of 2025-02-06, it is only implemented for Windows.

Index

• Variables
• type Session
  • func (s *Session) Description() string
• type SessionID
• type SessionInitCallback
• type SessionManager
  • func NewSessionManager(logger.Logf) (SessionManager, error)
• type SessionStateCallback
• type SessionStatus
  • func (s SessionStatus) String() string

Variables

var ErrNotImplemented = errors.New("not implemented for GOOS=" + runtime.GOOS)

ErrNotImplemented is returned by NewSessionManager when it is not implemented for the current GOOS.

Types

type Session

type Session struct {
	ID     SessionID     // Identifier of the session; can be reused after the session is closed.
	Status SessionStatus // The status of the session, such as foreground or background.
	User   ipnauth.Actor // User logged into the session.
}

Session is a state of a desktop session at a given point in time.

func (*Session) Description

func (s *Session) Description() string

Description returns a human-readable description of the session.

type SessionID

type SessionID uint

SessionID is a unique identifier of a desktop session.

type SessionInitCallback

type SessionInitCallback func(session *Session) (cleanup func())

SessionInitCallback is a function that is called once per Session. It returns an optional cleanup function that is called when the session is about to be destroyed, or nil if no cleanup is needed. It is not safe to call SessionManager methods from within the callback.

type SessionManager

type SessionManager interface {
	// Init explicitly initializes the receiver.
	// Unless the receiver is explicitly initialized, it will be lazily initialized
	// on the first call to any other method.
	// It is safe to call Init multiple times.
	Init() error

	// Sessions returns a session snapshot taken at the time of the call.
	// Since sessions can be created or destroyed at any time, it may become
	// outdated as soon as it is returned.
	//
	// It is primarily intended for logging and debugging.
	// Prefer registering a [SessionInitCallback] or [SessionStateCallback]
	// in contexts requiring stronger guarantees.
	Sessions() (map[SessionID]*Session, error)

	// RegisterInitCallback registers a [SessionInitCallback] that is called for each existing session
	// and for each new session that is created, until the returned unregister function is called.
	// If the specified [SessionInitCallback] returns a cleanup function, it is called when the session
	// is about to be destroyed. The callback function is guaranteed to be called once and only once
	// for each existing and new session.
	RegisterInitCallback(cb SessionInitCallback) (unregister func(), err error)

	// RegisterStateCallback registers a [SessionStateCallback] that is called for each existing session
	// and every time the state of a session changes, until the returned unregister function is called.
	RegisterStateCallback(cb SessionStateCallback) (unregister func(), err error)

	// Close waits for all registered callbacks to complete
	// and releases resources associated with the receiver.
	Close() error
}

SessionManager is an interface that provides access to desktop sessions on the current platform. It is safe for concurrent use.

func NewSessionManager

func NewSessionManager(logger.Logf) (SessionManager, error)

NewSessionManager returns a new SessionManager for the current platform, ErrNotImplemented if the platform is not supported, or an error if the session manager could not be created.

type SessionStateCallback

type SessionStateCallback func(session *Session)

SessionStateCallback is a function that reports the initial or updated state of a Session, such as when it transitions between foreground and background. It is guaranteed to be called after all registered SessionInitCallback functions have completed, and before any cleanup functions are called for the same session. It is not safe to call SessionManager methods from within the callback.

type SessionStatus

type SessionStatus int

SessionStatus is the status of a desktop session.

const (
	// ClosedSession is a session that does not exist, is not yet initialized by the OS,
	// or has been terminated.
	ClosedSession SessionStatus = iota
	// ForegroundSession is a session that a user can interact with,
	// such as when attached to a physical console or an active,
	// unlocked RDP connection.
	ForegroundSession
	// BackgroundSession indicates that the session is locked, disconnected,
	// or otherwise running without user presence or interaction.
	BackgroundSession
)

func (SessionStatus) String

func (s SessionStatus) String() string

String implements fmt.Stringer.