guide/components/bound-services.jd

page.title=
parent.title=
parent.link=services.html
@jd:body


<div id="qv-wrapper">
<ol id="qv">
<h2> </h2>
<ol>
  <li><a href="#Basics"></a></li>
  <li><a href="#Creating">  </a>
    <ol>
      <li><a href="#Binder">  Binder</a></li>
      <li><a href="#Messenger">  Messenger</a></li>
    </ol>
  </li>
  <li><a href="#Binding">  </a></li>
  <li><a href="#Lifecycle">    </a></li>
</ol>

<h2> </h2>
<ol>
  <li>{@link android.app.Service}</li>
  <li>{@link android.content.ServiceConnection}</li>
  <li>{@link android.os.IBinder}</li>
</ol>

<h2></h2>
<ol>
  <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">{@code
      RemoteService}</a></li>
  <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code
      LocalService}</a></li>
</ol>

<h2>. :</h2>
<ol>
  <li><a href="{@docRoot}guide/components/services.html"></a></li>
</ol>
</div>


<p>     -.
(, )   ,  ,
IPC.    ,
  .       .</p>

<p>   ,    ,
    .      <a href="{@docRoot}guide/components/services.html"></a>,
 , ,      ,
      ..</p>


<h2 id="Basics"></h2>

<p>      {@link android.app.Service},
        .
