Bound Services

    Quickview

    • A bound service allows other components to bind to it, in order to interact with it and perform interprocess communication
    • A bound service is destroyed once all clients unbind, unless the service was also started

    In this document

    1. The Basics
    2. Creating a Bound Service
      1. Extending the Binder class
    3. Binding to a Service
    4. Managing the Lifecycle of a Bound Service

    Key classes

    1. Service
    2. ServiceConnection
    3. IBinder

    See also

    1. Services

A bound service is the server in a client-server interface. A bound service allows components (such as activities) to bind to the service, send requests, receive responses, and even perform interprocess communication (IPC). A bound service typically lives only while it serves another application component and does not run in the background indefinitely.

This document shows you how to create a bound service, including how to bind to the service from other application components. However, you should also refer to the Services document for additional information about services in general, such as how to deliver notifications from a service, set the service to run in the foreground, and more.

The Basics

A bound service is an implementation of the Service class that allows other applications to bind to it and interact with it. To provide binding for a service, you must implement the onBind() callback method. This method returns an IBinder object that defines the programming interface that clients can use to interact with the service.

A client can bind to the service by calling bindService(). When it does, it must provide an implementation of ServiceConnection, which monitors the connection with the service. The bindService() method returns immediately without a value, but when the Android system creates the connection between the client and service, it calls onServiceConnected() on the ServiceConnection, to deliver the IBinder that the client can use to communicate with the service.

When the last client unbinds from the service, the system destroys the service (unless the service was also started by startService()).

When you implement your bound service, the most important part is defining the interface that your onBind() callback method returns. There are a few different ways you can define your service's IBinder interface and the following section discusses each technique.

Binding to a Service

Application components (clients) can bind to a service by calling bindService(). The Android system then calls the service's onBind() method, which returns an IBinder for interacting with the service.

The binding is asynchronous. bindService() returns immediately and does not return the IBinder to the client. To receive the IBinder, the client must create an instance of ServiceConnection and pass it to bindService(). The ServiceConnection includes a callback method that the system calls to deliver the IBinder.

So, to bind to a service from your client, you must:

  1. Implement ServiceConnection.

    Your implementation must override two callback methods:

    onServiceConnected()
    The system calls this to deliver the IBinder returned by the service's onBind() method.
    onServiceDisconnected()
    The Mindroid system calls this when the connection to the service is unexpectedly lost, such as when the service has crashed or has been killed. This is not called when the client unbinds.
  2. Call bindService(), passing the ServiceConnection implementation.
  3. When the system calls your onServiceConnected() callback method, you can begin making calls to the service, using the methods defined by the interface.
  4. To disconnect from the service, call unbindService().

    When your client is destroyed, it will unbind from the service, but you should always unbind when you're done interacting with the service or when your service pauses so that the previously bound service can shutdown while its not being used. (Appropriate times to bind and unbind is discussed more below.)

For example, the following snippet connects the client to the service created above by extending the Binder class.

ITestManager mService;
private ServiceConnection mConnection = new ServiceConnection() {
    // Called when the connection with the service is established
    public void onServiceConnected(ComponentName className, IBinder service) {
        // Because we have bound to an explicit
        // service that is running in our own process, we can
        // cast its IBinder to a concrete class and directly access it.
        mService = ITestManager.Stub.asInterface(service);
        mBound = true;
    }

    // Called when the connection with the service disconnects unexpectedly
    public void onServiceDisconnected(ComponentName className) {
        Log.e(TAG, "onServiceDisconnected");
        mBound = false;
    }
};

Managing the Lifecycle of a Bound Service

When a service is unbound from all clients, the Mindroid system destroys it (unless it was also started with onStartCommand()). As such, you don't have to manage the lifecycle of your service if it's purely a bound service—the Mindroid system manages it for you based on whether it is bound to any clients.

However, if you choose to implement the onStartCommand() callback method, then you must explicitly stop the service, because the service is now considered to be started. In this case, the service runs until the service stops itself with stopSelf() or another component calls stopService(), regardless of whether it is bound to any clients.

Figure 1. The lifecycle for a service that is started and also allows binding.

For more information about the lifecycle of a started service, see the Services document.