1 /* 2 * Copyright (C) 2006 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.os; 18 19 /** 20 * Reference to a Handler, which others can use to send messages to it. 21 * This allows for the implementation of message-based communication across 22 * processes, by creating a Messenger pointing to a Handler in one process, 23 * and handing that Messenger to another process. 24 * 25 * <p>Note: the implementation underneath is just a simple wrapper around 26 * a {@link Binder} that is used to perform the communication. This means 27 * semantically you should treat it as such: this class does not impact process 28 * lifecycle management (you must be using some higher-level component to tell 29 * the system that your process needs to continue running), the connection will 30 * break if your process goes away for any reason, etc.</p> 31 */ 32 public final class Messenger implements Parcelable { 33 private final IMessenger mTarget; 34 35 /** 36 * Create a new Messenger pointing to the given Handler. Any Message 37 * objects sent through this Messenger will appear in the Handler as if 38 * {@link Handler#sendMessage(Message) Handler.sendMessage(Message)} had 39 * been called directly. 40 * 41 * @param target The Handler that will receive sent messages. 42 */ Messenger(Handler target)43 public Messenger(Handler target) { 44 mTarget = target.getIMessenger(); 45 } 46 47 /** 48 * Send a Message to this Messenger's Handler. 49 * 50 * @param message The Message to send. Usually retrieved through 51 * {@link Message#obtain() Message.obtain()}. 52 * 53 * @throws RemoteException Throws DeadObjectException if the target 54 * Handler no longer exists. 55 */ send(Message message)56 public void send(Message message) throws RemoteException { 57 mTarget.send(message); 58 } 59 60 /** 61 * Retrieve the IBinder that this Messenger is using to communicate with 62 * its associated Handler. 63 * 64 * @return Returns the IBinder backing this Messenger. 65 */ getBinder()66 public IBinder getBinder() { 67 return mTarget.asBinder(); 68 } 69 70 /** 71 * Comparison operator on two Messenger objects, such that true 72 * is returned then they both point to the same Handler. 73 */ equals(Object otherObj)74 public boolean equals(Object otherObj) { 75 if (otherObj == null) { 76 return false; 77 } 78 try { 79 return mTarget.asBinder().equals(((Messenger)otherObj) 80 .mTarget.asBinder()); 81 } catch (ClassCastException e) { 82 } 83 return false; 84 } 85 hashCode()86 public int hashCode() { 87 return mTarget.asBinder().hashCode(); 88 } 89 describeContents()90 public int describeContents() { 91 return 0; 92 } 93 writeToParcel(Parcel out, int flags)94 public void writeToParcel(Parcel out, int flags) { 95 out.writeStrongBinder(mTarget.asBinder()); 96 } 97 98 public static final Parcelable.Creator<Messenger> CREATOR 99 = new Parcelable.Creator<Messenger>() { 100 public Messenger createFromParcel(Parcel in) { 101 IBinder target = in.readStrongBinder(); 102 return target != null ? new Messenger(target) : null; 103 } 104 105 public Messenger[] newArray(int size) { 106 return new Messenger[size]; 107 } 108 }; 109 110 /** 111 * Convenience function for writing either a Messenger or null pointer to 112 * a Parcel. You must use this with {@link #readMessengerOrNullFromParcel} 113 * for later reading it. 114 * 115 * @param messenger The Messenger to write, or null. 116 * @param out Where to write the Messenger. 117 */ writeMessengerOrNullToParcel(Messenger messenger, Parcel out)118 public static void writeMessengerOrNullToParcel(Messenger messenger, 119 Parcel out) { 120 out.writeStrongBinder(messenger != null ? messenger.mTarget.asBinder() 121 : null); 122 } 123 124 /** 125 * Convenience function for reading either a Messenger or null pointer from 126 * a Parcel. You must have previously written the Messenger with 127 * {@link #writeMessengerOrNullToParcel}. 128 * 129 * @param in The Parcel containing the written Messenger. 130 * 131 * @return Returns the Messenger read from the Parcel, or null if null had 132 * been written. 133 */ readMessengerOrNullFromParcel(Parcel in)134 public static Messenger readMessengerOrNullFromParcel(Parcel in) { 135 IBinder b = in.readStrongBinder(); 136 return b != null ? new Messenger(b) : null; 137 } 138 139 /** 140 * Create a Messenger from a raw IBinder, which had previously been 141 * retrieved with {@link #getBinder}. 142 * 143 * @param target The IBinder this Messenger should communicate with. 144 */ Messenger(IBinder target)145 public Messenger(IBinder target) { 146 mTarget = IMessenger.Stub.asInterface(target); 147 } 148 } 149