Skip to main content

camera_android/
android.rs

1//! Android JNI layer that invokes Java APIs directly.
2//!
3//! Uses JNI reflection for the Android USB APIs to keep the Java layer small.
4
5use std::os::fd::OwnedFd;
6use std::sync::OnceLock;
7
8use jni::objects::{AutoLocal, GlobalRef, JObject, JString};
9use jni::{AttachGuard, JavaVM};
10
11use crate::error::{CameraError, Result};
12use crate::UsbDeviceInfo as CameraDeviceInfo;
13
14// UVC interface class and subclass constants.
15const INTERFACE_CLASS_VIDEO: u8 = 14; // CC_VIDEO
16const INTERFACE_SUBCLASS_VIDEO_CONTROL: u8 = 1; // SC_VIDEOCONTROL
17const INTERFACE_SUBCLASS_VIDEO_STREAMING: u8 = 2; // SC_VIDEOSTREAMING
18
19/// Android state containing the JavaVM and Android Context.
20static ANDROID_CONTEXT: OnceLock<AndroidContext> = OnceLock::new();
21
22pub(crate) struct AndroidContext {
23    java_vm: JavaVM,
24    context_jobject: GlobalRef,
25}
26
27impl AndroidContext {
28    pub fn vm(&self) -> &JavaVM {
29        &self.java_vm
30    }
31
32    pub fn context(&self) -> GlobalRef {
33        self.context_jobject.clone()
34    }
35}
36
37/// Initializes the Android context.
38pub fn init_android_context(vm: JavaVM, context: GlobalRef) {
39    let android_context = AndroidContext {
40        java_vm: vm,
41        context_jobject: context,
42    };
43
44    if ANDROID_CONTEXT.set(android_context).is_ok() {
45        log::info!("Android context initialized");
46    } else {
47        log::warn!("Android context already initialized; ignoring duplicate init");
48    }
49}
50
51/// Returns the Android context.
52pub(crate) fn get_android_context() -> Result<&'static AndroidContext> {
53    ANDROID_CONTEXT.get().ok_or_else(|| {
54        CameraError::adapter(
55            camera::CameraErrorKind::InvalidState,
56            "Android context not initialized",
57        )
58    })
59}
60
61/// Extracts a string from a Java object.
62fn get_string(env: &mut AttachGuard, object: &JObject, method: &str) -> Result<Option<String>> {
63    let string_ret = match env.call_method(object, method, "()Ljava/lang/String;", &[]) {
64        Ok(ret) => ret,
65        Err(e) => {
66            log::debug!("Error on call get string {method}: {e}");
67            if env.exception_check()? {
68                env.exception_clear()?;
69            }
70            return Err(CameraError::adapter(
71                camera::CameraErrorKind::BackendFailure,
72                format!("JNI call failed: {e}"),
73            ));
74        }
75    };
76
77    let string = string_ret.l()?;
78    let string: AutoLocal<JString> = env.auto_local(string.into());
79
80    if string.is_null() {
81        Ok(None)
82    } else {
83        Ok(Some(env.get_string(&string)?.into()))
84    }
85}
86
87/// Scans for USB camera devices.
88///
89/// Invokes the Android UsbManager API through JNI.
90pub fn usb_manager_scan() -> Result<Vec<CameraDeviceInfo>> {
91    let ctx = get_android_context()?;
92
93    let context = ctx.context();
94    let vm = ctx.vm();
95    let mut env = vm.attach_current_thread()?;
96
97    let class_ctx = env.find_class("android/content/Context")?;
98    let usb_service = &env.get_static_field(class_ctx, "USB_SERVICE", "Ljava/lang/String;")?;
99
100    let usb_manager = env
101        .call_method(
102            context.as_obj(),
103            "getSystemService",
104            "(Ljava/lang/String;)Ljava/lang/Object;",
105            &[usb_service.into()],
106        )?
107        .l()?;
108    let usb_manager = env.auto_local(usb_manager);
109
110    let device_hashmap = env
111        .call_method(&usb_manager, "getDeviceList", "()Ljava/util/HashMap;", &[])?
112        .l()?;
113    let device_hashmap = env.auto_local(device_hashmap);
114
115    let device_values = env
116        .call_method(&device_hashmap, "values", "()Ljava/util/Collection;", &[])?
117        .l()?;
118    let device_values = env.auto_local(device_values);
119
120    let device_values_iterator = env
121        .call_method(&device_values, "iterator", "()Ljava/util/Iterator;", &[])?
122        .l()?;
123    let device_values_iterator = env.auto_local(device_values_iterator);
124
125    let mut result = Vec::new();
126
127    while env
128        .call_method(&device_values_iterator, "hasNext", "()Z", &[])?
129        .z()?
130    {
131        let item = env
132            .call_method(&device_values_iterator, "next", "()Ljava/lang/Object;", &[])?
133            .l()?;
134        let device_next = env.auto_local(item);
135
136        if device_next.is_null() {
137            break;
138        }
139
140        let vid = env
141            .call_method(&device_next, "getVendorId", "()I", &[])?
142            .i()? as u16;
143
144        let pid = env
145            .call_method(&device_next, "getProductId", "()I", &[])?
146            .i()? as u16;
147
148        // Check whether this is a UVC device.
149        if !scan_uvc_interface(&mut env, &device_next)? {
150            continue;
151        }
152
153        // Read device details.
154        // getProductName may return null.
155        let product_name = get_string(&mut env, &device_next, "getProductName")?;
156
157        // getManufacturerName may return null and requires Android 5.0 or newer.
158        let manufacturer = get_string(&mut env, &device_next, "getManufacturerName")?;
159
160        // getSerialNumber may return null and requires USB permission.
161        let serial_number = get_string(&mut env, &device_next, "getSerialNumber")
162            .ok()
163            .flatten();
164
165        // getDeviceName returns a path such as /dev/bus/usb/001/002.
166        let device_path = get_string(&mut env, &device_next, "getDeviceName")?.unwrap_or_default();
167
168        // getVersion is available on Android 13 and newer.
169        let usb_version = get_string(&mut env, &device_next, "getVersion")
170            .ok()
171            .flatten();
172
173        // Prefer the product name, then manufacturer plus VID:PID.
174        let display_name = if let Some(ref name) = product_name {
175            if !name.is_empty() {
176                name.clone()
177            } else if let Some(ref mfr) = manufacturer {
178                format!("{} Camera", mfr)
179            } else {
180                format!("USB Camera {:04X}:{:04X}", vid, pid)
181            }
182        } else if let Some(ref mfr) = manufacturer {
183            format!("{} Camera", mfr)
184        } else {
185            format!("USB Camera {:04X}:{:04X}", vid, pid)
186        };
187
188        log::debug!(
189            "Found UVC device: {} (VID:{:04X} PID:{:04X}, Manufacturer: {:?}, Serial: {:?}, USB: {:?})",
190            display_name, vid, pid, manufacturer, serial_number, usb_version
191        );
192
193        result.push(CameraDeviceInfo {
194            index: result.len() as u32,
195            name: display_name.clone(),
196            description: format!("USB Camera VID:{:04X} PID:{:04X}", vid, pid),
197            vendor_id: Some(vid),
198            product_id: Some(pid),
199            serial_number,
200            device_path: Some(device_path),
201        });
202    }
203
204    log::info!("Found {} UVC cameras", result.len());
205    Ok(result)
206}
207
208/// Scans device interfaces to identify a UVC camera.
209fn scan_uvc_interface(env: &mut AttachGuard, device: &JObject) -> Result<bool> {
210    let interface_count = env
211        .call_method(device, "getInterfaceCount", "()I", &[])?
212        .i()?;
213
214    for i in 0..interface_count {
215        let interface = env
216            .call_method(
217                device,
218                "getInterface",
219                "(I)Landroid/hardware/usb/UsbInterface;",
220                &[i.into()],
221            )?
222            .l()?;
223        let interface = env.auto_local(interface);
224
225        let interface_class = env
226            .call_method(&interface, "getInterfaceClass", "()I", &[])?
227            .i()? as u8;
228
229        if interface_class != INTERFACE_CLASS_VIDEO {
230            continue;
231        }
232
233        let interface_sub_class = env
234            .call_method(&interface, "getInterfaceSubclass", "()I", &[])?
235            .i()? as u8;
236
237        if interface_sub_class == INTERFACE_SUBCLASS_VIDEO_CONTROL
238            || interface_sub_class == INTERFACE_SUBCLASS_VIDEO_STREAMING
239        {
240            return Ok(true);
241        }
242    }
243
244    Ok(false)
245}
246
247/// Checks whether USB permission has already been granted.
248pub fn usb_device_has_permission(device_path: &str) -> Result<bool> {
249    let ctx = get_android_context()?;
250
251    let context = ctx.context();
252    let vm = ctx.vm();
253    let mut env = vm.attach_current_thread()?;
254
255    let class_ctx = env.find_class("android/content/Context")?;
256    let usb_service = &env.get_static_field(class_ctx, "USB_SERVICE", "Ljava/lang/String;")?;
257
258    let usb_manager = env
259        .call_method(
260            context.as_obj(),
261            "getSystemService",
262            "(Ljava/lang/String;)Ljava/lang/Object;",
263            &[usb_service.into()],
264        )?
265        .l()?;
266    let usb_manager = env.auto_local(usb_manager);
267
268    let device_hashmap = env
269        .call_method(&usb_manager, "getDeviceList", "()Ljava/util/HashMap;", &[])?
270        .l()?;
271    let device_hashmap = env.auto_local(device_hashmap);
272
273    let device_name: JObject = env.new_string(device_path)?.into();
274    let device_name = env.auto_local(device_name);
275
276    let device = env
277        .call_method(
278            &device_hashmap,
279            "get",
280            "(Ljava/lang/Object;)Ljava/lang/Object;",
281            &[(&device_name).into()],
282        )?
283        .l()?;
284    let device = env.auto_local(device);
285
286    if device.is_null() {
287        return Err(
288            camera::CameraError::device_not_found(device_path.to_string())
289                .with_backend(camera::BackendId::UVC)
290                .with_stage(camera::OperationStage::Enumeration)
291                .into(),
292        );
293    }
294
295    let has_permission = env
296        .call_method(
297            &usb_manager,
298            "hasPermission",
299            "(Landroid/hardware/usb/UsbDevice;)Z",
300            &[(&device).into()],
301        )?
302        .z()?;
303
304    Ok(has_permission)
305}
306
307/// Requests permission for a USB device.
308pub fn usb_device_request_permission(device_path: &str) -> Result<()> {
309    let ctx = get_android_context()?;
310
311    let context = ctx.context();
312    let vm = ctx.vm();
313    let mut env = vm.attach_current_thread()?;
314
315    let class_ctx = env.find_class("android/content/Context")?;
316    let usb_service = &env.get_static_field(class_ctx, "USB_SERVICE", "Ljava/lang/String;")?;
317
318    let usb_manager = env
319        .call_method(
320            context.as_obj(),
321            "getSystemService",
322            "(Ljava/lang/String;)Ljava/lang/Object;",
323            &[usb_service.into()],
324        )?
325        .l()?;
326    let usb_manager = env.auto_local(usb_manager);
327
328    let device_hashmap = env
329        .call_method(&usb_manager, "getDeviceList", "()Ljava/util/HashMap;", &[])?
330        .l()?;
331    let device_hashmap = env.auto_local(device_hashmap);
332
333    let device_name: JObject = env.new_string(device_path)?.into();
334    let device_name = env.auto_local(device_name);
335
336    let device = env
337        .call_method(
338            &device_hashmap,
339            "get",
340            "(Ljava/lang/Object;)Ljava/lang/Object;",
341            &[(&device_name).into()],
342        )?
343        .l()?;
344    let device = env.auto_local(device);
345
346    if device.is_null() {
347        return Err(
348            camera::CameraError::device_not_found(device_path.to_string())
349                .with_backend(camera::BackendId::UVC)
350                .with_stage(camera::OperationStage::Enumeration)
351                .into(),
352        );
353    }
354
355    // Create the PendingIntent.
356    let permission = "com.medivh.camera.USB_PERMISSION";
357    let permission_str: JObject = env.new_string(permission)?.into();
358    let permission_str = env.auto_local(permission_str);
359
360    let class_intent = env.find_class("android/content/Intent")?;
361    let intent = env.new_object(
362        &class_intent,
363        "(Ljava/lang/String;)V",
364        &[(&permission_str).into()],
365    )?;
366
367    // Android 12 and newer require the Intent package for broadcast delivery.
368    let package_name = env
369        .call_method(
370            context.as_obj(),
371            "getPackageName",
372            "()Ljava/lang/String;",
373            &[],
374        )?
375        .l()?;
376    env.call_method(
377        &intent,
378        "setPackage",
379        "(Ljava/lang/String;)Landroid/content/Intent;",
380        &[(&package_name).into()],
381    )?;
382    let intent = env.auto_local(intent);
383
384    let class_pending_intent = env.find_class("android/app/PendingIntent")?;
385
386    // Android 12 and newer require FLAG_MUTABLE or FLAG_IMMUTABLE.
387    // FLAG_MUTABLE = 0x02000000
388    let flags = 0x02000000i32; // FLAG_MUTABLE
389
390    let permission_intent = env
391        .call_static_method(
392            &class_pending_intent,
393            "getBroadcast",
394            "(Landroid/content/Context;ILandroid/content/Intent;I)Landroid/app/PendingIntent;",
395            &[
396                ctx.context().as_obj().into(),
397                0.into(),
398                (&intent).into(),
399                flags.into(),
400            ],
401        )?
402        .l()?;
403    let permission_intent = env.auto_local(permission_intent);
404
405    env.call_method(
406        &usb_manager,
407        "requestPermission",
408        "(Landroid/hardware/usb/UsbDevice;Landroid/app/PendingIntent;)V",
409        &[(&device).into(), (&permission_intent).into()],
410    )?;
411
412    log::info!("USB permission requested for device: {}", device_path);
413    Ok(())
414}
415
416/// Opens a USB device and returns its file descriptor.
417///
418/// This is the primary Android entry point for opening a UVC camera.
419/// Returns an owned duplicate of the USB fd. The caller must close it.
420/// The temporary Java UsbDeviceConnection is closed before returning.
421pub fn usb_device_open(device_path: &str) -> Result<OwnedFd> {
422    let ctx = get_android_context()?;
423
424    let context = ctx.context();
425    let vm = ctx.vm();
426    let mut env = vm.attach_current_thread()?;
427
428    let class_ctx = env.find_class("android/content/Context")?;
429    let usb_service = &env.get_static_field(class_ctx, "USB_SERVICE", "Ljava/lang/String;")?;
430
431    let usb_manager = env
432        .call_method(
433            context.as_obj(),
434            "getSystemService",
435            "(Ljava/lang/String;)Ljava/lang/Object;",
436            &[usb_service.into()],
437        )?
438        .l()?;
439    let usb_manager = env.auto_local(usb_manager);
440
441    let device_hashmap = env
442        .call_method(&usb_manager, "getDeviceList", "()Ljava/util/HashMap;", &[])?
443        .l()?;
444    let device_hashmap = env.auto_local(device_hashmap);
445
446    let device_name: JObject = env.new_string(device_path)?.into();
447    let device_name = env.auto_local(device_name);
448
449    let device = env
450        .call_method(
451            &device_hashmap,
452            "get",
453            "(Ljava/lang/Object;)Ljava/lang/Object;",
454            &[(&device_name).into()],
455        )?
456        .l()?;
457    let device = env.auto_local(device);
458
459    if device.is_null() {
460        return Err(
461            camera::CameraError::device_not_found(device_path.to_string())
462                .with_backend(camera::BackendId::UVC)
463                .with_stage(camera::OperationStage::Open)
464                .into(),
465        );
466    }
467
468    // Check USB permission.
469    let has_permission = env
470        .call_method(
471            &usb_manager,
472            "hasPermission",
473            "(Landroid/hardware/usb/UsbDevice;)Z",
474            &[(&device).into()],
475        )?
476        .z()?;
477
478    if !has_permission {
479        log::warn!("No permission for USB device: {}", device_path);
480        // Request permission.
481        usb_device_request_permission_internal(&mut env, &usb_manager, &device, ctx)?;
482        return Err(
483            camera::CameraError::permission_denied(device_path.to_string())
484                .with_backend(camera::BackendId::UVC)
485                .with_stage(camera::OperationStage::Open)
486                .into(),
487        );
488    }
489
490    // Open the device.
491    let usb_connection = env
492        .call_method(
493            &usb_manager,
494            "openDevice",
495            "(Landroid/hardware/usb/UsbDevice;)Landroid/hardware/usb/UsbDeviceConnection;",
496            &[(&device).into()],
497        )?
498        .l()?;
499    let usb_connection = env.auto_local(usb_connection);
500
501    if usb_connection.is_null() {
502        return Err(
503            camera::CameraError::device_open_failed("Failed to open USB device".into())
504                .with_backend(camera::BackendId::UVC)
505                .with_stage(camera::OperationStage::Open)
506                .into(),
507        );
508    }
509
510    // Duplicate while Java still owns the original descriptor. Always close
511    // the temporary connection, including descriptor/duplication failures.
512    let owned = env
513        .call_method(&usb_connection, "getFileDescriptor", "()I", &[])
514        .and_then(|v| v.i())
515        .map_err(CameraError::from)
516        .and_then(crate::owned_fd::duplicate);
517    let closed = env.call_method(&usb_connection, "close", "()V", &[]);
518    let owned = owned?;
519    closed?;
520    Ok(owned)
521}
522
523/// Internal permission request helper.
524fn usb_device_request_permission_internal<'a>(
525    env: &mut AttachGuard<'a>,
526    usb_manager: &JObject<'a>,
527    device: &JObject<'a>,
528    ctx: &AndroidContext,
529) -> Result<()> {
530    let permission = "com.medivh.camera.USB_PERMISSION";
531    let permission_str: JObject = env.new_string(permission)?.into();
532    let permission_str = env.auto_local(permission_str);
533
534    let class_intent = env.find_class("android/content/Intent")?;
535    let intent = env.new_object(
536        &class_intent,
537        "(Ljava/lang/String;)V",
538        &[(&permission_str).into()],
539    )?;
540
541    // Android 12 and newer require the Intent package for broadcast delivery.
542    let package_name = env
543        .call_method(
544            ctx.context().as_obj(),
545            "getPackageName",
546            "()Ljava/lang/String;",
547            &[],
548        )?
549        .l()?;
550    env.call_method(
551        &intent,
552        "setPackage",
553        "(Ljava/lang/String;)Landroid/content/Intent;",
554        &[(&package_name).into()],
555    )?;
556    let intent = env.auto_local(intent);
557
558    let class_pending_intent = env.find_class("android/app/PendingIntent")?;
559    let flags = 0x02000000i32;
560
561    let permission_intent = env
562        .call_static_method(
563            &class_pending_intent,
564            "getBroadcast",
565            "(Landroid/content/Context;ILandroid/content/Intent;I)Landroid/app/PendingIntent;",
566            &[
567                ctx.context().as_obj().into(),
568                0.into(),
569                (&intent).into(),
570                flags.into(),
571            ],
572        )?
573        .l()?;
574    let permission_intent = env.auto_local(permission_intent);
575
576    env.call_method(
577        usb_manager,
578        "requestPermission",
579        "(Landroid/hardware/usb/UsbDevice;Landroid/app/PendingIntent;)V",
580        &[device.into(), (&permission_intent).into()],
581    )?;
582
583    Ok(())
584}
585
586/// Opens a device by VID and PID.
587pub fn usb_device_open_by_vid_pid(vid: u16, pid: u16) -> Result<OwnedFd> {
588    let devices = usb_manager_scan()?;
589
590    for device in devices {
591        if device.vendor_id == Some(vid) && device.product_id == Some(pid) {
592            if let Some(path) = &device.device_path {
593                return usb_device_open(path);
594            }
595        }
596    }
597
598    Err(
599        camera::CameraError::device_not_found(format!("VID:{vid:04x} PID:{pid:04x}"))
600            .with_backend(camera::BackendId::UVC)
601            .with_stage(camera::OperationStage::Open)
602            .into(),
603    )
604}
605
606/// Opens a device by index.
607pub fn usb_device_open_by_index(index: u32) -> Result<OwnedFd> {
608    let devices = usb_manager_scan()?;
609
610    if let Some(device) = devices.get(index as usize) {
611        if let Some(path) = &device.device_path {
612            return usb_device_open(path);
613        }
614    }
615
616    Err(
617        camera::CameraError::device_not_found(format!("Device index {index}"))
618            .with_backend(camera::BackendId::UVC)
619            .with_stage(camera::OperationStage::Open)
620            .into(),
621    )
622}
623
624#[cfg(test)]
625mod tests {
626    use super::*;
627
628    #[test]
629    fn get_android_context_returns_error_before_init() {
630        let result = get_android_context();
631
632        assert!(matches!(
633            result,
634            Err(error) if error.kind() == camera::CameraErrorKind::InvalidState
635                && error.to_string().contains("not initialized")
636        ));
637    }
638}