File	Doc	Category	Size	Date	Package
Message.java	API Doc	Android 5.1 API	18693	Thu Mar 12 22:22:10 GMT 2015	android.os

Message

• java.lang.Object

Fields Summary
public int	what User-defined message code so that the recipient can identify what this message is about. Each {@link Handler} has its own name-space for message codes, so you do not need to worry about yours conflicting with other handlers.
public int	arg1 arg1 and arg2 are lower-cost alternatives to using {@link #setData(Bundle) setData()} if you only need to store a few integer values.
public int	arg2 arg1 and arg2 are lower-cost alternatives to using {@link #setData(Bundle) setData()} if you only need to store a few integer values.
public Object	obj An arbitrary object to send to the recipient. When using {@link Messenger} to send the message across processes this can only be non-null if it contains a Parcelable of a framework class (not one implemented by the application). For other data transfer use {@link #setData}. Note that Parcelable objects here are not supported prior to the {@link android.os.Build.VERSION_CODES#FROYO} release.
public Messenger	replyTo Optional Messenger where replies to this message can be sent. The semantics of exactly how this is used are up to the sender and receiver.
public int	sendingUid Optional field indicating the uid that sent the message. This is only valid for messages posted by a {@link Messenger}; otherwise, it will be -1.
static final int	FLAG_IN_USE If set message is in use. This flag is set when the message is enqueued and remains set while it is delivered and afterwards when it is recycled. The flag is only cleared when a new message is created or obtained since that is the only time that applications are allowed to modify the contents of the message. It is an error to attempt to enqueue or recycle a message that is already in use.
static final int	FLAG_ASYNCHRONOUS If set message is asynchronous
static final int	FLAGS_TO_CLEAR_ON_COPY_FROM Flags to clear in the copyFrom method
int	flags
long	when
Bundle	data
Handler	target
Runnable	callback
Message	next
private static final Object	sPoolSync
private static Message	sPool
private static int	sPoolSize
private static final int	MAX_POOL_SIZE
private static boolean	gCheckRecycle
public static final Parcelable.Creator	CREATOR

Constructors Summary
public Message() Constructor (but the preferred way to get a Message is to call {@link #obtain() Message.obtain()}).

Methods Summary
public void	copyFrom(Message o) Make this message like o. Performs a shallow copy of the data field. Does not copy the linked list fields, nor the timestamp or target/callback of the original message. this.flags = o.flags & ~FLAGS_TO_CLEAR_ON_COPY_FROM; this.what = o.what; this.arg1 = o.arg1; this.arg2 = o.arg2; this.obj = o.obj; this.replyTo = o.replyTo; this.sendingUid = o.sendingUid; if (o.data != null) { this.data = (Bundle) o.data.clone(); } else { this.data = null; }
public int	describeContents() return 0;
public java.lang.Runnable	getCallback() Retrieve callback object that will execute when this message is handled. This object must implement Runnable. This is called by the target {@link Handler} that is receiving this Message to dispatch it. If not set, the message will be dispatched to the receiving Handler's {@link Handler#handleMessage(Message Handler.handleMessage())}. return callback;
public Bundle	getData() Obtains a Bundle of arbitrary data associated with this event, lazily creating it if necessary. Set this value by calling {@link #setData(Bundle)}. Note that when transferring data across processes via {@link Messenger}, you will need to set your ClassLoader on the Bundle via {@link Bundle#setClassLoader(ClassLoader) Bundle.setClassLoader()} so that it can instantiate your objects when you retrieve them. see #peekData() see #setData(Bundle) if (data == null) { data = new Bundle(); } return data;
public Handler	getTarget() Retrieve the a {@link android.os.Handler Handler} implementation that will receive this message. The object must implement {@link android.os.Handler#handleMessage(android.os.Message) Handler.handleMessage()}. Each Handler has its own name-space for message codes, so you do not need to worry about yours conflicting with other handlers. return target;
public long	getWhen() Return the targeted delivery time of this message, in milliseconds. return when;
public boolean	isAsynchronous() Returns true if the message is asynchronous, meaning that it is not subject to {@link Looper} synchronization barriers. return True if the message is asynchronous. see #setAsynchronous(boolean) return (flags & FLAG_ASYNCHRONOUS) != 0;
boolean	isInUse() return ((flags & FLAG_IN_USE) == FLAG_IN_USE);
void	markInUse() flags |= FLAG_IN_USE;
public static Message	obtain() Return a new Message instance from the global pool. Allows us to avoid allocating new objects in many cases. synchronized (sPoolSync) { if (sPool != null) { Message m = sPool; sPool = m.next; m.next = null; m.flags = 0; // clear in-use flag sPoolSize--; return m; } } return new Message();
public static Message	obtain(Message orig) Same as {@link #obtain()}, but copies the values of an existing message (including its target) into the new one. param orig Original message to copy. return A Message object from the global pool. Message m = obtain(); m.what = orig.what; m.arg1 = orig.arg1; m.arg2 = orig.arg2; m.obj = orig.obj; m.replyTo = orig.replyTo; m.sendingUid = orig.sendingUid; if (orig.data != null) { m.data = new Bundle(orig.data); } m.target = orig.target; m.callback = orig.callback; return m;
public static Message	obtain(Handler h) Same as {@link #obtain()}, but sets the value for the target member on the Message returned. param h Handler to assign to the returned Message object's target member. return A Message object from the global pool. Message m = obtain(); m.target = h; return m;
public static Message	obtain(Handler h, java.lang.Runnable callback) Same as {@link #obtain(Handler)}, but assigns a callback Runnable on the Message that is returned. param h Handler to assign to the returned Message object's target member. param callback Runnable that will execute when the message is handled. return A Message object from the global pool. Message m = obtain(); m.target = h; m.callback = callback; return m;
public static Message	obtain(Handler h, int what) Same as {@link #obtain()}, but sets the values for both target and what members on the Message. param h Value to assign to the target member. param what Value to assign to the what member. return A Message object from the global pool. Message m = obtain(); m.target = h; m.what = what; return m;
public static Message	obtain(Handler h, int what, java.lang.Object obj) Same as {@link #obtain()}, but sets the values of the target, what, and obj members. param h The target value to set. param what The what value to set. param obj The object method to set. return A Message object from the global pool. Message m = obtain(); m.target = h; m.what = what; m.obj = obj; return m;
public static Message	obtain(Handler h, int what, int arg1, int arg2) Same as {@link #obtain()}, but sets the values of the target, what, arg1, and arg2 members. param h The target value to set. param what The what value to set. param arg1 The arg1 value to set. param arg2 The arg2 value to set. return A Message object from the global pool. Message m = obtain(); m.target = h; m.what = what; m.arg1 = arg1; m.arg2 = arg2; return m;
public static Message	obtain(Handler h, int what, int arg1, int arg2, java.lang.Object obj) Same as {@link #obtain()}, but sets the values of the target, what, arg1, arg2, and obj members. param h The target value to set. param what The what value to set. param arg1 The arg1 value to set. param arg2 The arg2 value to set. param obj The obj value to set. return A Message object from the global pool. Message m = obtain(); m.target = h; m.what = what; m.arg1 = arg1; m.arg2 = arg2; m.obj = obj; return m;
public Bundle	peekData() Like getData(), but does not lazily create the Bundle. A null is returned if the Bundle does not already exist. See {@link #getData} for further information on this. see #getData() see #setData(Bundle) return data;
private void	readFromParcel(Parcel source) what = source.readInt(); arg1 = source.readInt(); arg2 = source.readInt(); if (source.readInt() != 0) { obj = source.readParcelable(getClass().getClassLoader()); } when = source.readLong(); data = source.readBundle(); replyTo = Messenger.readMessengerOrNullFromParcel(source); sendingUid = source.readInt();
public void	recycle() Return a Message instance to the global pool. You MUST NOT touch the Message after calling this function because it has effectively been freed. It is an error to recycle a message that is currently enqueued or that is in the process of being delivered to a Handler. if (isInUse()) { if (gCheckRecycle) { throw new IllegalStateException("This message cannot be recycled because it " + "is still in use."); } return; } recycleUnchecked();
void	recycleUnchecked() Recycles a Message that may be in-use. Used internally by the MessageQueue and Looper when disposing of queued Messages. // Mark the message as in use while it remains in the recycled object pool. // Clear out all other details. flags = FLAG_IN_USE; what = 0; arg1 = 0; arg2 = 0; obj = null; replyTo = null; sendingUid = -1; when = 0; target = null; callback = null; data = null; synchronized (sPoolSync) { if (sPoolSize < MAX_POOL_SIZE) { next = sPool; sPool = this; sPoolSize++; } }
public void	sendToTarget() Sends this Message to the Handler specified by {@link #getTarget}. Throws a null pointer exception if this field has not been set. target.sendMessage(this);
public void	setAsynchronous(boolean async) Sets whether the message is asynchronous, meaning that it is not subject to {@link Looper} synchronization barriers. Certain operations, such as view invalidation, may introduce synchronization barriers into the {@link Looper}'s message queue to prevent subsequent messages from being delivered until some condition is met. In the case of view invalidation, messages which are posted after a call to {@link android.view.View#invalidate} are suspended by means of a synchronization barrier until the next frame is ready to be drawn. The synchronization barrier ensures that the invalidation request is completely handled before resuming. Asynchronous messages are exempt from synchronization barriers. They typically represent interrupts, input events, and other signals that must be handled independently even while other work has been suspended. Note that asynchronous messages may be delivered out of order with respect to synchronous messages although they are always delivered in order among themselves. If the relative order of these messages matters then they probably should not be asynchronous in the first place. Use with caution. param async True if the message is asynchronous. see #isAsynchronous() if (async) { flags |= FLAG_ASYNCHRONOUS; } else { flags &= ~FLAG_ASYNCHRONOUS; }
public void	setData(Bundle data) Sets a Bundle of arbitrary data values. Use arg1 and arg2 members as a lower cost way to send a few simple integer values, if you can. see #getData() see #peekData() this.data = data;
public void	setTarget(Handler target) this.target = target;
public java.lang.String	toString() return toString(SystemClock.uptimeMillis());
java.lang.String	toString(long now) StringBuilder b = new StringBuilder(); b.append("{ when="); TimeUtils.formatDuration(when - now, b); if (target != null) { if (callback != null) { b.append(" callback="); b.append(callback.getClass().getName()); } else { b.append(" what="); b.append(what); } if (arg1 != 0) { b.append(" arg1="); b.append(arg1); } if (arg2 != 0) { b.append(" arg2="); b.append(arg2); } if (obj != null) { b.append(" obj="); b.append(obj); } b.append(" target="); b.append(target.getClass().getName()); } else { b.append(" barrier="); b.append(arg1); } b.append(" }"); return b.toString();
public static void	updateCheckRecycle(int targetSdkVersion) hide if (targetSdkVersion < Build.VERSION_CODES.LOLLIPOP) { gCheckRecycle = false; }
public void	writeToParcel(Parcel dest, int flags) if (callback != null) { throw new RuntimeException( "Can't marshal callbacks across processes."); } dest.writeInt(what); dest.writeInt(arg1); dest.writeInt(arg2); if (obj != null) { try { Parcelable p = (Parcelable)obj; dest.writeInt(1); dest.writeParcelable(p, flags); } catch (ClassCastException e) { throw new RuntimeException( "Can't marshal non-Parcelable objects across processes."); } } else { dest.writeInt(0); } dest.writeLong(when); dest.writeBundle(data); Messenger.writeMessengerOrNullToParcel(replyTo, dest); dest.writeInt(sendingUid);