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