Messenger.java revision ab4a81b3c625e33d04ae8070fcce6b6baee6522c
1246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan/* 2246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * Copyright (C) 2006 The Android Open Source Project 3246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * 4246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * Licensed under the Apache License, Version 2.0 (the "License"); 5246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * you may not use this file except in compliance with the License. 6246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * You may obtain a copy of the License at 7246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * 8246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * http://www.apache.org/licenses/LICENSE-2.0 9246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * 10246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * Unless required by applicable law or agreed to in writing, software 11246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * distributed under the License is distributed on an "AS IS" BASIS, 12246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * See the License for the specific language governing permissions and 14246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * limitations under the License. 15246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan */ 16246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan 17246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajanpackage android.os; 18246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan 193b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe/** 2013b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * Reference to a Handler, which others can use to send messages to it. 21246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * This allows for the implementation of message-based communication across 2213b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * processes, by creating a Messenger pointing to a Handler in one process, 23246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * and handing that Messenger to another process. 24246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * 2513b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * <p>Note: the implementation underneath is just a simple wrapper around 26246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * a {@link Binder} that is used to perform the communication. This means 27246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * semantically you should treat it as such: this class does not impact process 2813b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * lifecycle management (you must be using some higher-level component to tell 2913b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * the system that your process needs to continue running), the connection will 30246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * break if your process goes away for any reason, etc.</p> 3113b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe */ 3213b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawepublic final class Messenger implements Parcelable { 3313b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe private final IMessenger mTarget; 34246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan 3513b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe /** 364e10a61602bd065cdf71d0335493ac3444d5055ayinxu * Create a new Messenger pointing to the given Handler. Any Message 37246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * objects sent through this Messenger will appear in the Handler as if 38246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * {@link Handler#sendMessage(Message) Handler.sendMessage(Message)} had 393b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe * been called directly. 403b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe * 41d8fe3ba2e6fbc96e80609f694cb0031ef40371e4Amit Mahajan * @param target The Handler that will receive sent messages. 423b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe */ 433b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe public Messenger(Handler target) { 4413b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe mTarget = target.getIMessenger(); 45d8fe3ba2e6fbc96e80609f694cb0031ef40371e4Amit Mahajan } 463b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe 473b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe /** 480b23fe5834db6b9f53111487e2911cbc394fe761sqian * Send a Message to this Messenger's Handler. 4913b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * 5021cb4001dec43dc8a3e031eb4a64c721a03bd6eeNathan Harold * @param message The Message to send. Usually retrieved through 513b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe * {@link Message#obtain() Message.obtain()}. 5213b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * 5313b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * @throws RemoteException Throws DeadObjectException if the target 543b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe * Handler no longer exists. 5513b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe */ 5613b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe public void send(Message message) throws RemoteException { 57246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan mTarget.send(message); 5813b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe } 593b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe 60246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan /** 61246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * Retrieve the IBinder that this Messenger is using to communicate with 623b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe * its associated Handler. 633b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe * 643b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe * @return Returns the IBinder backing this Messenger. 653b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe */ 663b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe public IBinder getBinder() { 673b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe return mTarget.asBinder(); 68246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan } 69246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan 70246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan /** 71246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * Comparison operator on two Messenger objects, such that true 72246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * is returned then they both point to the same Handler. 73246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan */ 74246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan public boolean equals(Object otherObj) { 75246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan if (otherObj == null) { 76246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan return false; 77246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan } 78246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan try { 7972c0d812e2e53b35c09ee9bfffe04779636678a3Amit Mahajan return mTarget.asBinder().equals(((Messenger)otherObj) 80246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan .mTarget.asBinder()); 81246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan } catch (ClassCastException e) { 82246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan } 83246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan return false; 84246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan } 85246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan 86246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan public int hashCode() { 876509576d8eb86664d1b5383a1b637e00748e807eJack Yu return mTarget.asBinder().hashCode(); 8813b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe } 8913b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe 9013b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe public int describeContents() { 9113b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe return 0; 9213b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe } 9313b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe 9413b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe public void writeToParcel(Parcel out, int flags) { 9513b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe out.writeStrongBinder(mTarget.asBinder()); 9613b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe } 9713b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe 983b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe public static final Parcelable.Creator<Messenger> CREATOR 99246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan = new Parcelable.Creator<Messenger>() { 100246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan public Messenger createFromParcel(Parcel in) { 101246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan IBinder target = in.readStrongBinder(); 10213b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe return target != null ? new Messenger(target) : null; 103246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan } 104246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan 10513b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe public Messenger[] newArray(int size) { 1063b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe return new Messenger[size]; 1074e10a61602bd065cdf71d0335493ac3444d5055ayinxu } 1084e10a61602bd065cdf71d0335493ac3444d5055ayinxu }; 1094e10a61602bd065cdf71d0335493ac3444d5055ayinxu 1104e10a61602bd065cdf71d0335493ac3444d5055ayinxu /** 1114e10a61602bd065cdf71d0335493ac3444d5055ayinxu * Convenience function for writing either a Messenger or null pointer to 1124e10a61602bd065cdf71d0335493ac3444d5055ayinxu * a Parcel. You must use this with {@link #readMessengerOrNullFromParcel} 1134e10a61602bd065cdf71d0335493ac3444d5055ayinxu * for later reading it. 1144e10a61602bd065cdf71d0335493ac3444d5055ayinxu * 1154e10a61602bd065cdf71d0335493ac3444d5055ayinxu * @param messenger The Messenger to write, or null. 11613b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * @param out Where to write the Messenger. 11713b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe */ 11813b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe public static void writeMessengerOrNullToParcel(Messenger messenger, 11913b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe Parcel out) { 12013b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe out.writeStrongBinder(messenger != null ? messenger.mTarget.asBinder() 121246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan : null); 12213b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe } 1233b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe 12413b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe /** 12513b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * Convenience function for reading either a Messenger or null pointer from 12613b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * a Parcel. You must have previously written the Messenger with 12713b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * {@link #writeMessengerOrNullToParcel}. 12813b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * 129246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan * @param in The Parcel containing the written Messenger. 13013b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * 1313b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe * @return Returns the Messenger read from the Parcel, or null if null had 13213b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * been written. 13313b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe */ 13413b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe public static Messenger readMessengerOrNullFromParcel(Parcel in) { 13513b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe IBinder b = in.readStrongBinder(); 13613b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe return b != null ? new Messenger(b) : null; 137246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan } 13813b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe 1393b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe /** 14013b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * Create a Messenger from a raw IBinder, which had previously been 14113b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * retrieved with {@link #getBinder}. 14213b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * 14313b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe * @param target The IBinder this Messenger should communicate with. 14413b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe */ 145246295a9ce6d2ae2613ff95b3e85ea1c0406d164Amit Mahajan public Messenger(IBinder target) { 14613b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe mTarget = IMessenger.Stub.asInterface(target); 1473b51aec7f0eca9a2b7af7fdf605ae7bf9d9c5f4aSanket Padawe } 14813b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe} 14913b2867e7d74a0234735502c4f922a281c8b0438Sanket Padawe