browser_protocol/target/
mod.rs

1//! Supports additional targets discovery and allows to attach to them.
2
3use serde::{Serialize, Deserialize};
4
5
6pub type TargetID = String;
7
8/// Unique identifier of attached debugging session.
9
10pub type SessionID = String;
11
12
13#[derive(Debug, Clone, Serialize, Deserialize, Default)]
14#[serde(rename_all = "camelCase")]
15pub struct TargetInfo {
16
17    pub targetId: TargetID,
18    /// List of types: <https://source.chromium.org/chromium/chromium/src/+/main:content/browser/devtools/devtools_agent_host_impl.cc?ss=chromium&q=f:devtools%20-f:out%20%22::kTypeTab%5B%5D%22>
19
20    #[serde(rename = "type")]
21    pub type_: String,
22
23    pub title: String,
24
25    pub url: String,
26    /// Whether the target has an attached client.
27
28    pub attached: bool,
29    /// Opener target Id
30
31    #[serde(skip_serializing_if = "Option::is_none")]
32    pub openerId: Option<TargetID>,
33    /// Whether the target has access to the originating window.
34
35    pub canAccessOpener: bool,
36    /// Frame id of originating window (is only set if target has an opener).
37
38    #[serde(skip_serializing_if = "Option::is_none")]
39    pub openerFrameId: Option<crate::page::FrameId>,
40    /// Id of the parent frame, present for "iframe" and "worker" targets. For nested workers,
41    /// this is the "ancestor" frame that created the first worker in the nested chain.
42
43    #[serde(skip_serializing_if = "Option::is_none")]
44    pub parentFrameId: Option<crate::page::FrameId>,
45
46    #[serde(skip_serializing_if = "Option::is_none")]
47    pub browserContextId: Option<crate::browser::BrowserContextID>,
48    /// Provides additional details for specific target types. For example, for
49    /// the type of "page", this may be set to "prerender".
50
51    #[serde(skip_serializing_if = "Option::is_none")]
52    pub subtype: Option<String>,
53}
54
55/// A filter used by target query/discovery/auto-attach operations.
56
57#[derive(Debug, Clone, Serialize, Deserialize, Default)]
58#[serde(rename_all = "camelCase")]
59pub struct FilterEntry {
60    /// If set, causes exclusion of matching targets from the list.
61
62    #[serde(skip_serializing_if = "Option::is_none")]
63    pub exclude: Option<bool>,
64    /// If not present, matches any type.
65
66    #[serde(skip_serializing_if = "Option::is_none")]
67    #[serde(rename = "type")]
68    pub type_: Option<String>,
69}
70
71/// The entries in TargetFilter are matched sequentially against targets and
72/// the first entry that matches determines if the target is included or not,
73/// depending on the value of 'exclude' field in the entry.
74/// If filter is not specified, the one assumed is
75/// \[{type: "browser", exclude: true}, {type: "tab", exclude: true}, {}\]
76/// (i.e. include everything but 'browser' and 'tab').
77
78pub type TargetFilter = Vec<FilterEntry>;
79
80
81#[derive(Debug, Clone, Serialize, Deserialize, Default)]
82#[serde(rename_all = "camelCase")]
83pub struct RemoteLocation {
84
85    pub host: String,
86
87    pub port: i64,
88}
89
90/// The state of the target window.
91
92#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
93pub enum WindowState {
94    #[default]
95    Normal,
96    Minimized,
97    Maximized,
98    Fullscreen,
99}
100
101/// Activates (focuses) the target.
102
103#[derive(Debug, Clone, Serialize, Deserialize, Default)]
104#[serde(rename_all = "camelCase")]
105pub struct ActivateTargetParams {
106
107    pub targetId: TargetID,
108}
109
110/// Attaches to the target with given id.
111
112#[derive(Debug, Clone, Serialize, Deserialize, Default)]
113#[serde(rename_all = "camelCase")]
114pub struct AttachToTargetParams {
115
116    pub targetId: TargetID,
117    /// Enables "flat" access to the session via specifying sessionId attribute in the commands.
118    /// We plan to make this the default, deprecate non-flattened mode,
119    /// and eventually retire it. See crbug.com/991325.
120
121    #[serde(skip_serializing_if = "Option::is_none")]
122    pub flatten: Option<bool>,
123}
124
125/// Attaches to the target with given id.
126
127#[derive(Debug, Clone, Serialize, Deserialize, Default)]
128#[serde(rename_all = "camelCase")]
129pub struct AttachToTargetReturns {
130    /// Id assigned to the session.
131
132    pub sessionId: SessionID,
133}
134
135/// Attaches to the browser target, only uses flat sessionId mode.
136
137#[derive(Debug, Clone, Serialize, Deserialize, Default)]
138#[serde(rename_all = "camelCase")]
139pub struct AttachToBrowserTargetReturns {
140    /// Id assigned to the session.
141
142    pub sessionId: SessionID,
143}
144
145/// Closes the target. If the target is a page that gets closed too.
146
147#[derive(Debug, Clone, Serialize, Deserialize, Default)]
148#[serde(rename_all = "camelCase")]
149pub struct CloseTargetParams {
150
151    pub targetId: TargetID,
152}
153
154/// Closes the target. If the target is a page that gets closed too.
155
156#[derive(Debug, Clone, Serialize, Deserialize, Default)]
157#[serde(rename_all = "camelCase")]
158pub struct CloseTargetReturns {
159    /// Always set to true. If an error occurs, the response indicates protocol error.
160
161    pub success: bool,
162}
163
164/// Inject object to the target's main frame that provides a communication
165/// channel with browser target.
166/// 
167/// Injected object will be available as 'window\[bindingName\]'.
168/// 
169/// The object has the following API:
170/// - 'binding.send(json)' - a method to send messages over the remote debugging protocol
171/// - 'binding.onmessage = json =\> handleMessage(json)' - a callback that will be called for the protocol notifications and command responses.
172
173#[derive(Debug, Clone, Serialize, Deserialize, Default)]
174#[serde(rename_all = "camelCase")]
175pub struct ExposeDevToolsProtocolParams {
176
177    pub targetId: TargetID,
178    /// Binding name, 'cdp' if not specified.
179
180    #[serde(skip_serializing_if = "Option::is_none")]
181    pub bindingName: Option<String>,
182    /// If true, inherits the current root session's permissions (default: false).
183
184    #[serde(skip_serializing_if = "Option::is_none")]
185    pub inheritPermissions: Option<bool>,
186}
187
188/// Creates a new empty BrowserContext. Similar to an incognito profile but you can have more than
189/// one.
190
191#[derive(Debug, Clone, Serialize, Deserialize, Default)]
192#[serde(rename_all = "camelCase")]
193pub struct CreateBrowserContextParams {
194    /// If specified, disposes this context when debugging session disconnects.
195
196    #[serde(skip_serializing_if = "Option::is_none")]
197    pub disposeOnDetach: Option<bool>,
198    /// Proxy server, similar to the one passed to --proxy-server
199
200    #[serde(skip_serializing_if = "Option::is_none")]
201    pub proxyServer: Option<String>,
202    /// Proxy bypass list, similar to the one passed to --proxy-bypass-list
203
204    #[serde(skip_serializing_if = "Option::is_none")]
205    pub proxyBypassList: Option<String>,
206    /// An optional list of origins to grant unlimited cross-origin access to.
207    /// Parts of the URL other than those constituting origin are ignored.
208
209    #[serde(skip_serializing_if = "Option::is_none")]
210    pub originsWithUniversalNetworkAccess: Option<Vec<String>>,
211}
212
213/// Creates a new empty BrowserContext. Similar to an incognito profile but you can have more than
214/// one.
215
216#[derive(Debug, Clone, Serialize, Deserialize, Default)]
217#[serde(rename_all = "camelCase")]
218pub struct CreateBrowserContextReturns {
219    /// The id of the context created.
220
221    pub browserContextId: crate::browser::BrowserContextID,
222}
223
224/// Returns all browser contexts created with 'Target.createBrowserContext' method.
225
226#[derive(Debug, Clone, Serialize, Deserialize, Default)]
227#[serde(rename_all = "camelCase")]
228pub struct GetBrowserContextsReturns {
229    /// An array of browser context ids.
230
231    pub browserContextIds: Vec<crate::browser::BrowserContextID>,
232    /// The id of the default browser context if available.
233
234    #[serde(skip_serializing_if = "Option::is_none")]
235    pub defaultBrowserContextId: Option<crate::browser::BrowserContextID>,
236}
237
238/// Creates a new page.
239
240#[derive(Debug, Clone, Serialize, Deserialize, Default)]
241#[serde(rename_all = "camelCase")]
242pub struct CreateTargetParams {
243    /// The initial URL the page will be navigated to. An empty string indicates about:blank.
244
245    pub url: String,
246    /// Frame left origin in DIP (requires newWindow to be true or headless shell).
247
248    #[serde(skip_serializing_if = "Option::is_none")]
249    pub left: Option<i64>,
250    /// Frame top origin in DIP (requires newWindow to be true or headless shell).
251
252    #[serde(skip_serializing_if = "Option::is_none")]
253    pub top: Option<i64>,
254    /// Frame width in DIP (requires newWindow to be true or headless shell).
255
256    #[serde(skip_serializing_if = "Option::is_none")]
257    pub width: Option<u64>,
258    /// Frame height in DIP (requires newWindow to be true or headless shell).
259
260    #[serde(skip_serializing_if = "Option::is_none")]
261    pub height: Option<i64>,
262    /// Frame window state (requires newWindow to be true or headless shell).
263    /// Default is normal.
264
265    #[serde(skip_serializing_if = "Option::is_none")]
266    pub windowState: Option<WindowState>,
267    /// The browser context to create the page in.
268
269    #[serde(skip_serializing_if = "Option::is_none")]
270    pub browserContextId: Option<crate::browser::BrowserContextID>,
271    /// Whether BeginFrames for this target will be controlled via DevTools (headless shell only,
272    /// not supported on MacOS yet, false by default).
273
274    #[serde(skip_serializing_if = "Option::is_none")]
275    pub enableBeginFrameControl: Option<bool>,
276    /// Whether to create a new Window or Tab (false by default, not supported by headless shell).
277
278    #[serde(skip_serializing_if = "Option::is_none")]
279    pub newWindow: Option<bool>,
280    /// Whether to create the target in background or foreground (false by default, not supported
281    /// by headless shell).
282
283    #[serde(skip_serializing_if = "Option::is_none")]
284    pub background: Option<bool>,
285    /// Whether to create the target of type "tab".
286
287    #[serde(skip_serializing_if = "Option::is_none")]
288    pub forTab: Option<bool>,
289    /// Whether to create a hidden target. The hidden target is observable via protocol, but not
290    /// present in the tab UI strip. Cannot be created with 'forTab: true', 'newWindow: true' or
291    /// 'background: false'. The life-time of the tab is limited to the life-time of the session.
292
293    #[serde(skip_serializing_if = "Option::is_none")]
294    pub hidden: Option<bool>,
295    /// If specified, the option is used to determine if the new target should
296    /// be focused or not. By default, the focus behavior depends on the
297    /// value of the background field. For example, background=false and focus=false
298    /// will result in the target tab being opened but the browser window remain
299    /// unchanged (if it was in the background, it will remain in the background)
300    /// and background=false with focus=undefined will result in the window being focused.
301    /// Using background: true and focus: true is not supported and will result in an error.
302
303    #[serde(skip_serializing_if = "Option::is_none")]
304    pub focus: Option<bool>,
305}
306
307/// Creates a new page.
308
309#[derive(Debug, Clone, Serialize, Deserialize, Default)]
310#[serde(rename_all = "camelCase")]
311pub struct CreateTargetReturns {
312    /// The id of the page opened.
313
314    pub targetId: TargetID,
315}
316
317/// Detaches session with given id.
318
319#[derive(Debug, Clone, Serialize, Deserialize, Default)]
320#[serde(rename_all = "camelCase")]
321pub struct DetachFromTargetParams {
322    /// Session to detach.
323
324    #[serde(skip_serializing_if = "Option::is_none")]
325    pub sessionId: Option<SessionID>,
326    /// Deprecated.
327
328    #[serde(skip_serializing_if = "Option::is_none")]
329    pub targetId: Option<TargetID>,
330}
331
332/// Deletes a BrowserContext. All the belonging pages will be closed without calling their
333/// beforeunload hooks.
334
335#[derive(Debug, Clone, Serialize, Deserialize, Default)]
336#[serde(rename_all = "camelCase")]
337pub struct DisposeBrowserContextParams {
338
339    pub browserContextId: crate::browser::BrowserContextID,
340}
341
342/// Returns information about a target.
343
344#[derive(Debug, Clone, Serialize, Deserialize, Default)]
345#[serde(rename_all = "camelCase")]
346pub struct GetTargetInfoParams {
347
348    #[serde(skip_serializing_if = "Option::is_none")]
349    pub targetId: Option<TargetID>,
350}
351
352/// Returns information about a target.
353
354#[derive(Debug, Clone, Serialize, Deserialize, Default)]
355#[serde(rename_all = "camelCase")]
356pub struct GetTargetInfoReturns {
357
358    pub targetInfo: TargetInfo,
359}
360
361/// Retrieves a list of available targets.
362
363#[derive(Debug, Clone, Serialize, Deserialize, Default)]
364#[serde(rename_all = "camelCase")]
365pub struct GetTargetsParams {
366    /// Only targets matching filter will be reported. If filter is not specified
367    /// and target discovery is currently enabled, a filter used for target discovery
368    /// is used for consistency.
369
370    #[serde(skip_serializing_if = "Option::is_none")]
371    pub filter: Option<TargetFilter>,
372}
373
374/// Retrieves a list of available targets.
375
376#[derive(Debug, Clone, Serialize, Deserialize, Default)]
377#[serde(rename_all = "camelCase")]
378pub struct GetTargetsReturns {
379    /// The list of targets.
380
381    pub targetInfos: Vec<TargetInfo>,
382}
383
384/// Sends protocol message over session with given id.
385/// Consider using flat mode instead; see commands attachToTarget, setAutoAttach,
386/// and crbug.com/991325.
387
388#[derive(Debug, Clone, Serialize, Deserialize, Default)]
389#[serde(rename_all = "camelCase")]
390pub struct SendMessageToTargetParams {
391
392    pub message: String,
393    /// Identifier of the session.
394
395    #[serde(skip_serializing_if = "Option::is_none")]
396    pub sessionId: Option<SessionID>,
397    /// Deprecated.
398
399    #[serde(skip_serializing_if = "Option::is_none")]
400    pub targetId: Option<TargetID>,
401}
402
403/// Controls whether to automatically attach to new targets which are considered
404/// to be directly related to this one (for example, iframes or workers).
405/// When turned on, attaches to all existing related targets as well. When turned off,
406/// automatically detaches from all currently attached targets.
407/// This also clears all targets added by 'autoAttachRelated' from the list of targets to watch
408/// for creation of related targets.
409/// You might want to call this recursively for auto-attached targets to attach
410/// to all available targets.
411
412#[derive(Debug, Clone, Serialize, Deserialize, Default)]
413#[serde(rename_all = "camelCase")]
414pub struct SetAutoAttachParams {
415    /// Whether to auto-attach to related targets.
416
417    pub autoAttach: bool,
418    /// Whether to pause new targets when attaching to them. Use 'Runtime.runIfWaitingForDebugger'
419    /// to run paused targets.
420
421    pub waitForDebuggerOnStart: bool,
422    /// Enables "flat" access to the session via specifying sessionId attribute in the commands.
423    /// We plan to make this the default, deprecate non-flattened mode,
424    /// and eventually retire it. See crbug.com/991325.
425
426    #[serde(skip_serializing_if = "Option::is_none")]
427    pub flatten: Option<bool>,
428    /// Only targets matching filter will be attached.
429
430    #[serde(skip_serializing_if = "Option::is_none")]
431    pub filter: Option<TargetFilter>,
432}
433
434/// Adds the specified target to the list of targets that will be monitored for any related target
435/// creation (such as child frames, child workers and new versions of service worker) and reported
436/// through 'attachedToTarget'. The specified target is also auto-attached.
437/// This cancels the effect of any previous 'setAutoAttach' and is also cancelled by subsequent
438/// 'setAutoAttach'. Only available at the Browser target.
439
440#[derive(Debug, Clone, Serialize, Deserialize, Default)]
441#[serde(rename_all = "camelCase")]
442pub struct AutoAttachRelatedParams {
443
444    pub targetId: TargetID,
445    /// Whether to pause new targets when attaching to them. Use 'Runtime.runIfWaitingForDebugger'
446    /// to run paused targets.
447
448    pub waitForDebuggerOnStart: bool,
449    /// Only targets matching filter will be attached.
450
451    #[serde(skip_serializing_if = "Option::is_none")]
452    pub filter: Option<TargetFilter>,
453}
454
455/// Controls whether to discover available targets and notify via
456/// 'targetCreated/targetInfoChanged/targetDestroyed' events.
457
458#[derive(Debug, Clone, Serialize, Deserialize, Default)]
459#[serde(rename_all = "camelCase")]
460pub struct SetDiscoverTargetsParams {
461    /// Whether to discover available targets.
462
463    pub discover: bool,
464    /// Only targets matching filter will be attached. If 'discover' is false,
465    /// 'filter' must be omitted or empty.
466
467    #[serde(skip_serializing_if = "Option::is_none")]
468    pub filter: Option<TargetFilter>,
469}
470
471/// Enables target discovery for the specified locations, when 'setDiscoverTargets' was set to
472/// 'true'.
473
474#[derive(Debug, Clone, Serialize, Deserialize, Default)]
475#[serde(rename_all = "camelCase")]
476pub struct SetRemoteLocationsParams {
477    /// List of remote locations.
478
479    pub locations: Vec<RemoteLocation>,
480}
481
482/// Gets the targetId of the DevTools page target opened for the given target
483/// (if any).
484
485#[derive(Debug, Clone, Serialize, Deserialize, Default)]
486#[serde(rename_all = "camelCase")]
487pub struct GetDevToolsTargetParams {
488    /// Page or tab target ID.
489
490    pub targetId: TargetID,
491}
492
493/// Gets the targetId of the DevTools page target opened for the given target
494/// (if any).
495
496#[derive(Debug, Clone, Serialize, Deserialize, Default)]
497#[serde(rename_all = "camelCase")]
498pub struct GetDevToolsTargetReturns {
499    /// The targetId of DevTools page target if exists.
500
501    #[serde(skip_serializing_if = "Option::is_none")]
502    pub targetId: Option<TargetID>,
503}
504
505/// Opens a DevTools window for the target.
506
507#[derive(Debug, Clone, Serialize, Deserialize, Default)]
508#[serde(rename_all = "camelCase")]
509pub struct OpenDevToolsParams {
510    /// This can be the page or tab target ID.
511
512    pub targetId: TargetID,
513    /// The id of the panel we want DevTools to open initially. Currently
514    /// supported panels are elements, console, network, sources, resources
515    /// and performance.
516
517    #[serde(skip_serializing_if = "Option::is_none")]
518    pub panelId: Option<String>,
519}
520
521/// Opens a DevTools window for the target.
522
523#[derive(Debug, Clone, Serialize, Deserialize, Default)]
524#[serde(rename_all = "camelCase")]
525pub struct OpenDevToolsReturns {
526    /// The targetId of DevTools page target.
527
528    pub targetId: TargetID,
529}
browser_protocol/target/mod.rs

browser_protocol/target/
mod.rs
