Skip to main content

aylis_core/
platform.rs

1//! Serviços de plataforma: os traits que cada sistema implementa.
2//!
3//! O core só conhece estes traits. Cada plataforma (Windows, Linux, web, Android, iOS)
4//! fornece as implementações num crate próprio e as entrega ao [`Ui`](crate::Ui) em
5//! [`Services`]. Sem serviços (por exemplo em testes), o `Ui` funciona normalmente,
6//! só não abre janelas.
7
8use crate::canvas::TextService;
9use crate::geometry::{RectF, SizeF};
10
11/// Identificador de uma janela nativa.
12#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
13pub struct WindowId(pub u64);
14
15/// Identificador de um timer.
16#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
17pub struct TimerId(pub u64);
18
19/// Janelas nativas (como `IFMXWindowService`).
20pub trait WindowService {
21    fn create_window(&mut self, title: &str, size: SizeF) -> WindowId;
22    fn close_window(&mut self, window: WindowId);
23    fn set_title(&mut self, window: WindowId, title: &str);
24    fn set_size(&mut self, window: WindowId, size: SizeF);
25    /// Pede que a janela seja repintada no próximo frame.
26    fn request_redraw(&mut self, window: WindowId);
27    /// Escala de DPI da janela (1.0 = 96 dpi).
28    fn scale_factor(&self, window: WindowId) -> f32;
29}
30
31/// Timers e frames (como `IFMXTimerService`).
32pub trait TimerService {
33    fn start_timer(&mut self, interval_ms: u32, repeat: bool) -> TimerId;
34    fn stop_timer(&mut self, timer: TimerId);
35    /// Pede um frame (usado pelas animações; só enquanto houver animação ativa).
36    fn request_frame(&mut self);
37    /// Relógio monotônico em segundos.
38    fn now(&self) -> f64;
39}
40
41/// Área de transferência (como `IFMXClipboardService`). Os controles e os apps usam o
42/// [`crate::clipboard`], que guarda no processo o que a plataforma não souber guardar.
43pub trait ClipboardService {
44    fn get_text(&mut self) -> Option<String>;
45    fn set_text(&mut self, text: &str);
46
47    /// Grava tudo de uma vez (o que estava sai), cada formato que a plataforma souber.
48    fn set_content(&mut self, content: &crate::clipboard::ClipboardContent) {
49        self.set_text(content.text.as_deref().unwrap_or(""));
50    }
51
52    fn get_html(&mut self) -> Option<String> {
53        None
54    }
55
56    fn get_image(&mut self) -> Option<crate::Image> {
57        None
58    }
59
60    /// Os bytes de um formato do app gravado pela plataforma (o de outra instância também).
61    fn get_data(&mut self, _format: &str) -> Option<Vec<u8>> {
62        None
63    }
64
65    /// Se a plataforma tem o formato (`clipboard::HTML`, `IMAGE` ou um do app) agora.
66    fn has(&mut self, format: &str) -> bool {
67        match format {
68            crate::clipboard::HTML => self.get_html().is_some(),
69            crate::clipboard::IMAGE => self.get_image().is_some(),
70            _ => self.get_data(format).is_some(),
71        }
72    }
73
74    /// O número que muda a cada cópia (de qualquer app), onde a plataforma conta; sem ele,
75    /// a cópia do processo vale enquanto o texto da plataforma for o mesmo.
76    fn sequence(&mut self) -> Option<u64> {
77        None
78    }
79}
80
81#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
82pub enum CursorShape {
83    #[default]
84    Default,
85    Pointer,
86    Text,
87    Wait,
88    Crosshair,
89    Move,
90    NotAllowed,
91    ResizeHorizontal,
92    ResizeVertical,
93    ResizeNeSw,
94    ResizeNwSe,
95    /// A mão aberta (o que se pode agarrar e arrastar) e a fechada (arrastando).
96    Grab,
97    Grabbing,
98    /// Sem cursor (o vídeo tocando com o mouse parado).
99    None,
100}
101
102impl CursorShape {
103    pub const ALL: [CursorShape; 14] = [
104        CursorShape::Default,
105        CursorShape::Pointer,
106        CursorShape::Text,
107        CursorShape::Wait,
108        CursorShape::Crosshair,
109        CursorShape::Move,
110        CursorShape::NotAllowed,
111        CursorShape::ResizeHorizontal,
112        CursorShape::ResizeVertical,
113        CursorShape::ResizeNeSw,
114        CursorShape::ResizeNwSe,
115        CursorShape::Grab,
116        CursorShape::Grabbing,
117        CursorShape::None,
118    ];
119}
120
121impl crate::prop::PropEnum for CursorShape {
122    const NAMES: &'static [&'static str] = &[
123        "default",
124        "pointer",
125        "text",
126        "wait",
127        "crosshair",
128        "move",
129        "not_allowed",
130        "resize_horizontal",
131        "resize_vertical",
132        "resize_ne_sw",
133        "resize_nw_se",
134        "grab",
135        "grabbing",
136        "none",
137    ];
138
139    fn from_index(index: usize) -> Option<Self> {
140        CursorShape::ALL.get(index).copied()
141    }
142
143    fn index(self) -> usize {
144        self as usize
145    }
146}
147
148/// Cursor do mouse (como `IFMXCursorService`). Plataformas sem mouse podem ignorar.
149pub trait CursorService {
150    fn set_cursor(&mut self, shape: CursorShape);
151}
152
153/// Aparência preferida pelo sistema.
154#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
155pub enum Appearance {
156    #[default]
157    Light,
158    Dark,
159}
160
161/// Tela (como `IFMXScreenService`).
162pub trait ScreenService {
163    fn screen_size(&self) -> SizeF;
164    fn scale_factor(&self) -> f32;
165    /// Tema claro/escuro do sistema operacional.
166    fn appearance(&self) -> Appearance;
167}
168
169/// Tipo de teclado virtual a mostrar no mobile.
170#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
171pub enum KeyboardKind {
172    #[default]
173    Text,
174    Number,
175    Decimal,
176    Phone,
177    Email,
178    Url,
179}
180
181/// Teclado virtual e IME (como `IFMXVirtualKeyboardService`).
182pub trait TextInputService {
183    fn show_keyboard(&mut self, kind: KeyboardKind);
184    fn hide_keyboard(&mut self);
185    /// Onde está o cursor de texto (para a janela de composição do IME).
186    fn set_ime_rect(&mut self, rect: RectF);
187}
188
189/// Formatos regionais.
190#[derive(Clone, Debug, PartialEq)]
191pub struct LocaleInfo {
192    pub decimal_separator: char,
193    pub thousand_separator: char,
194    pub short_date_format: String,
195    pub long_time_format: String,
196    pub currency_symbol: String,
197    /// Nomes dos meses (janeiro a dezembro) e dos dias da semana abreviados (domingo
198    /// primeiro), para calendários.
199    pub month_names: [&'static str; 12],
200    pub short_day_names: [&'static str; 7],
201    /// Primeiro dia da semana nos calendários (0 = domingo).
202    pub first_day_of_week: u8,
203}
204
205const MONTHS_EN: [&str; 12] = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
206const DAYS_EN: [&str; 7] = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
207
208impl Default for LocaleInfo {
209    fn default() -> Self {
210        Self {
211            decimal_separator: '.',
212            thousand_separator: ',',
213            short_date_format: "yyyy-mm-dd".into(),
214            long_time_format: "hh:nn:ss".into(),
215            currency_symbol: "$".into(),
216            month_names: MONTHS_EN,
217            short_day_names: DAYS_EN,
218            first_day_of_week: 0,
219        }
220    }
221}
222
223impl LocaleInfo {
224    /// Português do Brasil: `1.234,56`, `dd/mm/yyyy`, `R$`.
225    pub fn pt_br() -> Self {
226        Self {
227            decimal_separator: ',',
228            thousand_separator: '.',
229            short_date_format: "dd/mm/yyyy".into(),
230            long_time_format: "hh:nn:ss".into(),
231            currency_symbol: "R$".into(),
232            month_names: ["janeiro", "fevereiro", "março", "abril", "maio", "junho", "julho", "agosto", "setembro", "outubro", "novembro", "dezembro"],
233            short_day_names: ["dom", "seg", "ter", "qua", "qui", "sex", "sáb"],
234            first_day_of_week: 0,
235        }
236    }
237
238    /// Espanhol: `1.234,56`, `dd/mm/yyyy`, `€`, semana começando na segunda.
239    pub fn es() -> Self {
240        Self {
241            decimal_separator: ',',
242            thousand_separator: '.',
243            short_date_format: "dd/mm/yyyy".into(),
244            long_time_format: "hh:nn:ss".into(),
245            currency_symbol: "€".into(),
246            month_names: ["enero", "febrero", "marzo", "abril", "mayo", "junio", "julio", "agosto", "septiembre", "octubre", "noviembre", "diciembre"],
247            short_day_names: ["dom", "lun", "mar", "mié", "jue", "vie", "sáb"],
248            first_day_of_week: 1,
249        }
250    }
251
252    /// Inglês dos EUA: `1,234.56`, `mm/dd/yyyy`, `$`.
253    pub fn en_us() -> Self {
254        Self {
255            decimal_separator: '.',
256            thousand_separator: ',',
257            short_date_format: "mm/dd/yyyy".into(),
258            long_time_format: "hh:nn:ss".into(),
259            currency_symbol: "$".into(),
260            month_names: MONTHS_EN,
261            short_day_names: DAYS_EN,
262            first_day_of_week: 0,
263        }
264    }
265}
266
267pub trait LocaleService {
268    fn locale(&self) -> LocaleInfo;
269}
270
271/// Um `LocaleInfo` fixo também serve como serviço (útil para escolher o idioma do app).
272impl LocaleService for LocaleInfo {
273    fn locale(&self) -> LocaleInfo {
274        self.clone()
275    }
276}
277
278/// Eventos de ciclo de vida do aplicativo (importante no mobile).
279#[derive(Clone, Copy, Debug, PartialEq, Eq)]
280pub enum LifecycleEvent {
281    Resumed,
282    Suspended,
283    LowMemory,
284    /// A superfície de desenho foi perdida (GPU); é preciso recriar.
285    SurfaceLost,
286}
287
288/// Arquivos do aplicativo (imagens, áudio, vídeo, fontes) por caminho relativo à pasta
289/// do projeto, como `assets/images/logo.png`. No desktop vêm do disco; no Android podem vir
290/// de dentro do APK. O `aylis-project` instala um que lê da pasta do projeto.
291pub trait ResourceService {
292    fn read(&self, path: &str) -> Option<Vec<u8>>;
293}
294
295/// Cria forms pelo nome (como o `Application.CreateForm`). O `aylis-project` instala um que
296/// carrega os forms do projeto (`forms/*.json`).
297pub trait FormFactory {
298    /// Cria o form `name` (sem abrir) e devolve o id.
299    fn create_form(&mut self, ui: &mut crate::Ui, name: &str) -> Result<crate::ComponentId, String>;
300    /// Nomes dos forms que esta fábrica sabe criar.
301    fn form_names(&self) -> Vec<String>;
302}
303
304/// Opções de um diálogo de arquivo (Abrir/Salvar).
305#[derive(Clone, Debug, Default)]
306pub struct FileDialogOptions {
307    pub title: String,
308    /// (nome, extensões sem ponto): `("Imagens", ["png", "jpg"])`.
309    pub filters: Vec<(String, Vec<String>)>,
310    pub directory: String,
311    pub file_name: String,
312    /// Salvar em vez de abrir.
313    pub save: bool,
314    /// Abrir vários.
315    pub multiple: bool,
316    /// Escolher uma pasta (no lugar de arquivos; com `multiple`, várias). Onde o sistema não
317    /// tem (o navegador, o celular), volta vazio, como cancelado.
318    pub folder: bool,
319    /// O form dono do diálogo (a janela dele fica por baixo, como num modal); `None`: sem dona.
320    pub owner: Option<crate::ComponentId>,
321}
322
323/// Diálogos de arquivo do sistema. Assíncronos: `done` recebe os caminhos escolhidos
324/// (vazio = cancelado), de qualquer thread.
325pub trait FileDialogService {
326    fn show(&mut self, options: FileDialogOptions, done: Box<dyn FnOnce(Vec<String>) + Send>);
327}
328
329/// Uma permissão que o sistema pergunta ao usuário (celular e navegador; no desktop quase
330/// tudo já vem liberado).
331#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
332pub enum Permission {
333    Camera,
334    Microphone,
335    /// A localização com o app aberto.
336    Location,
337    Notifications,
338    /// Fotos e vídeos da galeria.
339    Photos,
340    Contacts,
341    Calendar,
342    Bluetooth,
343}
344
345impl Permission {
346    pub const ALL: [Permission; 8] = [
347        Permission::Camera,
348        Permission::Microphone,
349        Permission::Location,
350        Permission::Notifications,
351        Permission::Photos,
352        Permission::Contacts,
353        Permission::Calendar,
354        Permission::Bluetooth,
355    ];
356
357    /// O nome usado nos forms e no código (`camera`, `microphone`...).
358    pub fn name(self) -> &'static str {
359        match self {
360            Permission::Camera => "camera",
361            Permission::Microphone => "microphone",
362            Permission::Location => "location",
363            Permission::Notifications => "notifications",
364            Permission::Photos => "photos",
365            Permission::Contacts => "contacts",
366            Permission::Calendar => "calendar",
367            Permission::Bluetooth => "bluetooth",
368        }
369    }
370
371    pub fn parse(name: &str) -> Option<Permission> {
372        let name = name.trim();
373        Permission::ALL.into_iter().find(|p| p.name().eq_ignore_ascii_case(name))
374    }
375
376    /// Uma lista separada por `;` (ou `,`); nomes desconhecidos ficam de fora.
377    pub fn parse_list(list: &str) -> Vec<Permission> {
378        let mut out = Vec::new();
379        for p in list.split([';', ',']).filter_map(Permission::parse) {
380            if !out.contains(&p) {
381                out.push(p);
382            }
383        }
384        out
385    }
386}
387
388/// A situação de uma permissão.
389#[derive(Clone, Copy, Debug, PartialEq, Eq)]
390pub enum PermissionState {
391    /// Liberada.
392    Granted,
393    /// Negada (no celular, às vezes só nas configurações do aparelho dá para liberar).
394    Denied,
395    /// Ainda não perguntada: pedir mostra a pergunta do sistema.
396    Prompt,
397    /// O aparelho ou o navegador não tem isso.
398    Unavailable,
399}
400
401impl PermissionState {
402    pub fn name(self) -> &'static str {
403        match self {
404            PermissionState::Granted => "granted",
405            PermissionState::Denied => "denied",
406            PermissionState::Prompt => "prompt",
407            PermissionState::Unavailable => "unavailable",
408        }
409    }
410}
411
412/// Consultar e pedir permissões ao sistema. `done` recebe cada permissão pedida com a
413/// resposta, de qualquer thread.
414/// As permissões como enum do acesso tipado (o argumento do `Permissions.state`).
415impl crate::prop::PropEnum for Permission {
416    const NAMES: &'static [&'static str] = &["camera", "microphone", "location", "notifications", "photos", "contacts", "calendar", "bluetooth"];
417    fn from_index(index: usize) -> Option<Self> {
418        Permission::ALL.get(index).copied()
419    }
420    fn index(self) -> usize {
421        Permission::ALL.iter().position(|p| *p == self).unwrap_or(0)
422    }
423}
424
425impl crate::prop::PropEnum for PermissionState {
426    const NAMES: &'static [&'static str] = &["granted", "denied", "prompt", "unavailable"];
427    fn from_index(index: usize) -> Option<Self> {
428        [PermissionState::Granted, PermissionState::Denied, PermissionState::Prompt, PermissionState::Unavailable].get(index).copied()
429    }
430    fn index(self) -> usize {
431        self as usize
432    }
433}
434
435impl crate::prop::PropEnum for Biometry {
436    const NAMES: &'static [&'static str] = &["none", "fingerprint", "face", "iris", "any"];
437    fn from_index(index: usize) -> Option<Self> {
438        [Biometry::None, Biometry::Fingerprint, Biometry::Face, Biometry::Iris, Biometry::Any].get(index).copied()
439    }
440    fn index(self) -> usize {
441        self as usize
442    }
443}
444
445pub trait PermissionService {
446    fn state(&self, permission: Permission) -> PermissionState;
447    fn request(&mut self, permissions: Vec<Permission>, done: Box<dyn FnOnce(Vec<(Permission, PermissionState)>) + Send>);
448}
449
450/// O tipo de biometria do aparelho.
451#[derive(Clone, Copy, Debug, PartialEq, Eq)]
452pub enum Biometry {
453    /// Sem biometria (ou nenhuma cadastrada).
454    None,
455    Fingerprint,
456    Face,
457    Iris,
458    /// Tem, mas o sistema não diz qual (Windows Hello, a chave do navegador, vários tipos).
459    Any,
460}
461
462impl Biometry {
463    pub fn name(self) -> &'static str {
464        match self {
465            Biometry::None => "none",
466            Biometry::Fingerprint => "fingerprint",
467            Biometry::Face => "face",
468            Biometry::Iris => "iris",
469            Biometry::Any => "any",
470        }
471    }
472}
473
474/// Como terminou a verificação biométrica.
475#[derive(Clone, Debug, PartialEq, Eq)]
476pub enum BiometricResult {
477    Success,
478    /// O usuário desistiu (ou o app foi para o fundo).
479    Cancelled,
480    /// Não reconheceu, bloqueou por tentativas, sem biometria: o motivo.
481    Failed(String),
482}
483
484/// A biometria do aparelho (digital, rosto; o Windows Hello). `done` recebe o resultado,
485/// de qualquer thread.
486pub trait BiometricService {
487    fn availability(&self) -> Biometry;
488    /// Pede a verificação mostrando `reason`. Com `allow_device_credential`, o PIN ou o
489    /// padrão do aparelho também valem.
490    fn authenticate(&mut self, reason: &str, allow_device_credential: bool, done: Box<dyn FnOnce(BiometricResult) + Send>);
491}
492
493/// Imprimir na impressora do sistema: mostra o diálogo de impressão (impressora, cópias,
494/// páginas) e imprime as páginas gravadas. `done` recebe `Ok(true)` (impresso), `Ok(false)`
495/// (cancelado) ou o erro, de qualquer thread.
496pub trait PrintService {
497    fn print(&mut self, title: &str, pages: crate::pages::PageSet, done: Box<dyn FnOnce(Result<bool, String>) + Send>);
498
499    /// A plataforma imprime pelo PDF (abre no visualizador do sistema), e não pelas páginas: o
500    /// `Report` monta o PDF pelo provedor e chama [`PrintService::print_pdf`].
501    fn wants_pdf(&self) -> bool {
502        false
503    }
504
505    /// Imprime um PDF pronto (só quando [`PrintService::wants_pdf`]).
506    fn print_pdf(&mut self, title: &str, pdf: Vec<u8>, done: Box<dyn FnOnce(Result<bool, String>) + Send>) {
507        let _ = (title, pdf);
508        done(Err("esta plataforma não imprime PDF".into()));
509    }
510}
511
512/// Baixar da internet (HTTP GET) sem travar a interface (os blocos do mapa, imagens de
513/// um endereço). `done` recebe o corpo da resposta, ou o erro, de qualquer thread: use o
514/// [`Poster`](crate::Poster) para voltar à interface.
515pub trait HttpService {
516    fn get(&mut self, url: &str, done: Box<dyn FnOnce(Result<Vec<u8>, String>) + Send>);
517}
518
519/// Uma notificação do sistema (o toast do Windows, a notificação do Android).
520#[derive(Clone, Debug, Default, PartialEq)]
521pub struct SystemNotification {
522    /// Quem notifica (o AppUserModelID no Windows: `empresa.app`).
523    pub app_id: String,
524    /// O nome que aparece na notificação.
525    pub app_name: String,
526    pub title: String,
527    pub body: String,
528    /// Imagem (caminho de um PNG), opcional.
529    pub image: String,
530    /// A imagem em PNG já lida (dos assets do app, ou um form desenhado); vence `image`.
531    pub image_png: Vec<u8>,
532    /// Mostrar a imagem grande (embaixo do texto), em vez de miniatura ao lado.
533    pub big_image: bool,
534    /// Identifica a notificação: mostrar de novo com o mesmo número atualiza a anterior.
535    pub id: u32,
536    /// Canal (Android 8+): o usuário liga, desliga e escolhe o som por canal.
537    pub channel: String,
538    pub channel_name: String,
539    pub priority: NotificationPriority,
540    /// Botões da notificação: (identificador, texto).
541    pub actions: Vec<(String, String)>,
542    /// Fixa: o usuário não descarta (uma tarefa em andamento).
543    pub ongoing: bool,
544    /// Barra de progresso (0 a 1); `None`: sem barra.
545    pub progress: Option<f32>,
546    /// Tela cheia (Android): abre o app por cima de tudo, até da tela de bloqueio (uma
547    /// ligação, um alarme). Precisa da permissão `USE_FULL_SCREEN_INTENT`.
548    pub full_screen: bool,
549    /// O componente que recebe `on_click` e `on_action` quando o usuário toca.
550    pub component: Option<crate::ComponentId>,
551}
552
553/// Importância da notificação (no Android, a do canal: som, vibração, aparecer por cima).
554#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
555pub enum NotificationPriority {
556    /// Silenciosa, só na lista.
557    Low,
558    #[default]
559    Default,
560    /// Aparece por cima do app aberto (heads-up), com som.
561    High,
562}
563
564impl crate::PropEnum for NotificationPriority {
565    const NAMES: &'static [&'static str] = &["low", "default", "high"];
566    fn from_index(index: usize) -> Option<Self> {
567        [Self::Low, Self::Default, Self::High].get(index).copied()
568    }
569    fn index(self) -> usize {
570        self as usize
571    }
572}
573
574/// Notificações do sistema.
575pub trait NotificationService {
576    fn notify(&mut self, notification: &SystemNotification) -> Result<(), String>;
577    /// Tira a notificação `id` da lista.
578    fn cancel(&mut self, id: u32) -> Result<(), String> {
579        let _ = id;
580        Ok(())
581    }
582}
583
584/// Abrir endereços e outros apps, compartilhar e pedir algo a outro app (o componente
585/// `AppLink`). O que a plataforma não tem responde com o motivo.
586pub trait LinkService {
587    /// Abre o endereço no app que cuida dele (o navegador, o e-mail, o mapa, o discador).
588    fn open_url(&mut self, url: &str) -> Result<(), String>;
589    /// Abre outro app: o pacote no Android, o executável ou o nome registrado no desktop.
590    fn open_app(&mut self, app: &str) -> Result<(), String> {
591        Err(format!("abrir outro app não existe aqui ({app})"))
592    }
593    /// Compartilha texto e arquivos pela folha do sistema.
594    fn share(&mut self, text: &str, files: &[String]) -> Result<(), String> {
595        let _ = (text, files);
596        Err("compartilhar não existe aqui".into())
597    }
598    /// Pede `action` a outro app (uma `Intent` do Android com `data`): `done` recebe o que ele
599    /// devolveu, de qualquer thread.
600    fn request(&mut self, action: &str, data: &str, done: Box<dyn FnOnce(Result<String, String>) + Send>) {
601        let _ = data;
602        done(Err(format!("pedir a outro app não existe aqui ({action})")));
603    }
604    /// Se registra prefixos em execução (o Windows e o Linux); nas outras plataformas, quem
605    /// registra é a publicação, e o `UrlScheme` só recebe.
606    fn can_register_schemes(&self) -> bool {
607        false
608    }
609    /// Registra o prefixo (`meuapp`, já conferido por [`check_scheme`]) para abrir este app:
610    /// `meuapp://...` chamado por qualquer programa abre o app com o endereço (o componente
611    /// `UrlScheme`). Onde só a publicação registra (macOS, iOS, Android), `Err`.
612    fn register_scheme(&mut self, scheme: &str, description: &str) -> Result<(), String> {
613        let _ = description;
614        Err(format!("registrar o prefixo {scheme}:// em execução não existe aqui (vai na publicação)"))
615    }
616    /// Tira o registro do prefixo, se for deste app.
617    fn unregister_scheme(&mut self, scheme: &str) -> Result<(), String> {
618        Err(format!("tirar o registro do prefixo {scheme}:// não existe aqui"))
619    }
620    /// Se o prefixo abre este app.
621    fn scheme_registered(&mut self, scheme: &str) -> bool {
622        let _ = scheme;
623        false
624    }
625    /// Passa a receber os links que outra cópia do app repassar (o app já aberto, chamado de
626    /// novo por um link): `on_link` recebe o endereço, de qualquer thread.
627    fn receive_links(&mut self, on_link: Box<dyn Fn(String) + Send>) {
628        let _ = on_link;
629    }
630}
631
632/// Os prefixos que um app não registra: os da web, os do sistema e os que rodam código.
633const RESERVED_SCHEMES: &[&str] = &[
634    "http", "https", "file", "ftp", "ftps", "mailto", "tel", "sms", "data", "javascript", "vbscript", "about", "blob", "ws", "wss", "shell", "search",
635    "search-ms", "res", "its", "mk", "hcp", "callto", "news", "nntp", "telnet", "ldap", "ssh", "sftp", "smb", "git", "magnet", "steam", "zoommtg",
636];
637
638/// Confere o prefixo de um `UrlScheme` e devolve em minúsculas: letra, depois letras,
639/// números, `+`, `-` ou `.` (o esquema de URL), de 3 a 64 caracteres, fora dos do sistema
640/// (`http`, `file`, `ms-*`...).
641pub fn check_scheme(scheme: &str) -> Result<String, String> {
642    let s = scheme.trim().trim_end_matches("://").trim_end_matches(':').to_ascii_lowercase();
643    let valid = s.len() >= 3
644        && s.len() <= 64
645        && s.starts_with(|c: char| c.is_ascii_lowercase())
646        && s.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || matches!(c, '+' | '-' | '.'));
647    if !valid {
648        return Err(crate::messages::tf("prefixo inválido: {0} (letras, números, + - ., de 3 a 64)", &[&scheme]));
649    }
650    if RESERVED_SCHEMES.contains(&s.as_str()) || s.starts_with("ms-") || s.starts_with("microsoft") || s.starts_with("windows") {
651        return Err(crate::messages::tf("o prefixo {0} é do sistema", &[&s]));
652    }
653    Ok(s)
654}
655
656/// Os links que abriram o app (a linha de comando), até um `UrlScheme` do prefixo pegar: o
657/// form ainda nem existe quando o app abre. Separados da fila do `AppLink`, que pega todos.
658static STARTUP_LINKS: std::sync::Mutex<Vec<String>> = std::sync::Mutex::new(Vec::new());
659
660/// A plataforma guarda o link que abriu o app.
661pub fn push_startup_link(url: String) {
662    if let Ok(mut list) = STARTUP_LINKS.lock() {
663        list.push(url);
664    }
665}
666
667/// Tira os links que abriram o app com o prefixo `scheme` (já em minúsculas).
668pub fn take_startup_links(scheme: &str) -> Vec<String> {
669    let Ok(mut list) = STARTUP_LINKS.lock() else { return Vec::new() };
670    let (mine, rest): (Vec<String>, Vec<String>) = std::mem::take(&mut *list).into_iter().partition(|url| link_scheme(url).as_deref() == Some(scheme));
671    *list = rest;
672    mine
673}
674
675/// O prefixo de um endereço, em minúsculas (`MeuApp://x` → `meuapp`).
676pub fn link_scheme(url: &str) -> Option<String> {
677    let (scheme, _) = url.split_once(':')?;
678    (!scheme.is_empty()).then(|| scheme.to_ascii_lowercase())
679}
680
681/// Os sensores do aparelho (os componentes da categoria "Dispositivo").
682#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
683pub enum Sensor {
684    /// `[latitude, longitude, precisão em metros, altitude, velocidade em m/s]`.
685    Location,
686    /// `[carga de 0 a 1, carregando 0/1]`.
687    Battery,
688    /// `[conectado 0/1, tipo: 0 nenhum, 1 Wi-Fi, 2 celular, 3 cabo, 4 outro]`.
689    Network,
690    /// A aceleração com a gravidade, em m/s²: `[x, y, z]`.
691    Motion,
692    /// `[rumo em graus, 0 = norte]`.
693    Compass,
694    /// `[distância em cm, perto 0/1]`.
695    Proximity,
696    /// `[lux]`.
697    Light,
698}
699
700/// Lê os sensores do aparelho. A plataforma guarda a última leitura de cada um (os
701/// componentes consultam num timer) e só mede os ligados (bateria e rede valem sempre).
702pub trait SensorService {
703    /// O aparelho tem esse sensor.
704    fn available(&self, sensor: Sensor) -> bool;
705    /// Começa ou para de medir (a localização pede a permissão na primeira vez).
706    fn set_active(&mut self, sensor: Sensor, on: bool);
707    /// A última leitura (`None`: ainda não mediu).
708    fn read(&mut self, sensor: Sensor) -> Option<Vec<f64>>;
709    /// Vibra por `ms` milissegundos; `false` se o aparelho não vibra.
710    fn vibrate(&mut self, ms: u32) -> bool {
711        let _ = ms;
712        false
713    }
714}
715
716/// Os botões de um controle de jogo (o componente `Gamepad`), com os nomes do Xbox; no
717/// PlayStation, `a` = ✕, `b` = ○, `x` = □ e `y` = △. O bit `i` de [`GamepadState::buttons`]
718/// é o botão `GAMEPAD_BUTTONS[i]`.
719pub const GAMEPAD_BUTTONS: [&str; 17] =
720    ["a", "b", "x", "y", "lb", "rb", "lt", "rt", "back", "start", "l3", "r3", "up", "down", "left", "right", "guide"];
721
722/// Um controle de jogo conectado.
723#[derive(Clone, Debug, Default, PartialEq)]
724pub struct GamepadState {
725    pub name: String,
726    /// Os botões apertados (um bit por nome de [`GAMEPAD_BUTTONS`]).
727    pub buttons: u32,
728    /// `[esquerdo x, esquerdo y, direito x, direito y, gatilho esquerdo, gatilho direito]`:
729    /// os analógicos de -1 a 1 (y positivo para baixo, como na tela), os gatilhos de 0 a 1.
730    pub axes: [f32; 6],
731}
732
733impl GamepadState {
734    /// Marca o botão pelo nome (os da plataforma usam ao montar o estado).
735    pub fn set_button(&mut self, name: &str, down: bool) {
736        if let Some(i) = GAMEPAD_BUTTONS.iter().position(|b| *b == name) {
737            if down {
738                self.buttons |= 1 << i;
739            } else {
740                self.buttons &= !(1 << i);
741            }
742        }
743    }
744
745    pub fn pressed(&self, name: &str) -> bool {
746        GAMEPAD_BUTTONS.iter().position(|b| *b == name).is_some_and(|i| self.buttons & (1 << i) != 0)
747    }
748}
749
750/// Os controles de jogo (o componente `Gamepad`). O componente consulta a cada quadro.
751pub trait GamepadService {
752    /// Os controles conectados agora, na ordem em que entraram.
753    fn pads(&mut self) -> Vec<GamepadState>;
754    /// Vibra o controle `index` com a força (0 a 1) por `ms`; `false` se ele não vibra.
755    fn rumble(&mut self, index: usize, strength: f32, ms: u32) -> bool {
756        let _ = (index, strength, ms);
757        false
758    }
759}
760
761/// Ligações e a tela de bloqueio (os componentes `Phone` e `LockScreen`; hoje, o Android).
762pub trait PhoneService {
763    /// Abre o discador com o número (sem permissão).
764    fn dial(&mut self, number: &str) -> Result<(), String>;
765    /// Liga direto (a permissão `CALL_PHONE`, pedida na primeira vez).
766    fn call(&mut self, number: &str) -> Result<(), String>;
767    /// Acompanha o estado das chamadas (`READ_PHONE_STATE`).
768    fn watch(&mut self, on: bool);
769    /// O estado agora (`idle`, `ringing`, `dialing`, `active`, `holding`) e o número (quando o
770    /// sistema informa).
771    fn state(&mut self) -> (String, String);
772    /// O modo "app de telefone": pede para ser o discador padrão (o `InCallService`).
773    fn request_dialer(&mut self) -> Result<(), String> {
774        Err("não existe aqui".into())
775    }
776    /// No modo "app de telefone": atender, recusar, desligar.
777    fn answer(&mut self) -> bool {
778        false
779    }
780    fn reject(&mut self) -> bool {
781        false
782    }
783    fn hang_up(&mut self) -> bool {
784        false
785    }
786    /// As últimas `max` chamadas (`READ_CALL_LOG`): `número|tipo|quando|segundos` por linha.
787    fn history(&mut self, max: u32) -> Result<String, String> {
788        let _ = max;
789        Err("não existe aqui".into())
790    }
791    /// O form sobre a tela de bloqueio e acender a tela ao abrir.
792    fn lock_screen(&mut self, show_when_locked: bool, turn_screen_on: bool);
793    /// Pede ao sistema para destravar (o usuário confirma).
794    fn dismiss_keyguard(&mut self);
795}
796
797/// O serviço em primeiro plano do sistema (o Android: a notificação fixa que mantém o
798/// processo vivo com a tela fechada). `kind`: o tipo do Android 14+ (`dataSync`, `location`,
799/// `mediaPlayback`, `connectedDevice`...); `keep_alive`: o sistema reinicia o serviço (e no
800/// boot) e o app pede a isenção da otimização de bateria.
801pub trait BackgroundHost {
802    fn start(&mut self, title: &str, text: &str, kind: &str, keep_alive: bool) -> Result<(), String>;
803    fn stop(&mut self);
804}
805
806/// O que chega de fora para o app: um link que abriu o app (`on_link`) ou algo que outro
807/// app compartilhou com ele (`on_shared`: o texto, ou os arquivos separados por `;`).
808#[derive(Clone, Debug, PartialEq, Eq)]
809pub enum Incoming {
810    Link(String),
811    Shared(String),
812}
813
814static INCOMING: std::sync::Mutex<Vec<Incoming>> = std::sync::Mutex::new(Vec::new());
815
816/// A plataforma entrega o que chegou de fora (de qualquer thread). Fica guardado até um
817/// `AppLink` pegar: o app aberto pelo próprio link ainda nem criou o form.
818pub fn push_incoming(item: Incoming) {
819    if let Ok(mut list) = INCOMING.lock() {
820        list.push(item);
821    }
822}
823
824/// Tira da fila o que chegou de fora (o `AppLink` chama).
825pub fn take_incoming() -> Vec<Incoming> {
826    INCOMING.lock().map(|mut list| std::mem::take(&mut *list)).unwrap_or_default()
827}
828
829/// Desenho fora da tela: o `Ui` pinta um componente numa imagem (a notificação com "um
830/// form inteiro", capturas). A plataforma fornece com o renderizador dela.
831pub trait OffscreenService {
832    /// `width` x `height` em unidades lógicas, multiplicadas por `scale` em pixels.
833    fn render_png(&self, width: u32, height: u32, scale: f32, background: crate::Color, paint: &mut dyn FnMut(&mut dyn crate::Canvas)) -> Option<Vec<u8>>;
834
835    /// Os pixels RGBA (4 bytes por pixel, linha a linha, sem pré-multiplicar) de `width` x
836    /// `height` **pixels**, com `scale` pixels por unidade no canvas: o mesmo desenho do
837    /// `render_png`, sem codificar (o recorte de um print, `Ui::render_rgba`). `None`: o
838    /// serviço não sabe.
839    fn render_rgba(&self, _width: u32, _height: u32, _scale: f32, _background: crate::Color, _paint: &mut dyn FnMut(&mut dyn crate::Canvas)) -> Option<Vec<u8>> {
840        None
841    }
842
843    /// Os pixels RGBA (opacos) de `width` x `height` (em pixels, escala 1): inteiro, ou só
844    /// `area` repintada por cima de `previous` (do mesmo tamanho), o mesmo caminho da janela
845    /// quando repinta por parte. A conferência da pintura por parte dos componentes usa
846    /// (`aylis::headless::Headless::check_partial_paint`). `None`: o serviço não sabe.
847    fn render_area_rgba(
848        &self,
849        _width: u32,
850        _height: u32,
851        _background: crate::Color,
852        _over: Option<(&[u8], crate::geometry::RectF)>,
853        _paint: &mut dyn FnMut(&mut dyn crate::Canvas),
854    ) -> Option<Vec<u8>> {
855        None
856    }
857}
858
859/// O que a janela de um form mostra de verdade, com as vistas nativas por cima (o WebView,
860/// que o desenho fora da tela não tem). O relatório do Tabernáculo, W10.
861pub trait WindowCaptureService {
862    /// A área do form em pixels RGBA (largura, altura, pixels); `None` sem janela aberta.
863    fn capture(&mut self, form: crate::ComponentId) -> Option<(u32, u32, Vec<u8>)>;
864}
865
866/// Conjunto de serviços fornecidos pela plataforma. Todos são opcionais.
867#[derive(Default)]
868pub struct Services {
869    /// A captura da janela (a foto com o WebView).
870    pub window_capture: Option<Box<dyn WindowCaptureService>>,
871    pub offscreen: Option<Box<dyn OffscreenService>>,
872    pub window: Option<Box<dyn WindowService>>,
873    pub timer: Option<Box<dyn TimerService>>,
874    pub clipboard: Option<Box<dyn ClipboardService>>,
875    /// O que foi copiado por último, para o que a plataforma não guarda ([`crate::clipboard`]).
876    pub clipboard_local: crate::clipboard::LocalClipboard,
877    pub cursor: Option<Box<dyn CursorService>>,
878    pub screen: Option<Box<dyn ScreenService>>,
879    pub text_input: Option<Box<dyn TextInputService>>,
880    pub locale: Option<Box<dyn LocaleService>>,
881    pub text: Option<Box<dyn TextService>>,
882    pub resources: Option<Box<dyn ResourceService>>,
883    pub forms: Option<Box<dyn FormFactory>>,
884    pub file_dialogs: Option<Box<dyn FileDialogService>>,
885    /// Consultar e pedir permissões (câmera, localização...): o componente `Permissions`.
886    pub permissions: Option<Box<dyn PermissionService>>,
887    /// Digital, rosto, Windows Hello: o componente `Biometrics`.
888    pub biometrics: Option<Box<dyn BiometricService>>,
889    pub http: Option<Box<dyn HttpService>>,
890    pub notifications: Option<Box<dyn NotificationService>>,
891    /// Abrir endereços e apps, compartilhar: o componente `AppLink`.
892    pub links: Option<Box<dyn LinkService>>,
893    /// Localização, bateria, rede, movimento, bússola, proximidade, luz e vibração.
894    pub sensors: Option<Box<dyn SensorService>>,
895    /// O serviço em primeiro plano (o `BackgroundService`); sem ele, a lógica roda enquanto o
896    /// app roda.
897    pub background: Option<Box<dyn BackgroundHost>>,
898    /// Ligações e tela de bloqueio (`Phone`, `LockScreen`).
899    pub phone: Option<Box<dyn PhoneService>>,
900    /// Controles de jogo (`Gamepad`).
901    pub gamepads: Option<Box<dyn GamepadService>>,
902    pub printer: Option<Box<dyn PrintService>>,
903    /// O PDF padrão (o `Report` sem provedor ligado, a impressão fora do Windows): o
904    /// `aylis-providers` põe o dele ao registrar as classes. Sem ele, exportar PDF é um erro.
905    pub pdf: Option<Box<dyn crate::providers::PdfProvider>>,
906    /// Correção e sugestão de texto dos campos (`spellcheck`, `autocomplete`): o motor
907    /// nativo da plataforma, ou outro que o app ponha no lugar ([`crate::textassist`]).
908    pub text_assist: Option<Box<dyn crate::textassist::TextAssist>>,
909    /// Tags NFC (`Nfc`).
910    pub nfc: Option<Box<dyn NfcService>>,
911    /// Bluetooth BLE e clássico (`Bluetooth`).
912    pub bluetooth: Option<Box<dyn BluetoothService>>,
913    /// Notificações push (`PushNotifications`): FCM, APNs, Web Push, WNS, UnifiedPush.
914    pub push: Option<Box<dyn PushService>>,
915    /// Os controles de mídia do sistema (`MediaSession`): o SMTC do Windows, o MPRIS do Linux,
916    /// o Media Session do navegador, o `MPNowPlayingInfoCenter` do macOS e do iOS.
917    pub media_session: Option<Box<dyn MediaSessionService>>,
918    /// As ações do aparelho (`WakeAppAction`, `NotifyAction`) e as regras do `PushTrigger`
919    /// executadas pela plataforma, também com o app fechado. Sem ele, os componentes fazem o
920    /// que dá com o app aberto (mostrar o form, a notificação comum).
921    pub actions: Option<Box<dyn ActionService>>,
922    /// Automação OLE dos programas instalados (o `OleObject`): só no Windows.
923    pub ole: Option<Box<dyn OleService>>,
924    /// O WMI do Windows (o `WmiQuery`): consultas e eventos do sistema.
925    pub wmi: Option<Box<dyn WmiService>>,
926}
927
928/// Uma tag NFC encostada.
929#[derive(Clone, Debug, Default, PartialEq, Eq)]
930pub struct NfcTag {
931    /// O id em hexadecimal com dois pontos (`04:A2:1B:...`; [`crate::ndef::id_text`]).
932    pub id: String,
933    /// A tecnologia (`NfcA`, `MifareUltralight`, `IsoDep`...), como a plataforma informa.
934    pub tech: String,
935    /// A mensagem NDEF (vazia numa tag sem NDEF).
936    pub records: Vec<crate::ndef::NdefRecord>,
937    /// Dá para gravar nela.
938    pub writable: bool,
939}
940
941/// O que o [`NfcService`] tem para contar.
942#[derive(Clone, Debug, PartialEq, Eq)]
943pub enum NfcEvent {
944    Tag(NfcTag),
945    /// A gravação pedida terminou.
946    Written,
947    Error(String),
948}
949
950/// Ler e gravar tags NFC (o componente `Nfc`). O componente consulta [`NfcService::poll`]
951/// num timer; ler só funciona com o app na frente.
952pub trait NfcService {
953    /// Há NFC aqui (o aparelho tem, ou há um leitor USB ligado).
954    fn available(&self) -> bool;
955    /// O NFC está ligado (no Android dá para desligar nas configurações).
956    fn enabled(&self) -> bool {
957        self.available()
958    }
959    /// Começa ou para de ler as tags que encostarem.
960    fn set_reading(&mut self, on: bool);
961    /// Grava a mensagem NDEF ([`crate::ndef::encode`]) na próxima tag que encostar; o
962    /// resultado chega como [`NfcEvent::Written`] ou [`NfcEvent::Error`].
963    fn write(&mut self, message: Vec<u8>);
964    /// Desiste da gravação pendente.
965    fn cancel_write(&mut self) {}
966    /// O que aconteceu desde a última consulta.
967    fn poll(&mut self) -> Vec<NfcEvent>;
968}
969
970/// Um aparelho Bluetooth achado.
971#[derive(Clone, Debug, Default, PartialEq, Eq)]
972pub struct BleDevice {
973    /// O endereço (Android, Windows, Linux) ou o identificador que o sistema dá (macOS, iOS,
974    /// navegador).
975    pub id: String,
976    pub name: String,
977    /// A força do sinal em dBm (0: o sistema não informou).
978    pub rssi: i32,
979}
980
981/// Uma característica de um aparelho conectado.
982#[derive(Clone, Debug, Default, PartialEq, Eq)]
983pub struct BleCharacteristic {
984    pub service: String,
985    pub characteristic: String,
986    /// `read`, `write`, `write_without_response`, `notify`, `indicate`.
987    pub properties: Vec<String>,
988}
989
990/// O que o [`BluetoothService`] tem para contar.
991#[derive(Clone, Debug, PartialEq, Eq)]
992pub enum BluetoothEvent {
993    Found(BleDevice),
994    /// A procura parou (pedido, erro ou o sistema parou).
995    ScanStopped,
996    /// Conectado (BLE, com as características; o clássico, sem).
997    Connected { device: String, services: Vec<BleCharacteristic> },
998    Disconnected(String),
999    /// Uma leitura pedida ou um aviso (`notify`/`indicate`).
1000    Value { device: String, characteristic: String, data: Vec<u8> },
1001    Written { device: String, characteristic: String },
1002    /// Bytes que chegaram pelo canal serial (clássico).
1003    Received { device: String, data: Vec<u8> },
1004    Error(String),
1005}
1006
1007/// Bluetooth (o componente `Bluetooth`): BLE e o canal serial do clássico (SPP/RFCOMM). As
1008/// operações respondem depois, pelo [`BluetoothService::poll`]; os uuids chegam inteiros e
1009/// em minúsculas ([`ble_uuid`]).
1010pub trait BluetoothService {
1011    fn available(&self) -> bool;
1012    /// O Bluetooth está ligado.
1013    fn enabled(&self) -> bool {
1014        self.available()
1015    }
1016    /// Começa (com os serviços que o aparelho anuncia e parte do nome; vazios, todos) ou
1017    /// para de procurar.
1018    fn scan(&mut self, on: bool, services: Vec<String>, name: String);
1019    fn connect(&mut self, device: &str);
1020    fn disconnect(&mut self, device: &str);
1021    fn read(&mut self, device: &str, service: &str, characteristic: &str);
1022    fn write(&mut self, device: &str, service: &str, characteristic: &str, data: Vec<u8>, with_response: bool);
1023    /// Liga ou desliga os avisos de mudança (`notify` ou `indicate`).
1024    fn subscribe(&mut self, device: &str, service: &str, characteristic: &str, on: bool);
1025    /// Os aparelhos pareados (clássico): id e nome.
1026    fn paired(&mut self) -> Vec<(String, String)> {
1027        Vec::new()
1028    }
1029    /// Abre o canal serial (SPP) com um pareado; conecta depois ([`BluetoothEvent::Connected`]).
1030    fn open_serial(&mut self, device: &str) -> Result<(), String> {
1031        let _ = device;
1032        Err(crate::messages::t("o Bluetooth clássico não está disponível aqui"))
1033    }
1034    fn send_serial(&mut self, device: &str, data: Vec<u8>) -> Result<(), String> {
1035        let _ = (device, data);
1036        Err(crate::messages::t("o Bluetooth clássico não está disponível aqui"))
1037    }
1038    fn close_serial(&mut self, device: &str) {
1039        let _ = device;
1040    }
1041    /// O que aconteceu desde a última consulta.
1042    fn poll(&mut self) -> Vec<BluetoothEvent>;
1043}
1044
1045/// O uuid inteiro e em minúsculas: a forma curta do Bluetooth SIG (`180D`, `0x2A37`) vira
1046/// `0000180d-0000-1000-8000-00805f9b34fb`.
1047pub fn ble_uuid(text: &str) -> String {
1048    let t = text.trim().trim_start_matches("0x").trim_start_matches("0X").to_ascii_lowercase();
1049    if (t.len() == 4 || t.len() == 8) && t.chars().all(|c| c.is_ascii_hexdigit()) {
1050        format!("{t:0>8}-0000-1000-8000-00805f9b34fb")
1051    } else {
1052        t
1053    }
1054}
1055
1056/// Uma notificação push que chegou.
1057#[derive(Clone, Debug, Default, PartialEq, Eq)]
1058pub struct PushMessage {
1059    /// O id que o serviço deu (vazio se ele não deu).
1060    pub id: String,
1061    /// O título e o texto da parte "notification" (vazios numa mensagem só de dados).
1062    pub title: String,
1063    pub body: String,
1064    /// Os dados do app, como um objeto JSON (`{}` sem dados).
1065    pub data: String,
1066}
1067
1068/// O que chega das notificações push.
1069#[derive(Clone, Debug, PartialEq, Eq)]
1070pub enum PushEvent {
1071    /// O endereço deste aparelho no serviço (o token do FCM, o do APNs em hexadecimal, a
1072    /// assinatura do Web Push em JSON, o canal do WNS, o endpoint do UnifiedPush): o app
1073    /// manda ao servidor dele, que usa para enviar.
1074    Token(String),
1075    /// Uma mensagem chegou com o app aberto.
1076    Message(PushMessage),
1077    /// O usuário tocou na notificação (o app abriu ou voltou para a frente por ela).
1078    Opened(PushMessage),
1079    Error(String),
1080}
1081
1082/// A configuração do registro. Cada serviço usa a parte dele: o FCM (Android), as quatro
1083/// primeiras, que estão no `google-services.json`; o Web Push, a chave VAPID pública.
1084#[derive(Clone, Debug, Default, PartialEq, Eq)]
1085pub struct PushConfig {
1086    /// O número do projeto do Firebase (`project_number`, o "sender id").
1087    pub sender_id: String,
1088    /// O id do projeto (`project_id`).
1089    pub project_id: String,
1090    /// O id do app no Firebase (`mobilesdk_app_id`: `1:123:android:abc`).
1091    pub app_id: String,
1092    /// A chave da API (`current_key`).
1093    pub api_key: String,
1094    /// A chave VAPID pública (base64url) do servidor que envia o Web Push.
1095    pub vapid_key: String,
1096    /// Com o app aberto, a mensagem com título também aparece como notificação do sistema
1097    /// (sem isso, só o `on_message`).
1098    pub show_in_foreground: bool,
1099}
1100
1101/// Notificações push (o componente `PushNotifications`). O registro responde depois: o
1102/// token, as mensagens e os toques chegam por [`push_event`] (de qualquer thread, quando o
1103/// sistema chama) ou pelo [`PushService::poll`].
1104pub trait PushService {
1105    /// Há um serviço de push aqui (no Android, o Google Play Services; no navegador, a Push
1106    /// API e o service worker).
1107    fn available(&self) -> bool;
1108    /// O serviço: `fcm`, `apns`, `webpush`, `wns` ou `unifiedpush` (o servidor precisa saber
1109    /// por onde enviar).
1110    fn provider(&self) -> &'static str;
1111    /// Pede a permissão de notificar (onde é preciso) e registra; o token chega como
1112    /// [`PushEvent::Token`].
1113    fn register(&mut self, config: &PushConfig);
1114    /// Deixa de receber (o token deixa de valer).
1115    fn unregister(&mut self) {}
1116    /// A própria plataforma mostra a notificação da mensagem (Android, iOS, macOS,
1117    /// navegador). Sem isso (o WNS raw, o UnifiedPush), o componente mostra pelo
1118    /// [`NotificationService`] com o `show_in_foreground`.
1119    fn shows_notifications(&self) -> bool {
1120        true
1121    }
1122    /// O que aconteceu desde a última consulta (as plataformas que guardam numa fila).
1123    fn poll(&mut self) -> Vec<PushEvent> {
1124        Vec::new()
1125    }
1126}
1127
1128/// O que toca agora, para os controles de mídia do sistema (o quadro do volume do Windows, o
1129/// painel do Linux, a Central de Controle, a tela bloqueada).
1130#[derive(Clone, Debug, Default, PartialEq)]
1131pub struct NowPlaying {
1132    pub title: String,
1133    pub artist: String,
1134    pub album: String,
1135    /// Em segundos (0: não se sabe).
1136    pub duration: f64,
1137    /// Em segundos.
1138    pub position: f64,
1139    pub playing: bool,
1140    /// A capa (PNG ou JPEG, como está no arquivo).
1141    pub cover: Option<Vec<u8>>,
1142    /// Há faixa seguinte e anterior (os botões do sistema ficam ligados).
1143    pub can_next: bool,
1144    pub can_previous: bool,
1145}
1146
1147/// O que o sistema pede ao app (as teclas de mídia, os botões do painel e do fone).
1148#[derive(Clone, Copy, Debug, PartialEq)]
1149pub enum MediaCommand {
1150    Play,
1151    Pause,
1152    /// Tocar ou pausar (a tecla única dos teclados).
1153    Toggle,
1154    Stop,
1155    Next,
1156    Previous,
1157    /// Ir para a posição, em segundos.
1158    Seek(f64),
1159}
1160
1161impl MediaCommand {
1162    /// O nome do comando (`play`, `pause`, `toggle`, `stop`, `next`, `previous`, `seek`).
1163    pub fn name(self) -> &'static str {
1164        match self {
1165            MediaCommand::Play => "play",
1166            MediaCommand::Pause => "pause",
1167            MediaCommand::Toggle => "toggle",
1168            MediaCommand::Stop => "stop",
1169            MediaCommand::Next => "next",
1170            MediaCommand::Previous => "previous",
1171            MediaCommand::Seek(_) => "seek",
1172        }
1173    }
1174}
1175
1176/// Quem recebe os comandos do sistema (de qualquer thread: o componente repassa à tela).
1177pub type MediaCommandSink = std::sync::Arc<dyn Fn(MediaCommand) + Send + Sync>;
1178
1179/// Os controles de mídia do sistema (o componente `MediaSession`; decidido em 21/11). Onde
1180/// não existe, o serviço fica vazio e o componente não liga.
1181pub trait MediaSessionService {
1182    /// Começa a sessão do app: `owner` é o form (o Windows liga a sessão a uma janela), e os
1183    /// comandos do sistema chegam por `commands`. Erro: não deu para começar aqui.
1184    fn start(&mut self, owner: Option<crate::ComponentId>, commands: MediaCommandSink) -> Result<(), String>;
1185    /// O que toca agora (o título, a capa, tocando ou pausado).
1186    fn update(&mut self, now: &NowPlaying);
1187    /// Termina a sessão (o app sai dos controles do sistema).
1188    fn stop(&mut self);
1189}
1190
1191static PUSH_EVENTS: std::sync::Mutex<Vec<PushEvent>> = std::sync::Mutex::new(Vec::new());
1192
1193/// A plataforma entrega um evento de push (de qualquer thread). Fica guardado até o
1194/// `PushNotifications` pegar: o toque que abriu o app chega antes de o form existir.
1195pub fn push_event(event: PushEvent) {
1196    if let Ok(mut list) = PUSH_EVENTS.lock() {
1197        list.push(event);
1198    }
1199}
1200
1201/// Tira da fila os eventos de push (o `PushNotifications` chama).
1202pub fn take_push_events() -> Vec<PushEvent> {
1203    PUSH_EVENTS.lock().map(|mut list| std::mem::take(&mut *list)).unwrap_or_default()
1204}
1205
1206/// Uma linha de evento de push no formato que as plataformas com código fora do Rust usam
1207/// (o Java do Android, o service worker): campos separados por tab, `token	<token>`,
1208/// `message	<id>	<título>	<texto>	<dados JSON>`, `opened	...` e `error	<mensagem>`.
1209pub fn parse_push_line(line: &str) -> Option<PushEvent> {
1210    let mut f = line.split('\t');
1211    let kind = f.next()?;
1212    let mut next = || f.next().unwrap_or_default().to_string();
1213    match kind {
1214        "token" => Some(PushEvent::Token(next())),
1215        "error" => Some(PushEvent::Error(next())),
1216        "message" | "opened" => {
1217            let mut m = PushMessage { id: next(), title: next(), body: next(), data: next() };
1218            if m.data.trim().is_empty() {
1219                m.data = "{}".into();
1220            }
1221            Some(if kind == "message" { PushEvent::Message(m) } else { PushEvent::Opened(m) })
1222        }
1223        _ => None,
1224    }
1225}
1226
1227/// O valor de `key` num objeto JSON de um nível (os dados do push são texto → texto): o
1228/// texto sem as aspas, ou o valor como está (número, `true`, objeto).
1229pub fn json_field(json: &str, key: &str) -> Option<String> {
1230    let chars: Vec<char> = json.chars().collect();
1231    let mut i = 0;
1232    let skip_ws = |i: &mut usize| {
1233        while *i < chars.len() && chars[*i].is_whitespace() {
1234            *i += 1;
1235        }
1236    };
1237    // Lê um texto entre aspas a partir de `i` (em cima da aspa).
1238    let read_string = |i: &mut usize| -> Option<String> {
1239        if chars.get(*i) != Some(&'"') {
1240            return None;
1241        }
1242        *i += 1;
1243        let mut out = String::new();
1244        while *i < chars.len() {
1245            let c = chars[*i];
1246            *i += 1;
1247            match c {
1248                '"' => return Some(out),
1249                '\\' => {
1250                    let e = *chars.get(*i)?;
1251                    *i += 1;
1252                    match e {
1253                        'n' => out.push('\n'),
1254                        't' => out.push('\t'),
1255                        'r' => out.push('\r'),
1256                        'b' => out.push('\u{8}'),
1257                        'f' => out.push('\u{c}'),
1258                        'u' => {
1259                            let hex: String = chars.get(*i..*i + 4)?.iter().collect();
1260                            *i += 4;
1261                            let mut code = u32::from_str_radix(&hex, 16).ok()?;
1262                            // Par substituto (emoji): 😀.
1263                            if (0xD800..0xDC00).contains(&code) && chars.get(*i) == Some(&'\\') && chars.get(*i + 1) == Some(&'u') {
1264                                let low: String = chars.get(*i + 2..*i + 6)?.iter().collect();
1265                                if let Ok(low) = u32::from_str_radix(&low, 16) {
1266                                    *i += 6;
1267                                    code = 0x10000 + ((code - 0xD800) << 10) + (low.wrapping_sub(0xDC00) & 0x3FF);
1268                                }
1269                            }
1270                            out.push(char::from_u32(code).unwrap_or('\u{FFFD}'));
1271                        }
1272                        other => out.push(other),
1273                    }
1274                }
1275                c => out.push(c),
1276            }
1277        }
1278        None
1279    };
1280    skip_ws(&mut i);
1281    if chars.get(i) != Some(&'{') {
1282        return None;
1283    }
1284    i += 1;
1285    loop {
1286        skip_ws(&mut i);
1287        if chars.get(i) == Some(&'}') || i >= chars.len() {
1288            return None;
1289        }
1290        let name = read_string(&mut i)?;
1291        skip_ws(&mut i);
1292        if chars.get(i) != Some(&':') {
1293            return None;
1294        }
1295        i += 1;
1296        skip_ws(&mut i);
1297        let value = if chars.get(i) == Some(&'"') {
1298            read_string(&mut i)?
1299        } else {
1300            // Número, literal, objeto ou lista: até a vírgula ou o fecha do mesmo nível.
1301            let start = i;
1302            let (mut depth, mut quoted) = (0i32, false);
1303            while i < chars.len() {
1304                let c = chars[i];
1305                if quoted {
1306                    if c == '\\' {
1307                        i += 1;
1308                    } else if c == '"' {
1309                        quoted = false;
1310                    }
1311                } else {
1312                    match c {
1313                        '"' => quoted = true,
1314                        '{' | '[' => depth += 1,
1315                        '}' | ']' if depth == 0 => break,
1316                        '}' | ']' => depth -= 1,
1317                        ',' if depth == 0 => break,
1318                        _ => {}
1319                    }
1320                }
1321                i += 1;
1322            }
1323            chars[start..i.min(chars.len())].iter().collect::<String>().trim().to_string()
1324        };
1325        if name == key {
1326            return Some(value);
1327        }
1328        skip_ws(&mut i);
1329        if chars.get(i) == Some(&',') {
1330            i += 1;
1331        }
1332    }
1333}
1334
1335/// A mensagem de um push que chega cru (o WNS do tipo raw, o UnifiedPush, o Web Push): um
1336/// objeto JSON com `title`, `body`, `id` e `data` (objeto), ou no formato do FCM
1337/// (`{"notification": {"title", "body"}, "data": {...}}`). O que não for JSON vira o texto.
1338pub fn push_message_from_payload(text: &str) -> PushMessage {
1339    let text = text.trim();
1340    if !text.starts_with('{') {
1341        return PushMessage { body: text.to_string(), data: "{}".into(), ..Default::default() };
1342    }
1343    let notification = json_field(text, "notification").unwrap_or_default();
1344    let pick = |key: &str| json_field(text, key).or_else(|| json_field(&notification, key)).unwrap_or_default();
1345    let data = json_field(text, "data").filter(|d| d.trim_start().starts_with('{')).unwrap_or_else(|| "{}".into());
1346    PushMessage { id: pick("id"), title: pick("title"), body: pick("body"), data }
1347}
1348
1349/// Um texto de modelo com os dados de uma mensagem: `{chave}` vira o valor da chave no
1350/// objeto JSON `data` (vazio se não houver); `{{` e `}}` são as chaves literais.
1351pub fn render_template(template: &str, data: &str) -> String {
1352    let mut out = String::new();
1353    let mut rest = template;
1354    while let Some(i) = rest.find(['{', '}']) {
1355        out.push_str(&rest[..i]);
1356        let tail = &rest[i..];
1357        if tail.starts_with("{{") || tail.starts_with("}}") {
1358            out.push_str(&tail[..1]);
1359            rest = &tail[2..];
1360        } else if let (true, Some(end)) = (tail.starts_with('{'), tail.find('}')) {
1361            out.push_str(&json_field(data, tail[1..end].trim()).unwrap_or_default());
1362            rest = &tail[end + 1..];
1363        } else {
1364            out.push_str(&tail[..1]);
1365            rest = &tail[1..];
1366        }
1367    }
1368    out.push_str(rest);
1369    out
1370}
1371
1372/// Um filtro de dados (`kind=call;priority=high`): todas as condições valem (`chave=valor`,
1373/// `chave!=valor`, `chave` sozinha: existe e não é vazia). Vazio: aceita tudo.
1374pub fn data_matches(filter: &str, data: &str) -> bool {
1375    filter.split(';').map(str::trim).filter(|c| !c.is_empty()).all(|c| {
1376        if let Some((k, v)) = c.split_once("!=") {
1377            json_field(data, k.trim()).unwrap_or_default() != v.trim()
1378        } else if let Some((k, v)) = c.split_once('=') {
1379            json_field(data, k.trim()).unwrap_or_default() == v.trim()
1380        } else {
1381            json_field(data, c).is_some_and(|v| !v.is_empty())
1382        }
1383    })
1384}
1385
1386/// O texto em JSON (com as aspas), para as plataformas que montam JSON à mão.
1387pub fn json_quote(text: &str) -> String {
1388    let mut out = String::with_capacity(text.len() + 2);
1389    out.push('"');
1390    for c in text.chars() {
1391        match c {
1392            '"' => out.push_str("\\\""),
1393            '\\' => out.push_str("\\\\"),
1394            '\n' => out.push_str("\\n"),
1395            '\r' => out.push_str("\\r"),
1396            '\t' => out.push_str("\\t"),
1397            c if (c as u32) < 0x20 => out.push_str(&format!("\\u{:04x}", c as u32)),
1398            c => out.push(c),
1399        }
1400    }
1401    out.push('"');
1402    out
1403}
1404
1405/// O que volta de uma ação executada pela plataforma.
1406#[derive(Clone, Debug, PartialEq, Eq)]
1407pub struct ActionEvent {
1408    /// `open` (o app abriu pela ação), `button` (um botão da notificação), `click` (o corpo
1409    /// da notificação), `timeout` (passou o tempo sem resposta) ou `trigger` (uma regra do
1410    /// push disparou).
1411    pub kind: String,
1412    /// O caminho do componente (`frmPrincipal.wake1`; o `PushTrigger` no `trigger`).
1413    pub component: String,
1414    /// O id do botão (no `button`).
1415    pub detail: String,
1416    /// Os dados da mensagem (JSON).
1417    pub data: String,
1418}
1419
1420/// Uma linha de evento de ação (`tipo	componente	detalhe	dados`), como o Java manda.
1421pub fn parse_action_line(line: &str) -> Option<ActionEvent> {
1422    let mut f = line.split('\t');
1423    let kind = f.next().filter(|k| !k.is_empty())?.to_string();
1424    let component = f.next()?.to_string();
1425    let detail = f.next().unwrap_or_default().to_string();
1426    let data = f.next().filter(|d| !d.trim().is_empty()).unwrap_or("{}").to_string();
1427    Some(ActionEvent { kind, component, detail, data })
1428}
1429
1430/// As ações do aparelho executadas pela própria plataforma (o Android, com o app fechado e a
1431/// tela bloqueada). A ação vai como JSON (o `spec` que o componente monta: `type` `wake` ou
1432/// `notify`, os textos de modelo, os botões...); os dados, como o objeto JSON da mensagem.
1433pub trait ActionService {
1434    fn execute(&mut self, spec: &str, data: &str) -> Result<(), String>;
1435    /// Para a ação do componente (o toque, a notificação, o app por cima do bloqueio).
1436    fn stop(&mut self, component: &str);
1437    /// Grava as regras do `PushTrigger` (uma lista JSON) para valerem com o app fechado: a
1438    /// mensagem que casa executa a ação ali mesmo, antes de o app abrir.
1439    fn set_push_rules(&mut self, rules: &str);
1440    /// O que aconteceu desde a última consulta (também o que aconteceu com o app fechado).
1441    fn poll(&mut self) -> Vec<ActionEvent>;
1442}
1443
1444/// Um valor da automação OLE (o `VARIANT` do Windows, no que interessa a um app).
1445#[derive(Clone, Debug, PartialEq)]
1446pub enum OleValue {
1447    Null,
1448    Bool(bool),
1449    Int(i64),
1450    Float(f64),
1451    String(String),
1452    /// Data e hora como o OLE guarda: dias desde 30/12/1899, a fração é a hora
1453    /// ([`ole_date`], [`ole_date_parts`]).
1454    Date(f64),
1455    /// Um objeto do programa (`Workbook`, `Range`): o número que o serviço deu, até o
1456    /// [`OleService::release`].
1457    Object(u64),
1458    /// Uma matriz (linhas × colunas), como o `Range.Value` de várias células: vai e volta
1459    /// numa chamada só.
1460    Array(Vec<Vec<OleValue>>),
1461}
1462
1463/// Automação OLE (o `IDispatch`): o app comanda um programa instalado (Excel, Word,
1464/// Outlook...) pelos nomes do próprio programa. Cada chamada atravessa processos e custa
1465/// milissegundos: os componentes mandam matrizes inteiras, nunca uma célula por vez.
1466///
1467/// Só cria o que [`ole_allowed`] permite: um programa qualquer (`WScript.Shell`)
1468/// executaria comandos.
1469pub trait OleService {
1470    /// Cria o objeto do programa pelo ProgID (`Excel.Application`); com `running`, pega o
1471    /// que já está aberto e só cria se não houver.
1472    fn create(&mut self, prog_id: &str, running: bool) -> Result<u64, String>;
1473    /// Lê a propriedade ou chama o método `name` do objeto (como o VBA, os dois de uma vez).
1474    fn invoke(&mut self, object: u64, name: &str, args: Vec<OleValue>) -> Result<OleValue, String>;
1475    /// Grava a propriedade `name` (com os argumentos dela, como `Cells(1, 2)`).
1476    fn put(&mut self, object: u64, name: &str, args: Vec<OleValue>, value: OleValue) -> Result<(), String>;
1477    /// Larga o objeto (o programa fecha quando ninguém mais o segura).
1478    fn release(&mut self, object: u64);
1479    /// Quanto esperar o programa em cada chamada (um diálogo aberto nele o prende).
1480    fn set_timeout(&mut self, seconds: f64) {
1481        let _ = seconds;
1482    }
1483    /// Quem larga um objeto sem o `Ui` à mão (o componente liberado, no `Drop`).
1484    fn releaser(&self) -> Option<OleReleaser> {
1485        None
1486    }
1487}
1488
1489/// Larga um objeto da automação de qualquer lugar ([`OleService::releaser`]).
1490pub type OleReleaser = std::sync::Arc<dyn Fn(u64) + Send + Sync>;
1491
1492/// Os programas que a automação pode criar. Os do Office vêm permitidos; outro programa entra
1493/// pelo código do app ([`allow_ole`]), nunca por propriedade ou protocolo: quem manda
1494/// na tela de fora (um backend remoto) não escolhe o que roda nesta máquina.
1495static OLE_ALLOWED: std::sync::RwLock<Vec<String>> = std::sync::RwLock::new(Vec::new());
1496
1497/// Os ProgIDs permitidos sem pedir.
1498pub const OLE_DEFAULT: &[&str] = &["Excel.Application", "Word.Application", "Outlook.Application", "PowerPoint.Application"];
1499
1500/// Permite criar `prog_id` (`AutoCAD.Application`, `SldWorks.Application`).
1501pub fn allow_ole(prog_id: &str) {
1502    if let Ok(mut list) = OLE_ALLOWED.write() {
1503        if !list.iter().any(|p| p.eq_ignore_ascii_case(prog_id)) {
1504            list.push(prog_id.to_string());
1505        }
1506    }
1507}
1508
1509/// Se `prog_id` pode ser criado (sem diferenciar maiúsculas; a versão no fim, como
1510/// `Excel.Application.16`, conta como o mesmo programa).
1511pub fn ole_allowed(prog_id: &str) -> bool {
1512    let id = prog_id.trim();
1513    let base = match id.rsplit_once('.') {
1514        Some((head, tail)) if !tail.is_empty() && tail.chars().all(|c| c.is_ascii_digit()) => head,
1515        _ => id,
1516    };
1517    let ok = |p: &str| p.eq_ignore_ascii_case(base) || p.eq_ignore_ascii_case(id);
1518    OLE_DEFAULT.iter().any(|p| ok(p)) || OLE_ALLOWED.read().is_ok_and(|l| l.iter().any(|p| ok(p)))
1519}
1520
1521/// A data do OLE (dias desde 30/12/1899) de ano, mês, dia, hora, minuto e segundo.
1522pub fn ole_date(year: i32, month: u32, day: u32, hour: u32, minute: u32, second: u32) -> f64 {
1523    // Dias desde 1/1/1970 (o algoritmo de Howard Hinnant), mais os 25.569 até lá.
1524    let y = i64::from(year) - i64::from(month <= 2);
1525    let era = y.div_euclid(400);
1526    let yoe = y - era * 400;
1527    let m = i64::from(month);
1528    let doy = (153 * (if m > 2 { m - 3 } else { m + 9 }) + 2) / 5 + i64::from(day) - 1;
1529    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
1530    let days = era * 146_097 + doe - 719_468 + 25_569;
1531    days as f64 + f64::from(hour * 3600 + minute * 60 + second) / 86_400.0
1532}
1533
1534/// Ano, mês, dia, hora, minuto e segundo de uma data do OLE.
1535pub fn ole_date_parts(date: f64) -> (i32, u32, u32, u32, u32, u32) {
1536    let mut days = date.floor() as i64;
1537    let mut secs = ((date - date.floor()) * 86_400.0).round() as i64;
1538    if secs >= 86_400 {
1539        days += 1;
1540        secs -= 86_400;
1541    }
1542    let z = days - 25_569 + 719_468;
1543    let era = z.div_euclid(146_097);
1544    let doe = z - era * 146_097;
1545    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
1546    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
1547    let mp = (5 * doy + 2) / 153;
1548    let day = (doy - (153 * mp + 2) / 5 + 1) as u32;
1549    let month = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
1550    let year = (yoe + era * 400 + i64::from(month <= 2)) as i32;
1551    (year, month, day, (secs / 3600) as u32, (secs % 3600 / 60) as u32, (secs % 60) as u32)
1552}
1553
1554/// Um valor do WMI: uma propriedade de um objeto, já no tipo do CIM.
1555#[derive(Clone, Debug, PartialEq)]
1556pub enum WmiValue {
1557    Null,
1558    Bool(bool),
1559    Int(i64),
1560    Float(f64),
1561    String(String),
1562    /// Data e hora local em ISO (`2026-11-12T08:30:00`), do `CIM_DATETIME` ([`wmi_datetime`]).
1563    DateTime(String),
1564    /// Uma lista (`CIM_FLAG_ARRAY`: os IPs de uma placa de rede).
1565    Array(Vec<WmiValue>),
1566    /// Um objeto embutido (o `TargetInstance` de um evento): nome e valor de cada propriedade.
1567    Object(Vec<(String, WmiValue)>),
1568}
1569
1570/// O tipo de uma coluna do resultado (o `CIMTYPE` da propriedade).
1571#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
1572pub enum WmiType {
1573    #[default]
1574    String,
1575    Integer,
1576    Float,
1577    Boolean,
1578    DateTime,
1579    Array,
1580    Object,
1581}
1582
1583/// Uma coluna do resultado: o nome da propriedade e o tipo dela.
1584#[derive(Clone, Debug, Default, PartialEq, Eq)]
1585pub struct WmiColumn {
1586    pub name: String,
1587    pub kind: WmiType,
1588}
1589
1590/// O resultado de uma consulta: as colunas (as propriedades, na ordem do `SELECT` quando ele
1591/// lista os nomes) e um valor por coluna em cada linha.
1592#[derive(Clone, Debug, Default, PartialEq)]
1593pub struct WmiTable {
1594    pub columns: Vec<WmiColumn>,
1595    pub rows: Vec<Vec<WmiValue>>,
1596}
1597
1598/// O fim de uma consulta (chamado na thread do WMI; o componente leva à tela pelo
1599/// [`Poster`](crate::Poster)).
1600pub type WmiDone = Box<dyn FnOnce(Result<WmiTable, String>) + Send>;
1601
1602/// Quem recebe os eventos de uma assinatura: as propriedades do evento (com o
1603/// `TargetInstance` como objeto) ou o erro que a encerrou.
1604pub type WmiListener = std::sync::Arc<dyn Fn(Result<Vec<(String, WmiValue)>, String>) + Send + Sync>;
1605
1606/// Uma assinatura de eventos do WMI: para quando é largada.
1607pub struct WmiWatch(Option<Box<dyn FnOnce() + Send>>);
1608
1609impl WmiWatch {
1610    /// `stop` para a assinatura (a plataforma diz como).
1611    pub fn new(stop: impl FnOnce() + Send + 'static) -> Self {
1612        Self(Some(Box::new(stop)))
1613    }
1614}
1615
1616impl Drop for WmiWatch {
1617    fn drop(&mut self) {
1618        if let Some(stop) = self.0.take() {
1619            stop();
1620        }
1621    }
1622}
1623
1624/// O WMI do Windows pela API nativa (`IWbemLocator`/`IWbemServices`; o componente
1625/// `WmiQuery`). Só consulta (WQL), sempre nesta máquina: nada de métodos (`Win32_Process.Create`
1626/// executaria programas) nem de outro computador ([`wmi_namespace`]). Tudo em segundo plano:
1627/// a consulta responde pelo `done`, e os eventos, pelo `listener`.
1628pub trait WmiService {
1629    /// Roda a consulta (`SELECT * FROM Win32_LogicalDisk`) no namespace (`root\cimv2`).
1630    fn query(&mut self, namespace: &str, wql: &str, done: WmiDone);
1631    /// Assina uma consulta de eventos (`SELECT * FROM __InstanceCreationEvent WITHIN 2 WHERE
1632    /// TargetInstance ISA 'Win32_Process'`): cada evento chega no `listener` até a assinatura
1633    /// ser largada.
1634    fn watch(&mut self, namespace: &str, wql: &str, listener: WmiListener) -> Result<WmiWatch, String>;
1635}
1636
1637/// O namespace conferido e normalizado (`root/cimv2` → `root\cimv2`): começa por `root` e só
1638/// tem letras, números e `_`. Um computador (`\\servidor\root\cimv2`) é recusado: a tela não
1639/// abre conexão com outra máquina.
1640pub fn wmi_namespace(namespace: &str) -> Result<String, String> {
1641    let ns = namespace.trim().replace('/', "\\");
1642    let ns = if ns.is_empty() { "root\\cimv2".to_string() } else { ns };
1643    let valid = ns.split('\\').all(|p| !p.is_empty() && p.chars().all(|c| c.is_alphanumeric() || c == '_'));
1644    if !valid || !ns.split('\\').next().is_some_and(|r| r.eq_ignore_ascii_case("root")) {
1645        return Err(crate::messages::tf("namespace do WMI inválido '{0}' (só desta máquina, como root\\cimv2)", &[&namespace]));
1646    }
1647    Ok(ns)
1648}
1649
1650/// A data do CIM (`20261112083000.000000-180`: hora local e o fuso em minutos) em ISO
1651/// (`2026-11-12T08:30:00`). Um intervalo (`00000001132312.000000:000`) ou um texto que não
1652/// é data dá `None`.
1653pub fn wmi_datetime(text: &str) -> Option<String> {
1654    let t = text.trim();
1655    let b = t.as_bytes();
1656    if b.len() < 14 || !b[..14].iter().all(u8::is_ascii_digit) || b.get(21) == Some(&b':') {
1657        return None;
1658    }
1659    let (y, mo, d, h, mi, s) = (&t[0..4], &t[4..6], &t[6..8], &t[8..10], &t[10..12], &t[12..14]);
1660    let month: u32 = mo.parse().ok()?;
1661    let day: u32 = d.parse().ok()?;
1662    if !(1..=12).contains(&month) || !(1..=31).contains(&day) {
1663        return None;
1664    }
1665    Some(format!("{y}-{mo}-{d}T{h}:{mi}:{s}"))
1666}
1667
1668/// Os nomes das propriedades de um `SELECT a, b FROM ...`, na ordem (vazio com `*`): o
1669/// resultado do WMI vem em ordem alfabética, e as colunas seguem o que a consulta pediu.
1670pub fn wmi_select_list(wql: &str) -> Vec<String> {
1671    let t = wql.trim();
1672    let lower = t.to_ascii_lowercase();
1673    let (Some(rest), Some(from)) = (lower.strip_prefix("select"), lower.find(" from ")) else { return Vec::new() };
1674    let start = t.len() - rest.len();
1675    if from < start {
1676        return Vec::new();
1677    }
1678    t[start..from].split(',').map(str::trim).filter(|n| !n.is_empty() && *n != "*").map(str::to_string).collect()
1679}
1680
1681
1682/// Fuso horário: a plataforma liga uma função que devolve, para um instante UTC (segundos
1683/// desde 1970), quantos segundos o horário local está à frente (com horário de verão). Sem
1684/// ela (testes, servidor), o horário local é o UTC.
1685static LOCAL_OFFSET: std::sync::RwLock<Option<fn(i64) -> i64>> = std::sync::RwLock::new(None);
1686
1687pub fn set_local_offset_fn(f: fn(i64) -> i64) {
1688    if let Ok(mut slot) = LOCAL_OFFSET.write() {
1689        *slot = Some(f);
1690    }
1691}
1692
1693/// O fuso fixado pelo projeto (`time_zone` no `.aylisproj`): vale no lugar do fuso do
1694/// aparelho, para todos verem a hora da empresa.
1695static PROJECT_OFFSET: std::sync::RwLock<Option<fn(i64) -> i64>> = std::sync::RwLock::new(None);
1696
1697/// O projeto fixa o fuso (veja [`PROJECT_OFFSET`]); `None` volta ao do aparelho.
1698pub fn set_project_offset_fn(f: Option<fn(i64) -> i64>) {
1699    if let Ok(mut slot) = PROJECT_OFFSET.write() {
1700        *slot = f;
1701    }
1702}
1703
1704/// Segundos que o horário local está à frente do UTC no instante `utc`: o fuso do projeto,
1705/// se houver, senão o do aparelho.
1706pub fn local_offset(utc: i64) -> i64 {
1707    let project = PROJECT_OFFSET.read().ok().and_then(|f| *f);
1708    project.or_else(|| LOCAL_OFFSET.read().ok().and_then(|f| *f)).map_or(0, |f| f(utc))
1709}