,       {@link android.app.Service#onBind onBind()}.
   {@link android.os.IBinder}.    ,
       .</p>

<div class="sidebox-wrapper">
<div class="sidebox">
  <h3>   </h3>

<p>    <a href="{@docRoot}guide/components/services.html"></a>,
  ,    ,  .  ,
   {@link android.content.Context#startService startService()},
  ,            {@link
android.content.Context#bindService bindService()}.
  <p>     ,
 <em></em>       .
   ,   {@link android.app.Service#stopSelf stopSelf()}  {@link
android.content.Context#stopService stopService()}.</p>

<p>  ,       {@link android.app.Service#onBind onBind()},
<em> </em> {@link android.app.Service#onStartCommand onStartCommand()},
   . ,
 ,     .  ,
,         .
        ,    .</p>

<p>   ,  <a href="#Lifecycle">
</a>.         ,
 .</p>
</div>
</div>

<p>        {@link android.content.Context#bindService
bindService()}.        {@link
android.content.ServiceConnection},       .  {@link
android.content.Context#bindService bindService()}    ,
,   Android
-,    {@link
android.content.ServiceConnection#onServiceConnected onServiceConnected()}  {@link
android.content.ServiceConnection},    {@link android.os.IBinder},
      .</p>

<p>       .
{@link android.app.Service#onBind onBind()}      {@link android.os.IBinder}
    .        {@link android.os.IBinder}
 ,   ,     {@link android.app.Service#onBind onBind()}.</p>

<p>      ,    (
       {@link android.content.Context#startService startService()}).</p>

<p>         ,
      {@link android.app.Service#onBind onBind()}.
    {@link android.os.IBinder} .
.</p>


<h2 id="Creating">  </h2>

<p>  ,  ,   {@link android.os.IBinder},
   ,        .
    :</p>

<dl>
  <dt><a href="#Binder">  Binder</a></dt>
  <dd>          ,       ,
( ),       {@link android.os.Binder}

{@link android.app.Service#onBind onBind()}.    {@link android.os.Binder},
            ,     {@link android.os.Binder},
   {@link android.app.Service}.
  <p>   ,
 .         ,
         .</dd>

  <dt><a href="#Messenger">  Messenger</a></dt>
  <dd> ,        ,
   {@link android.os.Messenger}.  ,
  {@link android.os.Handler},     {@link
android.os.Message}.   {@link android.os.Handler}
    {@link android.os.Messenger}, ,   ,    {@link android.os.IBinder},
           {@link
android.os.Message}.  ,     {@link android.os.Messenger}
,      .
  <p>      ,  {@link
android.os.Messenger}        ,
  .</p>
  </dd>

  <dt>  AIDL</dt>
  <dd>AIDL (Android Interface Definition Language)
,
   (IPC).      {@link android.os.Messenger}    AIDL,
 .    ,  {@link android.os.Messenger}
     ,       . ,
 ,       ,   AIDL
.            .
  <p>  AIDL ,
  {@code .aidl},    .     SDK Android
  ,       ,
     .</p>
  </dd>
</dl>

  <p class="note"><strong>.</strong>    <strong> </strong>  AIDL
   ,       , ,   ,
   .  AIDL     ,
             .     ,
   AIDL ,
<a href="{@docRoot}guide/components/aidl.html">AIDL</a>.</p>


<h3 id="Binder">  Binder</h3>

<p>            ,
    {@link android.os.Binder},
     .</p>

<p class="note"><strong>.</strong>       ,
   ,     . ,
 ,         ,
    .</p>

<p>   :</p>
<ol>
  <li>      {@link android.os.Binder}   :
    <ul>
      <li>   ,    ; </li>
      <li>     {@link android.app.Service},
 ,    ; </li>
      <li>    ,   ,   ,
   .</li>
    </ul>
  <li>    {@link android.os.Binder}     {@link
android.app.Service#onBind onBind()}.</li>
  <li>    {@link android.os.Binder}     {@link
android.content.ServiceConnection#onServiceConnected onServiceConnected()}
        .</li>
</ol>

<p class="note"><strong>.</strong>
,               API-.  ,
          ,      -
  .</p>

<p>   ,
{@link android.os.Binder}:</p>

<pre>
public class LocalService extends Service {
    // Binder given to clients
    private final IBinder mBinder = new LocalBinder();
    // Random number generator
    private final Random mGenerator = new Random();

    /**
     * Class used for the client Binder.  Because we know this service always
     * runs in the same process as its clients, we don't need to deal with IPC.
     */
    public class LocalBinder extends Binder {
        LocalService getService() {
            // Return this instance of LocalService so clients can call public methods
            return LocalService.this;
        }
    }

    &#64;Override
    public IBinder onBind(Intent intent) {
        return mBinder;
    }

    /** method for clients */
    public int getRandomNumber() {
      return mGenerator.nextInt(100);
    }
}
</pre>

<p> {@code LocalBinder}     {@code getService()},
   {@code LocalService}.
. ,     {@code getRandomNumber()}  .</p>

<p>   ,      {@code LocalService}    {@code getRandomNumber()}
  :</p>

<pre>
public class BindingActivity extends Activity {
    LocalService mService;
    boolean mBound = false;

    &#64;Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
    }

    &#64;Override
    protected void onStart() {
        super.onStart();
        // Bind to LocalService
        Intent intent = new Intent(this, LocalService.class);
        bindService(intent, mConnection, Context.BIND_AUTO_CREATE);
    }

    &#64;Override
    protected void onStop() {
        super.onStop();
        // Unbind from the service
        if (mBound) {
            unbindService(mConnection);
            mBound = false;
        }
    }

    /** Called when a button is clicked (the button in the layout file attaches to
      * this method with the android:onClick attribute) */
    public void onButtonClick(View v) {
        if (mBound) {
            // Call a method from the LocalService.
            // However, if this call were something that might hang, then this request should
            // occur in a separate thread to avoid slowing down the activity performance.
            int num = mService.getRandomNumber();
            Toast.makeText(this, "number: " + num, Toast.LENGTH_SHORT).show();
        }
    }

    /** Defines callbacks for service binding, passed to bindService() */
    private ServiceConnection mConnection = new ServiceConnection() {

        &#64;Override
        public void onServiceConnected(ComponentName className,
                IBinder service) {
            // We've bound to LocalService, cast the IBinder and get LocalService instance
            LocalBinder binder = (LocalBinder) service;
            mService = binder.getService();
            mBound = true;
        }

        &#64;Override
        public void onServiceDisconnected(ComponentName arg0) {
            mBound = false;
        }
    };
}
</pre>

<p>   ,
{@link android.content.ServiceConnection}    {@link
android.content.ServiceConnection#onServiceConnected onServiceConnected()}.
           .</p>

<p class="note"><strong>.</strong>          ,
         (,   ).</p>

<p>    ,   <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code
LocalService.java}</a>  <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalServiceActivities.html">{@code
LocalServiceActivities.java}</a>,  <a href="{@docRoot}resources/samples/ApiDemos/index.html">ApiDemos</a>.</p>


<h3 id="Messenger">  Messenger</h3>

<div class="sidebox-wrapper">
<div class="sidebox">
  <h4>  AIDL</h4>
  <p>     ,   {@link android.os.Messenger}
     AIDL,   {@link android.os.Messenger}
     ,   ,    AIDL,     ,
    .</p>
  <p>       ,     {@link
android.os.Messenger}      .   ,
   ,      <a href="{@docRoot}guide/components/aidl.html">AIDL</a>.</p>
</div>
</div>

<p> ,      ,
{@link android.os.Messenger}.
     (IPC)    AIDL.</p>

<p>   ,     {@link android.os.Messenger}:</p>

<ul>
  <li>   {@link android.os.Handler},
  .</li>
  <li> {@link android.os.Handler}     {@link android.os.Messenger}
(     {@link android.os.Handler}).</li>
  <li> {@link android.os.Messenger}   {@link android.os.IBinder},
    {@link android.app.Service#onBind onBind()}.</li>
  <li>    {@link android.os.IBinder}     {@link android.os.Messenger}
(    {@link android.os.Handler} ),
{@link android.os.Message}  .</li>
  <li>    {@link android.os.Message}    {@link
android.os.Handler}&mdash;  ,   {@link android.os.Handler#handleMessage
handleMessage()}.</li>
</ul>


<p> ,        .
   ( {@link android.os.Message}),
  {@link android.os.Handler}.</p>

<p>   ,    {@link android.os.Messenger}:</p>

<pre>
public class MessengerService extends Service {
    /** Command to the service to display a message */
    static final int MSG_SAY_HELLO = 1;

    /**
     * Handler of incoming messages from clients.
     */
    class IncomingHandler extends Handler {
        &#64;Override
        public void handleMessage(Message msg) {
            switch (msg.what) {
                case MSG_SAY_HELLO:
                    Toast.makeText(getApplicationContext(), "hello!", Toast.LENGTH_SHORT).show();
                    break;
                default:
                    super.handleMessage(msg);
            }
        }
    }

    /**
     * Target we publish for clients to send messages to IncomingHandler.
     */
    final Messenger mMessenger = new Messenger(new IncomingHandler());

    /**
     * When binding to the service, we return an interface to our messenger
     * for sending messages to the service.
     */
    &#64;Override
    public IBinder onBind(Intent intent) {
        Toast.makeText(getApplicationContext(), "binding", Toast.LENGTH_SHORT).show();
        return mMessenger.getBinder();
    }
}
</pre>

<p> ,   {@link android.os.Handler#handleMessage handleMessage()}
{@link android.os.Handler}  ,      {@link android.os.Message}
 ,   ,   {@link android.os.Message#what}.</p>

<p>     {@link android.os.Messenger}    {@link
android.os.IBinder},  ,       {@link
android.os.Messenger#send send()}.    ,
     {@code MSG_SAY_HELLO}:</p>

<pre>
public class ActivityMessenger extends Activity {
    /** Messenger for communicating with the service. */
    Messenger mService = null;

    /** Flag indicating whether we have called bind on the service. */
    boolean mBound;

    /**
     * Class for interacting with the main interface of the service.
     */
    private ServiceConnection mConnection = new ServiceConnection() {
        public void onServiceConnected(ComponentName className, IBinder service) {
            // This is called when the connection with the service has been
            // established, giving us the object we can use to
            // interact with the service.  We are communicating with the
            // service using a Messenger, so here we get a client-side
            // representation of that from the raw IBinder object.
            mService = new Messenger(service);
            mBound = true;
        }

        public void onServiceDisconnected(ComponentName className) {
            // This is called when the connection with the service has been
            // unexpectedly disconnected -- that is, its process crashed.
            mService = null;
            mBound = false;
        }
    };

    public void sayHello(View v) {
        if (!mBound) return;
        // Create and send a message to the service, using a supported 'what' value
        Message msg = Message.obtain(null, MessengerService.MSG_SAY_HELLO, 0, 0);
        try {
            mService.send(msg);
        } catch (RemoteException e) {
            e.printStackTrace();
        }
    }

    &#64;Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
    }

    &#64;Override
    protected void onStart() {
        super.onStart();
        // Bind to the service
        bindService(new Intent(this, MessengerService.class), mConnection,
            Context.BIND_AUTO_CREATE);
    }

    &#64;Override
    protected void onStop() {
        super.onStop();
        // Unbind from the service
        if (mBound) {
            unbindService(mConnection);
            mBound = false;
        }
    }
}
</pre>

<p> ,      ,    .  ,
  ,    {@link android.os.Messenger}   . ,
     {@link android.content.ServiceConnection#onServiceConnected
onServiceConnected()},      {@link android.os.Message},
{@link android.os.Messenger}      {@link android.os.Message#replyTo}
 {@link android.os.Messenger#send send()}.</p>

<p>         <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/MessengerService.html">{@code
MessengerService.java}</a> ()  <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/MessengerServiceActivities.html">{@code
MessengerServiceActivities.java}</a> ().</p>


<h2 id="Binding">  </h2>

<p>      ()
{@link android.content.Context#bindService bindService()}.    Android
  {@link android.app.Service#onBind
onBind()} ,    {@link android.os.IBinder}    .</p>

<p>  . {@link android.content.Context#bindService
bindService()}     <em></em>
{@link android.os.IBinder}.    {@link android.os.IBinder}     {@link
android.content.ServiceConnection}      {@link android.content.Context#bindService
bindService()}.  {@link android.content.ServiceConnection}    ,
    ,    {@link android.os.IBinder}.</p>

<p class="note"><strong>.</strong>       ,
&mdash;  <strong> </strong>       .</p>

<p>           . </p>
<ol>
  <li>  {@link android.content.ServiceConnection}.
    <p>       :</p>
    <dl>
      <dt>{@link android.content.ServiceConnection#onServiceConnected onServiceConnected()}</dt>
        <dd>   ,    {@link android.os.IBinder},
{@link android.app.Service#onBind onBind()}.</dd>
      <dt>{@link android.content.ServiceConnection#onServiceDisconnected
onServiceDisconnected()}</dt>
        <dd> Android
  ,           .   <em></em> ,
 .</dd>
    </dl>
  </li>
  <li>  {@link
android.content.Context#bindService bindService()},      {@link
android.content.ServiceConnection}. </li>
  <li>       {@link android.content.ServiceConnection#onServiceConnected
onServiceConnected()},
,  .</li>
  <li>   ,   {@link
android.content.Context#unbindService unbindService()}.
    <p>         ,
          ,
   ,    . (
    ).</p>
  </li>
</ol>

<p>
<a href="#Binder">  Binder</a>
{@link android.os.IBinder}   {@code LocalService}    {@code
LocalService}:</p>

<pre>
LocalService 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.
        LocalBinder binder = (LocalBinder) service;
        mService = binder.getService();
        mBound = true;
    }

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

<p>    {@link android.content.ServiceConnection}      ,
 {@link android.content.Context#bindService bindService()}. :</p>

<pre>
Intent intent = new Intent(this, LocalService.class);
bindService(intent, mConnection, Context.BIND_AUTO_CREATE);
</pre>

<ul>
  <li>    {@link android.content.Context#bindService bindService()}
{@link android.content.Intent},        (
 ).</li>
<li>    {@link android.content.ServiceConnection}.</li>
<li>    ,   .    {@link
android.content.Context#BIND_AUTO_CREATE},  ,     .
  : {@link android.content.Context#BIND_DEBUG_UNBIND}
 {@link android.content.Context#BIND_NOT_FOREGROUND}  {@code 0},   .</li>
</ul>


<h3> </h3>

<p>        .</p>
<ul>
  <li>   {@link android.os.DeadObjectException},
   .   ,    .</li>
  <li>        . </li>
  <li>
        . :
    <ul>
      <li>        ,   ,
     {@link android.app.Activity#onStart onStart()},        {@link
android.app.Activity#onStop onStop()}.</li>
      <li> ,               ,
      {@link android.app.Activity#onCreate onCreate()},
     {@link android.app.Activity#onDestroy onDestroy()}.   ,    ,
       ,    (      ). ,
     ,     ,
  ,    .</li>
    </ul>
    <p class="note"><strong>.</strong>  <strong></strong>
    {@link android.app.Activity#onResume onResume()}  {@link
android.app.Activity#onPause onPause()}  ,             ,
   ,    ,   .  ,
      ,
  ,       ,
(  )  ,      (  ). (

<a href="{@docRoot}guide/components/activities.html#CoordinatingActivities"></a>.)</p>
</ul>

<p> ,       , .  ,   <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">{@code
RemoteService.java}</a>,  <a href="{@docRoot}resources/samples/ApiDemos/index.html">ApiDemos</a>.</p>


<h2 id="Lifecycle">    </h2>

<p>       ,  Android    (
  {@link android.app.Service#onStartCommand onStartCommand()}).
    ,
&mdash;  Android            .</p>

<p>,        {@link android.app.Service#onStartCommand
onStartCommand()},      ,
    <em></em>.        ,
        {@link android.app.Service#stopSelf()}    ,       {@link
android.content.Context#stopService stopService()},      -
.</p>

<p> ,       ,
  {@link android.app.Service#onUnbind onUnbind()}
{@code true},      {@link android.app.Service#onRebind
onRebind()}      (     {@link
android.app.Service#onBind onBind()}).  {@link android.app.Service#onRebind
onRebind()}   void,   -   {@link android.os.IBinder}
{@link android.content.ServiceConnection#onServiceConnected onServiceConnected()}.
 1       .</p>


<img src="{@docRoot}images/fundamentals/service_binding_tree_lifecycle.png" alt="" />
<p class="img-caption"><strong>1.</strong>    ,
   .</p>


<p>           <a href="{@docRoot}guide/components/services.html#Lifecycle"></a>.</p>