Struct CpdbClient 

pub struct CpdbClient { /* private fields */ }

Available on crate feature zbus-backend only.

A connected CPDB client managing proxies to all discovered print backends.

Created via CpdbClient::new(). The client is Clone-able - cloning shares the underlying D-Bus connection.

Usage

let client = CpdbClient::new().await?;

// Initial population
let printers = client.get_all_printers().await?;

// Fetch capabilities when the user selects a printer
let (options, media) = client.get_printer_details(&printers[0].id, "CUPS").await?;

// Submit a print job
let settings = [("copies", "1"), ("media", "iso_a4_210x297mm")];
let (job_id, fd) = client.print_fd(&printers[0].id, "CUPS", &settings, "My Doc").await?;

Implementations

impl CpdbClient

pub async fn new() -> Result<Self>

Connect to the D-Bus session bus and discover all CPDB backends.

1. Opens a session bus connection.
2. Calls ListActivatableNames to find org.openprinting.Backend.* services.
3. Creates a PrintBackendProxy for each discovered backend.

Backends that fail to connect are logged and skipped.

Errors

Returns CpdbError::DbusError if the session bus itself is unavailable.

pub fn backend_count(&self) -> usize

Returns the number of connected backends.

pub async fn get_all_printers(&self) -> Result<Vec<PrinterSnapshot>>

Fetches all known printers from all connected backends.

This is the initial population method - equivalent to what the C library’s fetchPrinterListFromBackend() does. It calls GetAllPrinters on each backend and unpacks the variant-wrapped printer data into PrinterSnapshots.

Use this to populate the printer list. Use discovery_stream() for live updates after that.

Errors

Returns errors if a D-Bus call fails. Backends that fail individually are skipped, and printers from working backends are still returned.

pub async fn get_filtered_printers(&self) -> Result<Vec<PrinterSnapshot>>

Like get_all_printers() but returns only printers matching the current filter state.

Call show_remote_printers(false) or show_temporary_printers(false) first to set the filter, then call this to get the filtered list.

pub async fn discovery_stream(&self) -> Result<DiscoveryStream>

Returns a merged stream of DiscoveryEvents from all backends.

The stream emits events as printers are added, removed, or change state. After subscribing to signals, it calls doListing(true) on each backend to trigger initial PrinterAdded emissions.

A background task is automatically spawned to ping the backends periodically, preventing them from timing out. When this stream is dropped, the keep-alive task is cancelled.

Errors

Returns CpdbError::DbusError if subscribing to D-Bus signals fails.

pub async fn keep_alive_all(&self)

Keeps all backends alive to prevent them from auto-exiting.

CPDB backends automatically exit after a period of inactivity (typically 30 seconds). If you are listening to a discovery_stream(), you should call this method periodically (e.g. every 10 seconds) to ensure the backends stay running and continue emitting discovery signals.

pub async fn get_printer_details( &self, printer_id: &str, backend: &str, ) -> Result<(OptionsCollection, MediaCollection)>

Fetches all options and media for a printer in a single D-Bus call.

This calls the backend’s GetAllOptions method, which returns both the printer’s capabilities (duplex, color mode, etc.) and its supported paper sizes with margin information.

Arguments

• printer_id - The printer’s unique ID (from PrinterSnapshot::id).
• backend - The backend name, e.g. "CUPS" or the full service name "org.openprinting.Backend.CUPS".

Errors

• CpdbError::BackendError if no backend matches backend.
• CpdbError::DbusError if the D-Bus call fails.

pub async fn get_translations( &self, printer_id: &str, backend: &str, locale: &str, ) -> Result<HashMap<String, String>>

Fetches localized labels for a printer’s options and choices.

Returns a map of internal name -> human-readable label, e.g. {"sides" -> "Two-Sided", "one-sided" -> "Off", ...}.

Arguments

• printer_id - The printer’s unique ID.
• backend - The backend name.
• locale - A POSIX locale string, e.g. "en_US" or "de_DE".

pub async fn get_default_printer(&self, backend: &str) -> Result<String>

Returns the default printer ID for a specific backend.

pub async fn print_fd( &self, printer_id: &str, backend: &str, settings: &[(&str, &str)], title: &str, ) -> Result<(String, OwnedFd)>

Submits a print job and returns a writable file descriptor.

The backend creates a CUPS job and returns the write end of a socketpair. The caller writes the document data into fd and closes it when done - the backend reads from the other end and forwards it to the print system.

Arguments

• printer_id - The printer’s unique ID.
• backend - The backend name.
• settings - Print settings as key-value pairs, e.g. [("copies", "2"), ("media", "iso_a4_210x297mm")].
• title - The job title shown in the print queue.

Returns

A tuple of (job_id, fd) where job_id is the CUPS job ID string and fd is the writable end of the socketpair.

pub async fn print_socket( &self, printer_id: &str, backend: &str, settings: &[(&str, &str)], title: &str, ) -> Result<(String, String)>

Submits a print job and returns a Unix domain socket path to write the document to.

The caller must connect to the returned socket path and write the document data, closing the stream when finished.

pub async fn show_remote_printers(&self, visible: bool)

Sets the visibility of remote printers on all connected backends.

When visible is false, printers discovered via DNS-SD / mDNS on remote hosts are hidden from discovery signals.

pub async fn show_temporary_printers(&self, visible: bool)

Sets the visibility of temporary (auto-discovered) printers on all connected backends.

Trait Implementations

impl Clone for CpdbClient

fn clone(&self) -> CpdbClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.