Struct Printer 

pub struct Printer<'frontend> { /* private fields */ }

A safe handle to a cpdb printer object.

See the module docs for the ownership and lifetime model.

Implementations

impl<'frontend> Printer<'frontend>

pub fn id(&self) -> Result<String>

The backend-assigned printer ID (stable across sessions).

pub fn name(&self) -> Result<String>

The human-readable printer name.

pub fn location(&self) -> Result<String>

The physical location string supplied by the backend.

pub fn description(&self) -> Result<String>

A free-form description (info in the C struct).

pub fn make_and_model(&self) -> Result<String>

The printer’s make and model.

pub fn backend_name(&self) -> Result<String>

The backend name this printer belongs to (e.g. "CUPS").

pub fn cached_state(&self) -> Result<String>

The cached state string (idle, processing, …).

For an authoritative answer use Printer::get_updated_state.

pub fn get_updated_state(&self) -> Result<String>

Queries the current state from the backend.

The returned string is owned by Rust; the cpdb-libs allocation is freed inside this call.

pub fn is_accepting_jobs(&self) -> Result<bool>

true when the printer is accepting jobs.

pub fn set_user_default(&self) -> Result<bool>

Marks this printer as the user’s default. Returns true on success.

pub fn set_system_default(&self) -> Result<bool>

Marks this printer as the system-wide default. Returns true on success.

pub fn print_file(&self, file_path: &str) -> Result<String>

Submits a file as a print job with no extra options.

Returns the backend-assigned job ID string.

pub fn print_fd(&self, title: &str) -> Result<PrintFdHandle>

Streams a print job over a file descriptor.

cpdb-libs hands back a writable file descriptor; the caller writes the job’s data to it and drops the returned handle to close it. The backend job ID and an optional auxiliary socket path are also returned.

pub fn print_socket(&self, title: &str) -> Result<PrintSocketHandle>

Streams a print job over a Unix-domain socket.

cpdb-libs returns a socket path the caller connects to and writes the job data through, plus the backend-assigned job ID.

pub fn submit_job( &self, file_path: &str, options: &[(&str, &str)], title: &str, ) -> Result<String>

Submits a job with a per-call set of options and an explicit title.

Options are applied to the printer’s settings table via cpdbAddSettingToPrinter before submission, so they take effect for this job and persist for subsequent jobs on the same printer until cleared via Printer::clear_setting.

Returns the backend-assigned job ID string.

pub fn get_option(&self, option_name: &str) -> Result<Option<String>>

Returns the default value for a named option, if the option exists.

pub fn get_default(&self, option_name: &str) -> Result<String>

Returns the default value for a named option, freeing the GLib string.

pub fn get_current(&self, option_name: &str) -> Result<String>

Returns the current (setting-or-default) value for a named option.

pub fn acquire_details(&self)

Asynchronously asks the backend to populate the printer’s full option table. Returns immediately; no completion notification.

Use Printer::acquire_details_with if you need to be told when the operation finishes.

pub fn acquire_details_with<F>(&self, completion: F)

where F: FnOnce(&Printer<'_>, bool) + Send + 'static,

Asynchronously populates the option table, firing completion when the backend responds.

completion is invoked from cpdb-libs’ D-Bus listener thread with success = true when the backend reported success. Panics inside the closure are caught and absorbed.

pub fn get_options_collection(&self) -> Result<OptionsCollection>

Returns an owned snapshot of every option on this printer.

Call Printer::acquire_details before this so the option table is populated by the backend.

pub fn get_setting(&self, name: &str) -> Result<Option<String>>

Reads a per-printer setting, or returns None when unset.

pub fn add_setting(&self, name: &str, value: &str) -> Result<()>

Inserts or overwrites a per-printer setting.

pub fn clear_setting(&self, name: &str) -> Result<bool>

Removes a per-printer setting. Returns Ok(true) when it existed.

pub fn get_media(&self, media_name: &str) -> Result<Option<String>>

Returns the descriptive name of a media type, if known.

pub fn get_media_size(&self, media_name: &str) -> Result<MediaSize>

Returns the media size for a named media type.

Both dimensions are in hundredths of a millimetre.

pub fn get_media_margins(&self, media_name: &str) -> Result<Margins>

Returns every margin entry the backend reports for a named media type.

pub fn acquire_translations(&self, locale: &str) -> Result<()>

Asynchronously fetches translations for the given locale.

Use Printer::acquire_translations_with if you need to be told when the operation finishes.

pub fn acquire_translations_with<F>( &self, locale: &str, completion: F, ) -> Result<()>

where F: FnOnce(&Printer<'_>, bool) + Send + 'static,

Asynchronously fetches translations, firing completion on success/failure.

completion is invoked from cpdb-libs’ D-Bus listener thread. Panics inside the closure are caught and absorbed.

pub fn get_option_translation( &self, option: &str, locale: &str, ) -> Result<Option<String>>

Returns the human-readable label for an option in the given locale.

pub fn get_choice_translation( &self, option: &str, choice: &str, locale: &str, ) -> Result<Option<String>>

Returns the human-readable label for a specific option choice.

pub fn get_option_translation_from_table( &self, option: &str, locale: &str, ) -> Result<Option<String>>

Like get_option_translation, but only consults the in-memory translation table — never falls through to the backend over D-Bus.

Returns None if the option label has not been loaded yet. Call Printer::get_all_translations (or Printer::acquire_translations_with) first to populate the table.

pub fn get_choice_translation_from_table( &self, option: &str, choice: &str, locale: &str, ) -> Result<Option<String>>

Like get_choice_translation, but only consults the in-memory translation table — never falls through to the backend over D-Bus.

pub fn get_group_translation( &self, group: &str, locale: &str, ) -> Result<Option<String>>

Returns the human-readable label for an option group.

pub fn get_all_translations(&self, locale: &str) -> Result<()>

Synchronously populates every translation for the given locale.

pub fn translations(&self) -> TranslationMap

Returns an owned snapshot of the printer’s cached translation table.

Call Printer::get_all_translations (or Printer::acquire_translations_with) first to populate the table. Returns an empty map when no translations have been loaded.

pub fn debug_dump(&self)

Dumps a human-readable description of this printer to stderr via cpdbDebugPrinter. Useful for diagnostics; production code should inspect the typed accessors instead.

pub fn dump_basic_options(&self)

Dumps the printer’s basic option set to stdout via cpdbPrintBasicOptions. Diagnostics-only.

pub fn pickle_to_file(&self, path: &str, frontend: &Frontend) -> Result<()>

Serialises this printer to a file (cpdbPicklePrinterToFile).

pub fn load_from_file(path: &str) -> Result<Printer<'static>>

Loads a printer that was previously serialised via pickle_to_file.

The returned printer is owned — it is freed when dropped.

Trait Implementations

impl<'frontend> Debug for Printer<'frontend>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Printer<'_>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.