notification-state-ffi

About

Get the current state of "Focus Assist" and/or check the state of the computer for the current user to determine whether sending a notification is appropriate.

This is a FFI wrapper to the Windows win32 shell API SHQueryUserNotificationState and undocumented WNF (Windows Notification Facility) API.

Example

import { queryUserNotificationState } from "notification-state-ffi";

const state = queryUserNotificationState();
console.log(state); 
//QUNS_ACCEPTS_NOTIFICATIONS (notifications can be freely sent) 

//If you prefer the raw data instead:

const state = queryUserNotificationState({translate: false});
console.log(state); 
//5 (notifications can be freely sent)

You can use queryUserNotificationState() to easily know if an application is currently running in fullscreen on the user's primary display

import { isFullscreenAppRunning } from "notification-state-ffi";

if (isFullscreenAppRunning()){
  //Do something
}

Focus assist current state

import { queryFocusAssistState } from "notification-state-ffi";

const state = await queryFocusAssistState({translate: true});
console.log(state);
//PRIORITY_ONLY

Disable / enable focus assist

import { focusAssist } from "notification-state-ffi";

console.log("Disabling...");
await focusAssist(false).catch(console.error);

console.log("Enabling...");
await focusAssist(true).catch(console.error);

Installation

npm install notification-state-ffi

Prerequisite: C/C++ build tools to build koffi.

API

⚠️ This module is only available as an ECMAScript module (ESM)

Named export

queryUserNotificationState(option?: object): Promise<number | string>

Checks the state of the computer for the current user to determine whether sending a notification is appropriate.

⚙️ Options:

• translate?: boolean (true)

When a value is known it will be 'translated' to its string equivalent value otherwise its integer value.
If you want the raw data only set it to false.

Return value:

✔️ If this function succeeds, it returns QUERY_USER_NOTIFICATION_STATE.
❌ Otherwise, it throws with the corresponding HRESULT error code.

Example:

queryUserNotificationState({translate: true}) //QUNS_BUSY (string)
queryUserNotificationState({translate: false}) //2 (number)

isFullscreenAppRunning(): Promise<boolean>

Uses queryUserNotificationState() to easily know if an application is currently running in fullscreen on the user's primary display.

Return value:

✔️ Returns whether an application is currently running in fullscreen.
If queryUserNotificationState() fails then false is assumed.

queryFocusAssistState(option?: object): Promise<number | string>

Get the current state of "Focus Assist".

⚠ WNF (Windows Notification Facility) is an undocumented Windows API ! This API can change/break at any time in the future.

⚙️ Options:

• translate?: boolean (true)

When a value is known it will be 'translated' to its string equivalent value otherwise its integer value.
If you want the raw data only set it to false.

• stateError?: boolean (false)

When true the state NOT_SUPPORTED (-2) and FAILED (-1) will throw.
Default to false for backwards compatibility.

Return value:

✔️ If this function succeeds, it returns the current state.
❌ Otherwise, it throws with the corresponding NTSTATUS error code.

Example:

queryFocusAssistState({translate: true}) //PRIORITY_ONLY (string)
queryFocusAssistState({translate: false}) //1 (number)

focusAssist(enable: boolean, option?: object): Promise<void>

Tries to enable / disable focus assist.

💡 Works best when user has game and/or fullscreen auto rule(s) enabled and set to priority only.

⚠ WNF (Windows Notification Facility) is an undocumented Windows API ! This API can change/break at any time in the future.

⚙️ Options:

• checkSuccess?: boolean (true)

Whether or not to check if the change operation was successful.

❌ Will throw on error.