From 0c11b990908df26aca7f017d330535b9bf21a903 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Tue, 5 May 2009 11:23:54 -0700 Subject: [PATCH] AI 148308: revise aidl support documentation -- now the same in all environments; also added a table of contents and tweaked the markup for the anchor links BUG=1760241 Automated import of CL 148308 --- docs/html/guide/developing/tools/aidl.jd | 62 +++++++++++++----------- 1 file changed, 33 insertions(+), 29 deletions(-) diff --git a/docs/html/guide/developing/tools/aidl.jd b/docs/html/guide/developing/tools/aidl.jd index 96e4fec7cc1a2..f370a804a4017 100644 --- a/docs/html/guide/developing/tools/aidl.jd +++ b/docs/html/guide/developing/tools/aidl.jd @@ -1,6 +1,25 @@ page.title=Designing a Remote Interface Using AIDL @jd:body + +
+ +
+ +

Since each application runs in its own process, and you can write a service that runs in a different process from your Application's UI, sometimes you need to pass objects between processes. On the Android platform, one process can not normally access the memory @@ -10,7 +29,7 @@ the operating system can understand, and "marshall" the object across that bound

The code to do that marshalling is tedious to write, so we provide the AIDL tool to do it for you.

-

AIDL (Android Interface Definition Language) is an AIDL (Android Interface Definition Language) is an IDL language used to generate code that enables two processes on an Android-powered device to talk using interprocess communication (IPC). If you have code @@ -20,12 +39,9 @@ generate code to marshall the parameters.

The AIDL IPC mechanism is interface-based, similar to COM or Corba, but lighter weight. It uses a proxy class to pass values between the client and the implementation.

-

This page includes the following main topics:

- -

Implementing IPC Using AIDL

+ + +

Implementing IPC Using AIDL

Follow these steps to implement an IPC service using AIDL.

  1. Create your .aidl file - This @@ -46,7 +62,8 @@ generate code to marshall the parameters.

    Service.onBind(Intent)} to return an instance of your class that implements your interface.
-

Create an .aidl File

+ +

Create an .aidl File

AIDL is a simple syntax that lets you declare an interface with one or more methods, that can take parameters and return values. These parameters and return values can be of any type, even other AIDL-generated interfaces. However, it @@ -117,7 +134,7 @@ interface IBankAccountService { int getCustomerList(in String branch, out String[] customerList); } -

Implementing the Interface

+

Implementing the Interface

AIDL generates an interface file for you with the same name as your .aidl file. If you are using the Eclipse plugin, AIDL will automatically be run as part of the build process (you don't need to run AIDL first and then build your project). @@ -152,7 +169,7 @@ private final IRemoteService.Stub mBinder = new IRemoteService.Stub(){

  • Only methods are supported; you cannot declare static fields in an AIDL interface.
    • -

    Exposing Your Interface to Clients

    +

    Exposing Your Interface to Clients

    Now that you've got your interface implementation, you need to expose it to clients. This is known as "publishing your service." To publish a service, inherit {@link android.app.Service Service} and implement {@link android.app.Service#onBind @@ -165,8 +182,8 @@ private final IRemoteService.Stub mBinder = new IRemoteService.Stub(){ exposing_a_service} } - -

    Pass by value Parameters using Parcelables

    + +

    Pass by value Parameters using Parcelables

    If you have a class that you would like to send from one process to another through an AIDL interface, you can do that. You must ensure that the code for your class is available @@ -181,25 +198,12 @@ current state of the object and writes it to a parcel. value in a parcel into your object.

  • Add a static field called CREATOR to your class which is an object implementing the {@link android.os.Parcelable.Creator Parcelable.Creator} interface.
    • -
  • Last but not least: -
      -
    • If you are developing with Eclipse/ADT, follow these steps: -
        -
      1. In the Package Explorer view, right-click on the project.
        2. -
      2. Choose Android Tools > Create Aidl preprocess file -for Parcelable classes.
        3. -
      3. This will create a file called "project.aidl" in the root of the project. -The file will be automatically used when compiling an aidl file that uses the -parcelable classes.
        4. -
      -
      • -
    • If you are developing with Ant or are using a custom build process, create an aidl file +
    • Last but not least, create an aidl file that declares your parcelable class (as shown below). If you are using a custom build process, do not add the aidl file to your build. Similar to a header file in C, the aidl file isn't compiled.
      • -
    -
    • - + +

    AIDL will use these methods and fields in the code it generates to marshall and unmarshall your objects.

    Here is an example of how the {@link android.graphics.Rect} class implements the @@ -269,7 +273,7 @@ values for whatever the caller is trying to do. See Security and Permissions for more on how to keep your application secure from malware.

    -

    Calling an IPC Method

    +

    Calling an IPC Method

    Here are the steps a calling class should make to call your remote interface:

    1. Declare a variable of the interface type that your .aidl file defined.