Printer Event Handler

A cross-platform Rust library for monitoring printer status and events on Windows and Linux systems.

Features

• 🖨️ Cross-platform support - Works on Windows (WMI) and Linux (CUPS)
• 📊 Real-time monitoring - Monitor printer status changes with customizable intervals
• 🔍 Printer discovery - List and find printers on your system
• ⚡ Async/await support - Built on Tokio for efficient asynchronous operations
• 🛡️ Type-safe - Strongly typed printer status and error states
• 📦 Library + CLI - Use as a library in your projects or as a standalone CLI tool

Quick Start

As a Library

Add this to your Cargo.toml:

[dependencies]
printer_event_handler = "1.1.0"
tokio = { version = "1.0", features = ["full"] }

Basic Usage

use printer_event_handler::{PrinterMonitor, PrinterError};

#[tokio::main]
async fn main() -> Result<(), PrinterError> {
    // Create a printer monitor
    let monitor = PrinterMonitor::new().await?;
    
    // List all printers
    let printers = monitor.list_printers().await?;
    for printer in &printers {
        println!("📄 {}: {}", printer.name(), printer.status_description());
        if printer.has_error() {
            println!("   ⚠️  Error: {}", printer.error_description());
        }
    }
    
    Ok(())
}

Monitor Printer Status Changes

use printer_event_handler::PrinterMonitor;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let monitor = PrinterMonitor::new().await?;
    
    // Monitor a specific printer every 30 seconds
    monitor.monitor_printer("HP LaserJet Pro", 30, |current, previous| {
        if let Some(prev) = previous {
            if prev != current {
                println!("🔄 Status changed: {} → {}", 
                    prev.status_description(), 
                    current.status_description());
                
                if current.has_error() {
                    println!("❌ Error detected: {}", current.error_description());
                }
            }
        } else {
            println!("📊 Initial status: {}", current.status_description());
        }
    }).await?;
    
    Ok(())
}

Find Specific Printer

use printer_event_handler::PrinterMonitor;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let monitor = PrinterMonitor::new().await?;
    
    match monitor.find_printer("Microsoft Print to PDF").await? {
        Some(printer) => {
            println!("Found printer: {}", printer.name());
            println!("Status: {}", printer.status_description());
            println!("Is default: {}", printer.is_default());
            println!("Is offline: {}", printer.is_offline());
        }
        None => println!("Printer not found"),
    }
    
    Ok(())
}

Check for Changes

use printer_event_handler::PrinterMonitor;
use tokio::time::{sleep, Duration};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let monitor = PrinterMonitor::new().await?;
    
    // Get initial status
    let initial = monitor.find_printer("Your Printer").await?;
    
    // Wait and check again
    sleep(Duration::from_secs(5)).await;
    let current = monitor.find_printer("Your Printer").await?;
    
    // Compare states
    match (initial, current) {
        (Some(before), Some(after)) if before != after => {
            println!("Change detected!");
            println!("Before: {}", before.status_description());
            println!("After: {}", after.status_description());
        }
        (Some(_), Some(_)) => println!("No changes detected"),
        _ => println!("Printer not found"),
    }
    
    Ok(())
}

CLI Usage

The crate also provides a command-line interface:

# Install from crates.io
cargo install printer_event_handler

# Or run directly from source
git clone https://github.com/PajakKamil/printer_event_handler
cd printer_event_handler

List All Printers

cargo run

Output:

Printer Status Checker
======================
Found 3 printer(s):

Printer #1: HP LaserJet Pro MFP M428f
  Status: Idle
  Error State: No Error
  Offline: No
  Default Printer: Yes

Printer #2: HPDC7777 (HP Smart Tank 580-590 series)
  Status: Offline
  Error State: Service Requested
  Offline: Yes

Printer #3: Microsoft Print to PDF
  Status: Idle
  Error State: No Error
  Offline: No

Monitor a Specific Printer

