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 @android.annotation.NonNull 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