• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 public final class Messenger implements Parcelable {
26     private final IMessenger mTarget;
27 
28     /**
29      * Create a new Messenger pointing to the given Handler.  Any Message
30      * objects sent through this Messenger will appear in the Handler as if
31      * {@link Handler#sendMessage(Message) Handler.sendMessage(Message)} had
32      * been called directly.
33      *
34      * @param target The Handler that will receive sent messages.
35      */
Messenger(Handler target)36     public Messenger(Handler target) {
37         mTarget = target.getIMessenger();
38     }
39 
40     /**
41      * Send a Message to this Messenger's Handler.
42      *
43      * @param message The Message to send.  Usually retrieved through
44      * {@link Message#obtain() Message.obtain()}.
45      *
46      * @throws RemoteException Throws DeadObjectException if the target
47      * Handler no longer exists.
48      */
send(Message message)49     public void send(Message message) throws RemoteException {
50         mTarget.send(message);
51     }
52 
53     /**
54      * Retrieve the IBinder that this Messenger is using to communicate with
55      * its associated Handler.
56      *
57      * @return Returns the IBinder backing this Messenger.
58      */
getBinder()59     public IBinder getBinder() {
60         return mTarget.asBinder();
61     }
62 
63     /**
64      * Comparison operator on two Messenger objects, such that true
65      * is returned then they both point to the same Handler.
66      */
equals(Object otherObj)67     public boolean equals(Object otherObj) {
68         if (otherObj == null) {
69             return false;
70         }
71         try {
72             return mTarget.asBinder().equals(((Messenger)otherObj)
73                     .mTarget.asBinder());
74         } catch (ClassCastException e) {
75         }
76         return false;
77     }
78 
hashCode()79     public int hashCode() {
80         return mTarget.asBinder().hashCode();
81     }
82 
describeContents()83     public int describeContents() {
84         return 0;
85     }
86 
writeToParcel(Parcel out, int flags)87     public void writeToParcel(Parcel out, int flags) {
88         out.writeStrongBinder(mTarget.asBinder());
89     }
90 
91     public static final Parcelable.Creator<Messenger> CREATOR
92             = new Parcelable.Creator<Messenger>() {
93         public Messenger createFromParcel(Parcel in) {
94             IBinder target = in.readStrongBinder();
95             return target != null ? new Messenger(target) : null;
96         }
97 
98         public Messenger[] newArray(int size) {
99             return new Messenger[size];
100         }
101     };
102 
103     /**
104      * Convenience function for writing either a Messenger or null pointer to
105      * a Parcel.  You must use this with {@link #readMessengerOrNullFromParcel}
106      * for later reading it.
107      *
108      * @param messenger The Messenger to write, or null.
109      * @param out Where to write the Messenger.
110      */
writeMessengerOrNullToParcel(Messenger messenger, Parcel out)111     public static void writeMessengerOrNullToParcel(Messenger messenger,
112             Parcel out) {
113         out.writeStrongBinder(messenger != null ? messenger.mTarget.asBinder()
114                 : null);
115     }
116 
117     /**
118      * Convenience function for reading either a Messenger or null pointer from
119      * a Parcel.  You must have previously written the Messenger with
120      * {@link #writeMessengerOrNullToParcel}.
121      *
122      * @param in The Parcel containing the written Messenger.
123      *
124      * @return Returns the Messenger read from the Parcel, or null if null had
125      * been written.
126      */
readMessengerOrNullFromParcel(Parcel in)127     public static Messenger readMessengerOrNullFromParcel(Parcel in) {
128         IBinder b = in.readStrongBinder();
129         return b != null ? new Messenger(b) : null;
130     }
131 
132     /**
133      * Create a Messenger from a raw IBinder, which had previously been
134      * retrieved with {@link #getBinder}.
135      *
136      * @param target The IBinder this Messenger should communicate with.
137      */
Messenger(IBinder target)138     public Messenger(IBinder target) {
139         mTarget = IMessenger.Stub.asInterface(target);
140     }
141 }
142