floss: Add rustdoc for dbus_projection crate (3a8d94ec) · Commits · e / os / android_packages_modules_Bluetooth

system/gd/rust/linux/dbus_projection/dbus_macros/src/lib.rs

+8 −0

Original line number	Diff line number	Diff line
		@@ -31,6 +31,14 @@ pub fn dbus_method(_attr: TokenStream, item: TokenStream) -> TokenStream {
		}

		/// Generates a function to export a Rust object to D-Bus.
		///
		/// Example:
		/// ```
		/// #[generate_dbus_exporter(export_foo_dbus_obj, "org.example.FooInterface")]
		/// ```
		///
		/// This generates a method called `export_foo_dbus_obj` that will export a Rust object into a
		/// D-Bus object having interface `org.example.FooInterface`.
		#[proc_macro_attribute]
		pub fn generate_dbus_exporter(attr: TokenStream, item: TokenStream) -> TokenStream {
		let ori_item: proc_macro2::TokenStream = item.clone().into();

system/gd/rust/linux/dbus_projection/src/lib.rs

+47 −1

Original line number	Diff line number	Diff line
		//! This crate provides tools to automatically project generic API to D-Bus RPC.
		//!
		//! For D-Bus projection to work automatically, the API needs to follow certain restrictions.
		//! For D-Bus projection to work automatically, the API needs to follow certain restrictions:
		//!
		//! * API does not use D-Bus specific features: Signals, Properties, ObjectManager.
		//! * Interfaces (contain Methods) are hosted on statically allocated D-Bus objects.
		//! * When the service needs to notify the client about changes, callback objects are used. The
		//! client can pass a callback object obeying a specified Interface by passing the D-Bus object
		//! path.
		//!
		//! A good example is in
		//! [`manager_service`](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt)
		//! crate:
		//!
		//! * Define RPCProxy like in
		//! [here](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt/src/lib.rs)
		//! (TODO: We should remove this requirement in the future).
		//! * Generate `DBusArg` trait like in
		//! [here](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt/src/bin/btmanagerd/dbus_arg.rs).
		//! This trait is generated by a macro and cannot simply be imported because of Rust's
		//! [Orphan Rule](https://github.com/Ixrec/rust-orphan-rules).
		//! * Define D-Bus-agnostic traits like in
		//! [here](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt/src/iface_bluetooth_manager.rs).
		//! These traits can be projected into D-Bus Interfaces on D-Bus objects. A method parameter can
		//! be of a Rust primitive type, structure, enum, or a callback specially typed as
		//! `Box<dyn SomeCallbackTrait + Send>`. Callback traits implement `RPCProxy`.
		//! * Implement the traits like in
		//! [here](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt/src/bin/btmanagerd/bluetooth_manager.rs),
		//! also D-Bus-agnostic.
		//! * Define D-Bus projection mappings like in
		//! [here](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt/src/bin/btmanagerd/bluetooth_manager_dbus.rs).
		//! * Add [`generate_dbus_exporter`](dbus_macros::generate_dbus_exporter) macro to an `impl` of a
		//! trait.
		//! * Define a method name of each method with [`dbus_method`](dbus_macros::dbus_method) macro.
		//! * Similarly, for callbacks use [`dbus_proxy_obj`](dbus_macros::dbus_proxy_obj) macro to define
		//! the method mappings.
		//! * Rust primitive types can be converted automatically to and from D-Bus types.
		//! * Rust structures require implementations of `DBusArg` for the conversion. This is made easy
		//! with the [`dbus_propmap`](dbus_macros::dbus_propmap) macro.
		//! * Rust enums require implementations of `DBusArg` for the conversion. This is made easy with
		//! the [`impl_dbus_arg_enum`](impl_dbus_arg_enum) macro.
		//! * To project a Rust object to a D-Bus, call the function generated by
		//! [`generate_dbus_exporter`](dbus_macros::generate_dbus_exporter) like in
		//! [here](https://android.googlesource.com/platform/packages/modules/Bluetooth/system/+/refs/heads/master/gd/rust/linux/mgmt/src/bin/btmanagerd/main.rs)
		//! passing in the object path, D-Bus connection, Crossroads object, the Rust object to be
		//! projected, and a [`DisconnectWatcher`](DisconnectWatcher) object.

		use dbus::channel::MatchingReceiver;
		use dbus::message::MatchRule;
		@@ -73,6 +116,9 @@ impl DisconnectWatcher {
		}
		}

		/// Implements `DBusArg` for an enum.
		///
		/// A Rust enum is converted to D-Bus INT32 type.
		#[macro_export]
		macro_rules! impl_dbus_arg_enum {
		($enum_type:ty) => {