cargo run -- "HP LaserJet Pro"

Output:

Printer Status Monitor Service
==============================
Monitoring printer 'HP LaserJet Pro' every 60 seconds...
Press Ctrl+C to stop

[2024-01-15 14:30:15] Printer 'HP LaserJet Pro' Initial Status:
  Status: Idle
  Error State: No Error
  Offline: No

[2024-01-15 14:31:15] Checking printer 'HP LaserJet Pro'
[2024-01-15 14:32:15] Printer 'HP LaserJet Pro' Status Changed:
  Status: Idle -> Printing
  Error State: No Error -> No Error
  Offline: No

[2024-01-15 14:33:15] Printer 'HP LaserJet Pro' Status Changed:
  Status: Printing -> Busy
  Error State: No Error -> No Error
  Offline: No

Platform Support

Linux Setup

On Ubuntu/Debian:

sudo apt install cups

On RHEL/CentOS/Fedora:

sudo yum install cups  # or dnf install cups-client

API Reference

Core Types

• PrinterMonitor - Main entry point for all printer operations
• Printer - Represents a printer and its current state
• PrinterStatus - Printer status enum (Idle, Printing, Offline, etc.)
• ErrorState - Error condition enum (NoError, Jammed, NoPaper, etc.)
• PrinterError - Error type for all operations

Printer Status Values

The library provides comprehensive support for all Win32_Printer states:

pub enum PrinterStatus {
    // Basic PrinterStatus values (1-7)
    Other,          // Other status
    Unknown,        // Unknown status  
    Idle,           // Ready to print
    Printing,       // Currently printing
    Warmup,         // Starting up/warming up
    StoppedPrinting,// Stopped mid-job
    Offline,        // Not available
    
    // Extended PrinterState values (0-25) - Full Win32_Printer support
    Paused,         // Printer paused
    Error,          // General error state
    PendingDeletion,// Queued for deletion
    PaperJam,       // Paper jam detected
    PaperOut,       // Out of paper
    ManualFeed,     // Manual feed required
    PaperProblem,   // Paper-related issue
    IOActive,       // I/O operations active
    Busy,           // Printer busy
    OutputBinFull,  // Output tray full
    NotAvailable,   // Printer not available
    Waiting,        // Waiting for job
    Processing,     // Processing job
    Initialization, // Initializing
    TonerLow,       // Low toner/ink
    NoToner,        // Out of toner/ink
    PagePunt,       // Page punt condition
    UserInterventionRequired, // User action needed
    OutOfMemory,    // Memory full
    DoorOpen,       // Cover/door open
    ServerUnknown,  // Server status unknown
    PowerSave,      // Power save mode
    
    StatusUnknown,  // Could not determine
}

Error States

Complete support for Win32_Printer DetectedErrorState values:

pub enum ErrorState {
    NoError,         // No issues (values 0, 2)
    Other,           // Other error (values 1, 9)
    LowPaper,        // Low paper (value 3)
    NoPaper,         // Out of paper (value 4)
    LowToner,        // Low toner/ink (value 5)
    NoToner,         // Out of toner/ink (value 6)
    DoorOpen,        // Cover/door open (value 7)
    Jammed,          // Paper jam (value 8)
    ServiceRequested,// Needs maintenance (value 10)
    OutputBinFull,   // Output tray full (value 11)
    UnknownError,    // Unknown error state
}

Examples

Check out the examples directory for more usage patterns:

• basic_listing.rs - List all printers
• monitor_changes.rs - Monitor status changes
• error_handling.rs - Proper error handling
• async_patterns.rs - Advanced async usage

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development

# Clone the repository
git clone https://github.com/PajakKamil/printer_event_handler
cd printer_event_handler

# Run tests
cargo test

# Check formatting
cargo fmt

# Run linter
cargo clippy

# Build documentation
cargo doc --open

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Changelog

See CHANGELOG.md for details about changes in each version.