Binder/AIDL content updates (google#1618)

Author: randomPoison

src/SUMMARY.md

@@ -212,12 +212,21 @@
   - [Binary](android/build-rules/binary.md)
   - [Library](android/build-rules/library.md)
 - [AIDL](android/aidl.md)
-  - [Interface](android/aidl/interface.md)
-  - [Implementation](android/aidl/implementation.md)
-  - [Server](android/aidl/server.md)
-  - [Deploy](android/aidl/deploy.md)
-  - [Client](android/aidl/client.md)
-  - [Changing API](android/aidl/changing.md)
+  - [Birthday Service Tutorial](android/aidl/birthday-service.md)
+    - [Interface](android/aidl/example-service/interface.md)
+    - [Service API](android/aidl/example-service/service-bindings.md)
+    - [Service](android/aidl/example-service/service.md)
+    - [Server](android/aidl/example-service/server.md)
+    - [Deploy](android/aidl/example-service/deploy.md)
+    - [Client](android/aidl/example-service/client.md)
+    - [Changing API](android/aidl/example-service/changing-definition.md)
+    - [Updating Implementations](android/aidl/example-service/changing-implementation.md)
+  - [AIDL Types](android/aidl/types.md)
+    - [Primitive Types](android/aidl/types/primitives.md)
+    - [Array Types](android/aidl/types/arrays.md)
+    - [Sending Objects](android/aidl/types/objects.md)
+    - [Parcelables](android/aidl/types/parcelables.md)
+    - [Sending Files](android/aidl/types/file-descriptor.md)
 - [Logging](android/logging.md)
 - [Interoperability](android/interoperability.md)
   - [With C](android/interoperability/with-c.md)

src/android/aidl/birthday-service.md

@@ -0,0 +1,5 @@
+# Birthday Service Tutorial
+
+To illustrate how to use Rust with Binder, we're going to walk through the
+process of creating a Binder interface. We're then going to both implement the
+described service and write client code that talks to that service.

src/android/aidl/birthday_service/aidl/com/example/birthdayservice/BirthdayInfo.aidl

@@ -0,0 +1,6 @@
+package com.example.birthdayservice;
+
+parcelable BirthdayInfo {
+    String name;
+    int years;
+}

src/android/aidl/birthday_service/aidl/com/example/birthdayservice/IBirthdayInfoProvider.aidl

@@ -0,0 +1,21 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// ANCHOR: IBirthdayInfoProvider
+package com.example.birthdayservice;
+
+interface IBirthdayInfoProvider {
+    String name();
+    int years();
+}

src/android/aidl/birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl

@@ -12,11 +12,33 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// ANCHOR: IBirthdayService
 package com.example.birthdayservice;
 
+import com.example.birthdayservice.IBirthdayInfoProvider;
+import com.example.birthdayservice.BirthdayInfo;
+
+// ANCHOR: IBirthdayService
 /** Birthday service interface. */
 interface IBirthdayService {
     /** Generate a Happy Birthday message. */
     String wishHappyBirthday(String name, int years);
+    // ANCHOR_END: IBirthdayService
+
+    // ANCHOR: with_info
+    /** The same thing, but with a parcelable. */
+    String wishWithInfo(in BirthdayInfo info);
+    // ANCHOR_END: with_info
+
+    // ANCHOR: with_info_provider
+    /** The same thing, but using a binder object. */
+    String wishWithProvider(IBirthdayInfoProvider provider);
+
+    /** The same thing, but using `IBinder`. */
+    String wishWithErasedProvider(IBinder provider);
+    // ANCHOR_END: with_info_provider
+
+    // ANCHOR: with_file
+    /** The same thing, but loads info from a file. */
+    String wishFromFile(in ParcelFileDescriptor infoFile);
+    // ANCHOR_END: with_file
 }

src/android/aidl/birthday_service/src/client.rs

@@ -12,30 +12,87 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// ANCHOR: main
 //! Birthday service.
+use com_example_birthdayservice::aidl::com::example::birthdayservice::BirthdayInfo::BirthdayInfo;
+use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayInfoProvider::{
+    BnBirthdayInfoProvider, IBirthdayInfoProvider,
+};
 use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
-use com_example_birthdayservice::binder;
+use com_example_birthdayservice::binder::{self, BinderFeatures, ParcelFileDescriptor};
+use std::error::Error;
+use std::fs::File;
+use std::io::prelude::*;
 
+// ANCHOR: main
 const SERVICE_IDENTIFIER: &str = "birthdayservice";
 
-/// Connect to the BirthdayService.
-pub fn connect() -> Result<binder::Strong<dyn IBirthdayService>, binder::StatusCode>
-{
-    binder::get_interface(SERVICE_IDENTIFIER)
-}
-
 /// Call the birthday service.
-fn main() -> Result<(), binder::Status> {
+fn main() -> Result<(), Box<dyn Error>> {
     let name = std::env::args().nth(1).unwrap_or_else(|| String::from("Bob"));
     let years = std::env::args()
         .nth(2)
         .and_then(|arg| arg.parse::<i32>().ok())
         .unwrap_or(42);
 
     binder::ProcessState::start_thread_pool();
-    let service = connect().expect("Failed to connect to BirthdayService");
+    let service = binder::get_interface::<dyn IBirthdayService>(SERVICE_IDENTIFIER)
+        .map_err(|_| "Failed to connect to BirthdayService")?;
+
+    // Call the service.
     let msg = service.wishHappyBirthday(&name, years)?;
     println!("{msg}");
+    // ANCHOR_END: main
+
+    // ANCHOR: wish_with_info
+    service.wishWithInfo(&BirthdayInfo { name: name.clone(), years })?;
+    // ANCHOR_END: wish_with_info
+
+    // ANCHOR: wish_with_provider
+
+    // Create a binder object for the `IBirthdayInfoProvider` interface.
+    let provider = BnBirthdayInfoProvider::new_binder(
+        InfoProvider { name: name.clone(), age: years as u8 },
+        BinderFeatures::default(),
+    );
+
+    // Send the binder object to the service.
+    service.wishWithProvider(&provider)?;
+
+    // Perform the same operation but passing the provider as an `SpIBinder`.
+    service.wishWithErasedProvider(&provider.as_binder())?;
+    // ANCHOR_END: wish_with_provider
+
+    // ANCHOR: wish_with_file
+
+    // Open a file and put the birthday info in it.
+    let mut file = File::create("/data/local/tmp/birthday.info").unwrap();
+    writeln!(file, "{name}")?;
+    writeln!(file, "{years}")?;
+
+    // Create a `ParcelFileDescriptor` from the file and send it.
+    let file = ParcelFileDescriptor::new(file);
+    service.wishFromFile(&file)?;
+    // ANCHOR_END: wish_with_file
+
     Ok(())
 }
+
+// ANCHOR: InfoProvider
+/// Rust struct implementing the `IBirthdayInfoProvider` interface.
+struct InfoProvider {
+    name: String,
+    age: u8,
+}
+
+impl binder::Interface for InfoProvider {}
+
+impl IBirthdayInfoProvider for InfoProvider {
+    fn name(&self) -> binder::Result<String> {
+        Ok(self.name.clone())
+    }
+
+    fn years(&self) -> binder::Result<i32> {
+        Ok(self.age as i32)
+    }
+}
+// ANCHOR_END: InfoProvider

src/android/aidl/birthday_service/src/lib.rs

@@ -12,11 +12,15 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// ANCHOR: IBirthdayService
 //! Implementation of the `IBirthdayService` AIDL interface.
+use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayInfoProvider::IBirthdayInfoProvider;
 use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
-use com_example_birthdayservice::binder;
+use com_example_birthdayservice::aidl::com::example::birthdayservice::BirthdayInfo::BirthdayInfo;
+use com_example_birthdayservice::binder::{self, ParcelFileDescriptor, SpIBinder, Strong};
+use std::fs::File;
+use std::io::Read;
 
+// ANCHOR: IBirthdayService
 /// The `IBirthdayService` implementation.
 pub struct BirthdayService;
 
@@ -26,4 +30,63 @@ impl IBirthdayService for BirthdayService {
     fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String> {
         Ok(format!("Happy Birthday {name}, congratulations with the {years} years!"))
     }
+    // ANCHOR_END: IBirthdayService
+
+    fn wishWithInfo(&self, info: &BirthdayInfo) -> binder::Result<String> {
+        Ok(format!(
+            "Happy Birthday {}, congratulations with the {} years!",
+            info.name, info.years,
+        ))
+    }
+
+    fn wishWithProvider(
+        &self,
+        provider: &Strong<dyn IBirthdayInfoProvider>,
+    ) -> binder::Result<String> {
+        Ok(format!(
+            "Happy Birthday {}, congratulations with the {} years!",
+            provider.name()?,
+            provider.years()?,
+        ))
+    }
+
+    fn wishWithErasedProvider(
+        &self,
+        provider: &SpIBinder,
+    ) -> binder::Result<String> {
+        // Convert the `SpIBinder` to a concrete interface.
+        let provider =
+            provider.clone().into_interface::<dyn IBirthdayInfoProvider>()?;
+
+        Ok(format!(
+            "Happy Birthday {}, congratulations with the {} years!",
+            provider.name()?,
+            provider.years()?,
+        ))
+    }
+
+    // ANCHOR: wishFromFile
+    fn wishFromFile(
+        &self,
+        info_file: &ParcelFileDescriptor,
+    ) -> binder::Result<String> {
+        // Convert the file descriptor to a `File`. `ParcelFileDescriptor` wraps
+        // an `OwnedFd`, which can be cloned and then used to create a `File`
+        // object.
+        let mut info_file = info_file
+            .as_ref()
+            .try_clone()
+            .map(File::from)
+            .expect("Invalid file handle");
+
+        let mut contents = String::new();
+        info_file.read_to_string(&mut contents).unwrap();
+
+        let mut lines = contents.lines();
+        let name = lines.next().unwrap();
+        let years: i32 = lines.next().unwrap().parse().unwrap();
+
+        Ok(format!("Happy Birthday {name}, congratulations with the {years} years!"))
+    }
+    // ANCHOR_END: wishFromFile
 }

src/android/aidl/changing.md

@@ -0,0 +1,38 @@
+# Changing API
+
+Let us extend the API with more functionality: we want to let clients specify a
+list of lines for the birthday card:
+
+```java
+package com.example.birthdayservice;
+
+/** Birthday service interface. */
+interface IBirthdayService {
+    /** Generate a Happy Birthday message. */
+    String wishHappyBirthday(String name, int years, in String[] text);
+}
+```
+
+This results in an updated trait definition for `IBirthdayService`:
+
+```rust,ignore
+trait IBirthdayService {
+    fn wishHappyBirthday(
+        &self,
+        name: &str,
+        years: i32,
+        text: &[String],
+    ) -> binder::Result<String>;
+}
+```
+
+<details>
+
+- Note how the `String[]` in the AIDL definition is translated as a `&[String]`
+  in Rust, i.e. that idiomatic Rust types are used in the generated bindings
+  wherever possible:
+  - `in` array arguments are translated to slices.
+  - `out` and `inout` args are translated to `&mut Vec<T>`.
+  - Return values are translated to returning a `Vec<T>`.
+
+</details>