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
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.