cpdb_rs/proxy.rs
1//! D-Bus proxy for the `org.openprinting.PrintBackend` interface.
2//!
3//! This module is generated by `zbus-xmlgen` and adapted to use named structs
4//! for complex return types. Consumers should use [`crate::client::CpdbClient`]
5//! instead of this proxy directly.
6
7// The `#[proxy]` macro generates internal struct fields and service methods
8// that cannot be given doc comments directly.
9#![allow(missing_docs)]
10
11use serde::{Deserialize, Serialize};
12use zbus::proxy;
13use zbus::zvariant::Type;
14
15/// A printer option from `GetAllOptions`. D-Bus signature: `(sssia(s))`.
16#[derive(Debug, Clone, Deserialize, Serialize, Type)]
17pub struct RawOption {
18 /// The option name (e.g. `"sides"`, `"copies"`).
19 pub option_name: String,
20 /// The option group name (e.g. `"General"`).
21 pub group_name: String,
22 /// The default value string.
23 pub default_value: String,
24 /// Number of supported values.
25 pub num_supported: i32,
26 /// The list of supported values as 1-tuples (D-Bus encoding).
27 pub supported_values: Vec<(String,)>,
28}
29
30/// Print margins in hundredths of a millimetre. D-Bus signature: `(iiii)`.
31#[derive(Debug, Clone, Deserialize, Serialize, Type)]
32pub struct RawMargin {
33 /// Left margin in hundredths of a mm.
34 pub left: i32,
35 /// Right margin in hundredths of a mm.
36 pub right: i32,
37 /// Top margin in hundredths of a mm.
38 pub top: i32,
39 /// Bottom margin in hundredths of a mm.
40 pub bottom: i32,
41}
42
43/// A supported paper size from `GetAllOptions`. D-Bus signature: `(siiia(iiii))`.
44///
45/// Width and length are in hundredths of a millimetre.
46#[derive(Debug, Clone, Deserialize, Serialize, Type)]
47pub struct RawMedia {
48 /// The media name (e.g. `"iso_a4_210x297mm"`).
49 pub name: String,
50 /// Width in hundredths of a mm.
51 pub width: i32,
52 /// Length in hundredths of a mm.
53 pub length: i32,
54 /// Number of margin entries.
55 pub num_margins: i32,
56 /// Available margin configurations.
57 pub margins: Vec<RawMargin>,
58}
59
60/// A printer summary from `GetAllPrinters` or `GetFilteredPrinterList`.
61/// D-Bus signature: `(sssssbss)`.
62#[derive(Debug, Clone, Deserialize, Serialize, Type)]
63pub struct RawPrinter(
64 pub String, // id
65 pub String, // name
66 pub String, // info
67 pub String, // location
68 pub String, // make_and_model
69 pub bool, // is_accepting_jobs
70 pub String, // state
71 pub String, // backend_name
72);
73
74#[allow(missing_docs)]
75/// Low-level proxy for `org.openprinting.PrintBackend`.
76///
77/// Prefer [`CpdbClient`](crate::client::CpdbClient) for high-level usage.
78#[proxy(interface = "org.openprinting.PrintBackend", assume_defaults = true)]
79pub trait PrintBackend {
80 /// Returns all printers known to this backend.
81 fn get_all_printers(&self) -> zbus::Result<(i32, Vec<(zbus::zvariant::OwnedValue,)>)>;
82
83 /// Returns the backend name (e.g. "CUPS", "FILE").
84 fn get_backend_name(&self) -> zbus::Result<String>;
85
86 /// Returns printers matching the current filter settings.
87 fn get_filtered_printer_list(&self) -> zbus::Result<(i32, Vec<(zbus::zvariant::OwnedValue,)>)>;
88
89 /// Starts or stops printer discovery. Call `do_listing(true)` to trigger
90 /// `PrinterAdded` signals for all known printers.
91 ///
92 /// This is a fire-and-forget method - the backend does not send a reply.
93 #[zbus(name = "doListing", no_reply)]
94 fn do_listing(&self, is_listed: bool) -> zbus::Result<()>;
95
96 /// Fetches all options and media for a printer in a single call.
97 ///
98 /// Returns `(num_options, options, num_media, media)`.
99 /// This is the primary method for getting printer capabilities.
100 #[allow(clippy::type_complexity)]
101 fn get_all_options(
102 &self,
103 printer_id: &str,
104 ) -> zbus::Result<(i32, Vec<RawOption>, i32, Vec<RawMedia>)>;
105
106 /// Fetches all localized translations for a printer's options.
107 ///
108 /// Returns a map of internal name -> human-readable label.
109 fn get_all_translations(
110 &self,
111 printer_id: &str,
112 locale: &str,
113 ) -> zbus::Result<std::collections::HashMap<String, String>>;
114
115 /// Returns the default printer ID for this backend.
116 #[zbus(name = "getDefaultPrinter")]
117 fn get_default_printer(&self) -> zbus::Result<String>;
118
119 /// Returns the current state of a printer (e.g. "idle", "printing").
120 #[zbus(name = "getPrinterState")]
121 fn get_printer_state(&self, printer_id: &str) -> zbus::Result<String>;
122
123 /// Returns whether a printer is currently accepting jobs.
124 #[zbus(name = "isAcceptingJobs")]
125 fn is_accepting_jobs(&self, printer_id: &str) -> zbus::Result<bool>;
126
127 /// Returns a localized label for a single option name.
128 #[zbus(name = "getOptionTranslation")]
129 fn get_option_translation(
130 &self,
131 printer_name: &str,
132 option_name: &str,
133 locale: &str,
134 ) -> zbus::Result<String>;
135
136 /// Returns a localized label for a single option choice.
137 #[zbus(name = "getChoiceTranslation")]
138 fn get_choice_translation(
139 &self,
140 printer_name: &str,
141 option_name: &str,
142 choice_name: &str,
143 locale: &str,
144 ) -> zbus::Result<String>;
145
146 /// Returns a localized label for an option group.
147 #[zbus(name = "getGroupTranslation")]
148 fn get_group_translation(
149 &self,
150 printer_name: &str,
151 group_name: &str,
152 locale: &str,
153 ) -> zbus::Result<String>;
154
155 /// Submits a print job and returns a writable file descriptor.
156 ///
157 /// The backend creates a job and returns the write end of a socketpair.
158 /// The caller writes document data into `fd` and closes it when done.
159 #[zbus(name = "printFd")]
160 fn print_fd(
161 &self,
162 printer_id: &str,
163 num_settings: i32,
164 settings: &[(&str, &str)],
165 title: &str,
166 ) -> zbus::Result<(String, zbus::zvariant::OwnedFd)>;
167
168 /// Submits a print job via a Unix socket path.
169 #[zbus(name = "printSocket")]
170 fn print_socket(
171 &self,
172 printer_id: &str,
173 num_settings: i32,
174 settings: &[(&str, &str)],
175 title: &str,
176 ) -> zbus::Result<(String, String)>;
177
178 /// Show or hide remote (network-discovered) printers.
179 ///
180 /// This is a fire-and-forget method. The backend will emit `PrinterRemoved`
181 /// or `PrinterAdded` signals to reflect the new filtered state.
182 #[zbus(name = "showRemotePrinters", no_reply)]
183 fn show_remote_printers(&self, is_visible: bool) -> zbus::Result<()>;
184
185 /// Show or hide temporary (auto-discovered) printers.
186 #[zbus(name = "showTemporaryPrinters", no_reply)]
187 fn show_temporary_printers(&self, is_visible: bool) -> zbus::Result<()>;
188
189 /// Keeps the backend alive (prevents auto-exit timeout).
190 #[zbus(name = "keepAlive")]
191 fn keep_alive(&self) -> zbus::Result<()>;
192
193 /// Tells the backend to replace state from a previous dialog session.
194 #[zbus(name = "replace", no_reply)]
195 fn replace(&self, previous_dialog_id: &str) -> zbus::Result<()>;
196
197 /// Ping (testing only, will be removed from spec).
198 #[zbus(name = "ping", no_reply)]
199 fn ping(&self, printer_id: &str) -> zbus::Result<()>;
200
201 /// Emitted when a new printer is discovered by this backend.
202 #[zbus(signal)]
203 fn printer_added(
204 &self,
205 printer_id: &str,
206 printer_name: &str,
207 printer_info: &str,
208 printer_location: &str,
209 printer_make_and_model: &str,
210 printer_is_accepting_jobs: bool,
211 printer_state: &str,
212 backend_name: &str,
213 ) -> zbus::Result<()>;
214
215 /// Emitted when a printer is removed from this backend.
216 #[zbus(signal)]
217 fn printer_removed(&self, printer_id: &str, backend_name: &str) -> zbus::Result<()>;
218
219 /// Emitted when a printer's state changes (e.g. idle -> printing).
220 #[zbus(signal)]
221 fn printer_state_changed(
222 &self,
223 printer_id: &str,
224 printer_state: &str,
225 printer_is_accepting_jobs: bool,
226 backend_name: &str,
227 ) -> zbus::Result<()>;
228}