API: Processes

Functions for finding, monitoring, and managing Windows processes.

C++ registration: regManager(js) and regProcesses(js).

---

proc_find

proc_find(name: string) → object

Find process(es) by .exe name (case-insensitive). If multiple instances are running — returns all PIDs.

Parameters:

Parameter	Type	Description
name	string	Process file name, e.g. "notepad.exe"

Result:

Field	Type	Description
found	bool	true — at least one instance found
pid	number	PID of the first found (0 if not found)
pids	number[]	Array of all PIDs with that name
error	string	Error message or ""

Example:

let f = proc_find("notepad.exe");

if (!f.found) {
    console.log("Process not found");
} else {
    console.log("First PID:", f.pid);

    if (f.pids.length > 1) {
        console.log("Multiple instances:", JSON.stringify(f.pids));
    }
}

---

proc_cpu

proc_cpu(pid: number) → object

CPU usage by the process in percent.

Note: The function takes two measurements with a 200 ms pause — execution is blocked during this time.

Parameters:

Parameter	Type	Description
pid	number	Process PID

Result:

Field	Type	Description
cpu	number	CPU percent (−1 on error)
error	string	Error message or ""

Example:

let r = proc_cpu(1234);
if (r.error) {
    console.log("Error:", r.error);
} else {
    console.log("CPU:", r.cpu.toFixed(1) + "%");
}

---

proc_ram

proc_ram(pid: number) → object

Memory consumption (Working Set).

Parameters:

Parameter	Type	Description
pid	number	Process PID

Result:

Field	Type	Description
ram_mb	number	MB (−1 on error)
ram_bytes	number	Bytes
error	string	Error message or ""

Example:

let r = proc_ram(1234);
console.log("RAM:", r.ram_mb.toFixed(1), "MB");
console.log("RAM (bytes):", r.ram_bytes);

---

proc_alive

proc_alive(pid: number) → object

Whether the process is alive and responding to messages.

Behavior:

• GUI process (has a visible window): checked via SendMessageTimeout with a 1 sec timeout.
• Background process (no window): responding = alive.

Parameters:

Parameter	Type	Description
pid	number	Process PID

Result:

Field	Type	Description
alive	bool	true — process exists and has not exited
responding	bool	true — process responds to messages
error	string	Error message or ""

Example:

let r = proc_alive(1234);
console.log("Alive:", r.alive);
console.log("Responding:", r.responding);

if (r.alive && !r.responding) {
    console.log("Process is hung!");
}

---

proc_service

proc_service(pid: number) → object

Whether the process belongs to a Windows service.

Parameters:

Parameter	Type	Description
pid	number	Process PID

Result:

Field	Type	Description
is_service	bool	true — process is a Windows service
service_name	string	Service name or ""
error	string	Error message or ""

Example:

let r = proc_service(1234);
if (r.is_service) {
    console.log("Service:", r.service_name);
}

---

proc_kill

proc_kill(pid: number) → object

Forcefully terminate a process (TerminateProcess).

Parameters:

Parameter	Type	Description
pid	number	Process PID

Result:

Field	Type	Description
ok	bool	true — process terminated
error	string	Error message or ""

Example:

let r = proc_kill(1234);
if (r.ok) {
    console.log("Process terminated");
} else {
    console.log("Error:", r.error);
}

---

proc_run

proc_run(path: string, args?: string) → object

Start a new process (CreateProcess).

Parameters:

Parameter	Type	Description
path	string	Full path to .exe
args	string	(optional) Command-line arguments

Result:

Field	Type	Description
ok	bool	true — process started
pid	number	PID of the new process (0 on error)
error	string	Error message or ""

Examples:

// Without arguments
let r = proc_run("C:\\Windows\\notepad.exe");
console.log("PID:", r.pid);

// With arguments
let r2 = proc_run("C:\\tools\\app.exe", "--config app.json --verbose");
if (r2.ok) {
    console.log("Started, PID:", r2.pid);
} else {
    console.log("Error:", r2.error);
}

---

Full example: monitoring a single process

let name = "myapp.exe";

// 1. Find the process
let f = proc_find(name);
if (!f.found) {
    console.log("[WARN] Process not found:", name);
} else {
    let pid = f.pid;

    // 2. Collect metrics
    let cpu  = proc_cpu(pid);      // blocks for 200 ms
    let ram  = proc_ram(pid);
    let live = proc_alive(pid);
    let svc  = proc_service(pid);

    console.log("PID:", pid);
    console.log("CPU:", cpu.cpu.toFixed(1) + "%");
    console.log("RAM:", ram.ram_mb.toFixed(1) + " MB");
    console.log("Alive:", live.alive, "| Responding:", live.responding);

    if (svc.is_service) {
        console.log("Service:", svc.service_name);
    }
}