winAPI package

Subpackages

Submodules

winAPI._displayTracking module

Tracking was introduced so that NVDA has a mechanism to announce changes to the device orientation.

When the display resolution changes, the new height and width is sent to NVDA, and we notify the user of changes to the orientation.

class winAPI._displayTracking.Orientation(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

PORTRAIT = 1
LANDSCAPE = 2
class winAPI._displayTracking.OrientationState(width: int, height: int, style: winAPI._displayTracking.Orientation)

Bases: object

width: int
height: int
style: Orientation
winAPI._displayTracking.initialize()

The NVDA message window only handles changes of state. As such, to correctly ignore an initial display change event, which does not change the orientation style (e.g. monitor change), we fetch the primary display orientation manually.

winAPI._displayTracking.getPrimaryDisplayOrientation() OrientationState
winAPI._displayTracking._getOrientationStyle(height: int, width: int) Orientation
winAPI._displayTracking._getNewOrientationStyle(previousState: OrientationState, height: int, width: int) Orientation | None

@returns: Orientation if there has been an orientation state change, otherwise None

winAPI._displayTracking.reportScreenOrientationChange(heightWidth: int) None

Reports the screen orientation only if the screen orientation has changed.

winAPI._powerTracking module

Tracking was introduced so that NVDA has a mechanism to announce changes to the power state.

When NVDA receives a power status change Window Message, we notify the user of the power status. The power status can also be reported using script_say_battery_status.

class winAPI._powerTracking.PowerBroadcast(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

APM_POWER_STATUS_CHANGE = 10

Notifies applications of a change in the power status of the computer, such as a switch from battery power to A/C. The system also broadcasts this event when remaining battery power slips below the threshold specified by the user or if the battery power changes by a specified percentage. A window receives this event through the WM_POWERBROADCAST message. https://docs.microsoft.com/en-us/windows/win32/power/pbt-apmpowerstatuschange

APM_RESUME_AUTOMATIC = 18

Operation is resuming automatically from a low-power state. This message is sent every time the system resumes.

APM_RESUME_SUSPEND = 7

Operation is resuming from a low-power state. This message is sent after APM_RESUME_AUTOMATIC if the resume is triggered by user input, such as pressing a key.

APM_SUSPEND = 4

System is suspending operation.

POWER_SETTING_CHANGE = 32787

A power setting change event has been received.

class winAPI._powerTracking.BatteryFlag(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntFlag

HIGH = 1

More than 66%

LOW = 2

Less than 33%

CRITICAL = 4

Less than 5%

NO_SYSTEM_BATTERY = 128
UNKNOWN = 255
class winAPI._powerTracking.PowerState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntFlag

AC_OFFLINE = 0
AC_ONLINE = 1
UNKNOWN = 255
class winAPI._powerTracking.SystemPowerStatus

Bases: Structure

_fields_ = [('ACLineStatus', <class 'ctypes.c_byte'>), ('BatteryFlag', <class 'ctypes.c_byte'>), ('BatteryLifePercent', <class 'ctypes.c_byte'>), ('Reserved1', <class 'ctypes.c_byte'>), ('BatteryLifeTime', <class 'ctypes.c_ulong'>), ('BatteryFullLiveTime', <class 'ctypes.c_ulong'>)]
BatteryFlag: BatteryFlag

Structure/Union member

ACLineStatus: PowerState

Structure/Union member

BatteryLifePercent: int

Structure/Union member

BatteryLifeTime: int

Structure/Union member

BatteryFullLiveTime

Structure/Union member

Reserved1

Structure/Union member

winAPI._powerTracking.initialize()

The NVDA message window only handles changes of state. As such, to correctly ignore an initial power change event, which does not change the power state (e.g. a battery level drop), we fetch the initial power state manually.

class winAPI._powerTracking._ReportContext(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Used to determine the order of information, based on relevance to the user, when announcing power status information

AC_STATUS_CHANGE = 1

e.g. a charger is connected/disconnected

FETCH_STATUS = 2

e.g. when a user presses nvda+shift+b to fetch the current battery status

winAPI._powerTracking.reportACStateChange() None
winAPI._powerTracking.reportCurrentBatteryStatus() None
winAPI._powerTracking._reportPowerStatus(context: _ReportContext) None

@param context: the context is used to order the announcement. When the context is AC_STATUS_CHANGE, this reports the current AC status first. When the context is FETCH_STATUS, this reports the remaining battery life first.

winAPI._powerTracking._getPowerStatus() SystemPowerStatus | None
winAPI._powerTracking._getSpeechForBatteryStatus(systemPowerStatus: SystemPowerStatus | None, context: _ReportContext, oldPowerState: PowerState) List[str]
winAPI._powerTracking._getACStatusText(systemPowerStatus: SystemPowerStatus) str
winAPI._powerTracking._getBatteryInformation(systemPowerStatus: SystemPowerStatus) List[str]

winAPI._wtsApi32 module

Definitions for the (Windows API) WTS Api32 Reference: https://github.com/microsoft/win32metadata/blob/main/generation/WinSDK/RecompiledIdlHeaders/um/WtsApi32.h

This file refers to this header with the convention WtsApi32.h#L36 meaning line 36 of the above link.

winAPI._wtsApi32.WTS_CURRENT_SERVER_HANDLE = c_void_p(None)

WTS_CURRENT_SERVER_HANDLE WtsApi32.h#L36

winAPI._wtsApi32.WTS_CURRENT_SESSION = c_ulong(4294967295)

WTS_CURRENT_SESSION WtsApi32.h#L42

winAPI._wtsApi32.WTSFreeMemory: Callable[[c_void_p], None] = <_FuncPtr object>

WtsApi32.h#L1245

class winAPI._wtsApi32.WTS_INFO_CLASS(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

WtsApi32.h#L322

WTSInitialProgram = 0
WTSApplicationName = 1
WTSWorkingDirectory = 2
WTSOEMId = 3
WTSSessionId = 4
WTSUserName = 5
WTSWinStationName = 6
WTSDomainName = 7
WTSConnectState = 8
WTSClientBuildNumber = 9
WTSClientName = 10
WTSClientDirectory = 11
WTSClientProductId = 12
WTSClientHardwareId = 13
WTSClientAddress = 14
WTSClientDisplay = 15
WTSClientProtocolType = 16
WTSIdleTime = 17
WTSLogonTime = 18
WTSIncomingBytes = 19
WTSOutgoingBytes = 20
WTSIncomingFrames = 21
WTSOutgoingFrames = 22
WTSClientInfo = 23
WTSSessionInfo = 24
WTSSessionInfoEx = 25
WTSConfigInfo = 26
WTSValidationInfo = 27
WTSSessionAddressV4 = 28
WTSIsRemoteSession = 29
winAPI._wtsApi32.WTS_CONNECTSTATE_CLASS

A value of the WTS_CONNECTSTATE_CLASS enumeration type that specifies the connection state of a Remote Desktop Services session.

winAPI._wtsApi32.WINSTATIONNAME_LENGTH = 32

WtsApi32.h#L81

winAPI._wtsApi32.DOMAIN_LENGTH = 17

WtsApi32.h#L82

winAPI._wtsApi32.USERNAME_LENGTH = 20

WtsApi32.h#L60

class winAPI._wtsApi32.WTSINFOEX_LEVEL1_W

Bases: Structure

WtsApi32.h#L443 https://learn.microsoft.com/en-us/windows/win32/api/wtsapi32/ns-wtsapi32-wtsinfoex_level1_w

_fields_ = (('SessionId', <class 'ctypes.c_ulong'>), ('SessionState', <class 'ctypes.c_long'>), ('SessionFlags', <class 'ctypes.c_long'>), ('WinStationName', <class 'winAPI._wtsApi32.c_wchar_Array_33'>), ('UserName', <class 'winAPI._wtsApi32.c_wchar_Array_21'>), ('DomainName', <class 'winAPI._wtsApi32.c_wchar_Array_18'>), ('LogonTime', <class 'ctypes.c_longlong'>), ('ConnectTime', <class 'ctypes.c_longlong'>), ('DisconnectTime', <class 'ctypes.c_longlong'>), ('LastInputTime', <class 'ctypes.c_longlong'>), ('CurrentTime', <class 'ctypes.c_longlong'>), ('IncomingBytes', <class 'ctypes.c_ulong'>), ('OutgoingBytes', <class 'ctypes.c_ulong'>), ('IncomingFrames', <class 'ctypes.c_ulong'>), ('OutgoingFrames', <class 'ctypes.c_ulong'>), ('IncomingCompressedBytes', <class 'ctypes.c_ulong'>), ('OutgoingCompressedBytes', <class 'ctypes.c_ulong'>))
SessionFlags: c_long

Structure/Union member

ConnectTime

Structure/Union member

CurrentTime

Structure/Union member

DisconnectTime

Structure/Union member

DomainName

Structure/Union member

IncomingBytes

Structure/Union member

IncomingCompressedBytes

Structure/Union member

IncomingFrames

Structure/Union member

LastInputTime

Structure/Union member

LogonTime

Structure/Union member

OutgoingBytes

Structure/Union member

OutgoingCompressedBytes

Structure/Union member

OutgoingFrames

Structure/Union member

SessionId

Structure/Union member

SessionState

Structure/Union member

UserName

Structure/Union member

WinStationName

Structure/Union member

class winAPI._wtsApi32.WTSINFOEX_LEVEL_W

Bases: Union

WtsApi32.h#L483 https://learn.microsoft.com/en-us/windows/win32/api/wtsapi32/ns-wtsapi32-wtsinfoex_level_w

_fields_ = (('WTSInfoExLevel1', <class 'winAPI._wtsApi32.WTSINFOEX_LEVEL1_W'>),)
WTSInfoExLevel1: WTSINFOEX_LEVEL1_W

Structure/Union member

class winAPI._wtsApi32.WTSINFOEXW

Bases: Structure

WtsApi32.h#L491 https://learn.microsoft.com/en-us/windows/win32/api/wtsapi32/ns-wtsapi32-wtsinfoexw

_fields_ = (('Level', <class 'ctypes.c_ulong'>), ('Data', <class 'winAPI._wtsApi32.WTSINFOEX_LEVEL_W'>))
Level: c_ulong

Structure/Union member

Data: WTSINFOEX_LEVEL_W

Structure/Union member

class winAPI._wtsApi32._WTS_LockState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

WtsApi32.h#L437

WTS_SESSIONSTATE_UNKNOWN = 4294967295

The session state is not known.

WTS_SESSIONSTATE_LOCK = 0

The session is locked.

WTS_SESSIONSTATE_UNLOCK = 1

The session is unlocked.

class winAPI._wtsApi32._WTS_LockState_Win7(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Provide consistent interface to work around defect in Windows Server 2008 R2 and Windows 7. Due to a code defect in Windows 7/Server 2008 the values are reversed. That is: - _WTS_LockState.WTS_SESSIONSTATE_LOCK (0x0) indicates that the session is unlocked - _WTS_LockState.WTS_SESSIONSTATE_UNLOCK (0x1) indicates the session is locked.

WTS_SESSIONSTATE_UNKNOWN = 4294967295

The session state is not known.

WTS_SESSIONSTATE_LOCK = 1

The session is locked.

WTS_SESSIONSTATE_UNLOCK = 0

The session is unlocked.

winAPI._wtsApi32._setWTS_LockState() _WTS_LockState

Ensure that the correct values for WTS_SESSIONSTATE_LOCK are used based on the platform.

winAPI._wtsApi32.WTS_LockState

Set of known session states that NVDA can handle. These values are different on different versions of Windows.

In some cases, other states such as -0x1 are returned when queried (#14379). Generally, WTSINFOEX_LEVEL1_W.SessionFlags returns a flag state. This means that the following is a valid state according to the winAPI: WTS_SESSIONSTATE_UNKNOWN | WTS_SESSIONSTATE_LOCK | WTS_SESSIONSTATE_UNLOCK. As mixed states imply an unknown state, _WTS_LockStateT is an IntEnum rather than an IntFlag and mixed state flags are unexpected enum values.

winAPI.constants module

winAPI.constants.IS_64_BIT_WINDOWS: bool = False

True if the Windows copy is 64bit

class winAPI.constants.HResult(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

S_OK = 0
E_ACCESS_DENIED = 2147942405
E_INVALID_ARG = 2147942487
class winAPI.constants.SystemErrorCodes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

SUCCESS = 0
ACCESS_DENIED = 5
INVALID_DATA = 13
NOT_READY = 21
INVALID_PARAMETER = 87
MOD_NOT_FOUND = 126
CANCELLED = 1223

winAPI.dpiAwareness module

winAPI.dpiAwareness.setDPIAwareness() None

Different versions of Windows inconsistently support different styles of DPI Awareness. This function attempts to set process DPI awareness using the most modern Windows API method available.

Only call this function once per instance of NVDA.

Only call this function when running from source. It is recommended that you set the process-default DPI awareness via application manifest. Setting the process-default DPI awareness via these API calls can lead to unexpected application behavior.

winAPI.messageWindow module

A submodule for NVDA’s message window, used for handling Window Messages.

Message windows can be used to handle communications from other processes, new NVDA instances and Windows.

winAPI.messageWindow.pre_handleWindowMessage = <extensionPoints.Action object>

Notifies when a window message has been received by NVDA. This allows components to perform an action when certain system events occur, such as power, screen orientation and hardware changes.

Handlers are called with three arguments. @param msg: The window message. @type msg: int @param wParam: Additional message information. @type wParam: int @param lParam: Additional message information. @type lParam: int

class winAPI.messageWindow.WindowMessage(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

DISPLAY_CHANGE = 126

WM_DISPLAYCHANGE

https://docs.microsoft.com/en-us/windows/win32/gdi/wm-displaychange

POWER_BROADCAST = 536

WM_POWERBROADCAST

An application should process this event by calling the GetSystemPowerStatus function to retrieve the current power status of the computer. In particular, the application should check the ACLineStatus, BatteryFlag, BatteryLifeTime, and BatteryLifePercent members of the SYSTEM_POWER_STATUS structure for any changes.

This event can occur when battery life drops to less than 5 minutes, or when the percentage of battery life drops below 10 percent, or if the battery life changes by 3 percent.

https://docs.microsoft.com/en-us/windows/win32/power/pbt-apmpowerstatuschange

WTS_SESSION_CHANGE = 689

WM_WTSSESSION_CHANGE

Windows Message for when a Session State Changes.

class winAPI.messageWindow._MessageWindow(*args, **kwargs)

Bases: CustomWindow

Constructor. @param windowName: The name of the window. @param windowStyle: The style of the window.

This is a combination of the C{winUser.WS_*} constants.

@param extendedWindowStyle: The extended style of the window.

This is a combination of the C{winUser.WS_EX_*} constants.

@param parent: The handle of the parent window, if any. @raise WindowsError: If an error occurs.

_abc_impl = <_abc._abc_data object>
className: str = 'wxWindowClassNR'

#3763: In wxPython 3, the class name of frame windows changed from wxWindowClassNR to wxWindowNR. NVDA uses the main frame to check for and quit another instance of NVDA. To remain compatible with older versions of NVDA, create our own wxWindowClassNR. We don’t need to do anything else because wx handles WM_QUIT for all windows.

windowProc(hwnd: int, msg: int, wParam: int, lParam: int) None

@param hwnd @param msg: The window message. @param wParam: Additional message information. @param lParam: Additional message information.

handleWindowMessage(msg: int, wParam: int, lParam: int) None

@param msg: The window message. @param wParam: Additional message information. @param lParam: Additional message information.

winAPI.secureDesktop module

winAPI.secureDesktop.post_secureDesktopStateChange = <extensionPoints.Action object>

Used to indicate that the user has switched to/from the secure desktop. This is triggered when Windows notification EVENT_SYSTEM_DESKTOPSWITCH notifies that the desktop has changed.

This occurs when NVDA is running on a user profile, then enters a secure screen, such as the sign-in screen or UAC dialog. If NVDA is installed and allowed to run on these screens, a new instance of NVDA will start. A user instance of NVDA cannot read the contents of the secure screen, so NVDA should enter sleep mode while it is active.

Usage: ``` def onSecureDesktopChange(isSecureDesktop: bool):

‘’’ @param isSecureDesktop: True if the new desktop is the secure desktop. ‘’’ pass

post_secureDesktopStateChange.register(onSecureDesktopChange) # Later, when no longer needed: post_secureDesktopStateChange.unregister(onSecureDesktopChange) ```

winAPI.secureDesktop._handleSecureDesktopChange()

winAPI.sessionTracking module

Session tracking was introduced so that NVDA has a mechanism to track activation of the Windows lock screen. This is required to support the privacy and data integrity of the logged in user. NVDA restricts access to NVDA settings and certain tools while the system is locked, and prevents navigating beyond apps open on the lock screen (LockScreen.exe, Magnifier, some notifications).

Used to: - only allow a whitelist of safe scripts to run - ensure object navigation cannot occur outside of the lockscreen

winAPI.sessionTracking.RPC_S_INVALID_BINDING = 1702

Error which occurs when Windows is not ready to register session notification tracking. This error can be prevented by waiting for the event: ‘GlobalTermSrvReadyEvent.’

Unused in NVDA core.

winAPI.sessionTracking.NOTIFY_FOR_THIS_SESSION = 0

The alternative to NOTIFY_FOR_THIS_SESSION is to be notified for all user sessions. NOTIFY_FOR_ALL_SESSIONS is not required as NVDA runs on separate user profiles, including the system profile.

Unused in NVDA core.

winAPI.sessionTracking.SYNCHRONIZE = 1048576

Parameter for OpenEventW, blocks thread until event is registered. https://docs.microsoft.com/en-us/windows/win32/sync/synchronization-object-security-and-access-rights

Unused in NVDA core, duplicate of winKernel.SYNCHRONIZE.

winAPI.sessionTracking._lockStateTracker: _WindowsLockedState | None = None

Caches the Windows lock state as an auto property object.

winAPI.sessionTracking._wasLockedPreviousPumpAll = False

Each core pump cycle, the Windows lock state is updated. The previous value is tracked, so that changes to the lock state can be detected.

class winAPI.sessionTracking.WindowsTrackedSession(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

Windows Tracked Session notifications. Members are states which form logical pairs, except SESSION_REMOTE_CONTROL which requires more complex handling. Values from: https://learn.microsoft.com/en-us/windows/win32/termserv/wm-wtssession-change Context: https://docs.microsoft.com/en-us/windows/win32/api/wtsapi32/nf-wtsapi32-wtsregistersessionnotification

Unused in NVDA core.

CONSOLE_CONNECT = 1
CONSOLE_DISCONNECT = 2
REMOTE_CONNECT = 3
REMOTE_DISCONNECT = 4
SESSION_LOGON = 5
SESSION_LOGOFF = 6
SESSION_LOCK = 7
SESSION_UNLOCK = 8
SESSION_REMOTE_CONTROL = 9
SESSION_CREATE = 10
SESSION_TERMINATE = 11
class winAPI.sessionTracking._WindowsLockedState(*args, **kwargs)

Bases: AutoPropertyObject

Class to encapsulate caching the Windows lock state.

_cache_isWindowsLocked = True
isWindowsLocked: bool
_get_isWindowsLocked() bool
_abc_impl = <_abc._abc_data object>
winAPI.sessionTracking.initialize()
winAPI.sessionTracking.pumpAll()

Used to track the session lock state every core cycle, and detect changes.

winAPI.sessionTracking._isWindowsLocked() bool
winAPI.sessionTracking.isLockScreenModeActive() bool

Checks if the Window lock screen is active. Not to be confused with the Windows sign-in screen, a secure screen. Includes temporary locked desktops, such as the PIN workflow reset and the Out Of Box Experience.

winAPI.sessionTracking._isWindowsLocked_checkViaSessionQuery() bool

Use a session query to check if the session is locked @returns: True is the session is locked. Also returns False if the lock state can not be determined via a Session Query.

winAPI.sessionTracking._WTS_INFO_POINTER_T

alias of LP_WTSINFOEXW

winAPI.sessionTracking.WTSCurrentSessionInfoEx() Generator[LP_WTSINFOEXW, None, None]

Context manager to get the WTSINFOEXW for the current server/session or raises a RuntimeError. Handles freeing the memory when usage is complete. @raises RuntimeError: On failure

winAPI.sessionTracking._getCurrentSessionInfoEx() LP_WTSINFOEXW | None

Gets the WTSINFOEXW for the current server/session or raises a RuntimeError on failure. On RuntimeError memory is first freed. In other cases use WTSFreeMemory. Ideally use the WTSCurrentSessionInfoEx context manager which will handle freeing the memory. @raises RuntimeError: On failure

winAPI.sessionTracking._getSessionLockedValue() _WTS_LockState

Get the WTS_LockState for the current server/session. @raises RuntimeError: if fetching the session info fails.

winAPI.types module