Android APIs
public final class

Message

extends Object
implements Parcelable
java.lang.Object
   ↳ android.os.Message

Class Overview

Defines a message containing a description and arbitrary data object that can be sent to a Handler. This object contains two extra int fields and an extra object field that allow you to not do allocations in many cases.

While the constructor of Message is public, the best way to get one of these is to call Message.obtain() or one of the Handler.obtainMessage() methods, which will pull them from a pool of recycled objects.

Summary

[Expand]
Inherited Constants
From interface android.os.Parcelable
Fields
public static final Creator<Message> CREATOR
public int arg1 arg1 and arg2 are lower-cost alternatives to using setData() if you only need to store a few integer values.
public int arg2 arg1 and arg2 are lower-cost alternatives to using setData() if you only need to store a few integer values.
public Object obj An arbitrary object to send to the recipient.
public Messenger replyTo Optional Messenger where replies to this message can be sent.
public int sendingUid Optional field indicating the uid that sent the message.
public int what User-defined message code so that the recipient can identify what this message is about.
Public Constructors
Message()
Constructor (but the preferred way to get a Message is to call Message.obtain()).
Public Methods
void copyFrom(Message o)
Make this message like o.
int describeContents()
Describe the kinds of special objects contained in this Parcelable's marshalled representation.
Runnable getCallback()
Retrieve callback object that will execute when this message is handled.
Bundle getData()
Obtains a Bundle of arbitrary data associated with this event, lazily creating it if necessary.
Handler getTarget()
Retrieve the a Handler implementation that will receive this message.
long getWhen()
Return the targeted delivery time of this message, in milliseconds.
boolean isAsynchronous()
Returns true if the message is asynchronous, meaning that it is not subject to Looper synchronization barriers.
static Message obtain(Handler h, int what, int arg1, int arg2, Object obj)
Same as obtain(), but sets the values of the target, what, arg1, arg2, and obj members.
static Message obtain(Handler h, int what, Object obj)
Same as obtain(), but sets the values of the target, what, and obj members.
static Message obtain(Handler h, int what)
Same as obtain(), but sets the values for both target and what members on the Message.
static Message obtain(Handler h)
Same as obtain(), but sets the value for the target member on the Message returned.
static Message obtain(Handler h, Runnable callback)
Same as obtain(Handler), but assigns a callback Runnable on the Message that is returned.
static Message obtain()
Return a new Message instance from the global pool.
static Message obtain(Handler h, int what, int arg1, int arg2)
Same as obtain(), but sets the values of the target, what, arg1, and arg2 members.
static Message obtain(Message orig)
Same as obtain(), but copies the values of an existing message (including its target) into the new one.
Bundle peekData()
Like getData(), but does not lazily create the Bundle.
void recycle()
Return a Message instance to the global pool.
void sendToTarget()
Sends this Message to the Handler specified by getTarget().
void setAsynchronous(boolean async)
Sets whether the message is asynchronous, meaning that it is not subject to Looper synchronization barriers.
void setData(Bundle data)
Sets a Bundle of arbitrary data values.
void setTarget(Handler target)
String toString()
Returns a string containing a concise, human-readable description of this object.
void writeToParcel(Parcel dest, int flags)
Flatten this object in to a Parcel.
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.os.Parcelable

Fields

public static final Creator<Message> CREATOR

Added in API level 1

public int arg1

Added in API level 1

arg1 and arg2 are lower-cost alternatives to using setData() if you only need to store a few integer values.

public int arg2

Added in API level 1

arg1 and arg2 are lower-cost alternatives to using setData() if you only need to store a few integer values.

public Object obj

Added in API level 1

An arbitrary object to send to the recipient. When using 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 setData(Bundle).

Note that Parcelable objects here are not supported prior to the FROYO release.

public Messenger replyTo

Added in API level 1

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

Added in API level 21

Optional field indicating the uid that sent the message. This is only valid for messages posted by a Messenger; otherwise, it will be -1.

public int what

Added in API level 1

User-defined message code so that the recipient can identify what this message is about. Each Handler has its own name-space for message codes, so you do not need to worry about yours conflicting with other handlers.

Public Constructors

public Message ()

Added in API level 1

Constructor (but the preferred way to get a Message is to call Message.obtain()).

Public Methods

public void copyFrom (Message o)

Added in API level 1

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.

public int describeContents ()

Added in API level 1

Describe the kinds of special objects contained in this Parcelable's marshalled representation.

Returns
  • a bitmask indicating the set of special object types marshalled by the Parcelable.

public Runnable getCallback ()

Added in API level 1

Retrieve callback object that will execute when this message is handled. This object must implement Runnable. This is called by the target Handler that is receiving this Message to dispatch it. If not set, the message will be dispatched to the receiving Handler's handleMessage(Message).

public Bundle getData ()

Added in API level 1

Obtains a Bundle of arbitrary data associated with this event, lazily creating it if necessary. Set this value by calling setData(Bundle). Note that when transferring data across processes via Messenger, you will need to set your ClassLoader on the Bundle via Bundle.setClassLoader() so that it can instantiate your objects when you retrieve them.

See Also

public Handler getTarget ()

Added in API level 1

Retrieve the a Handler implementation that will receive this message. The object must implement 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.

public long getWhen ()

Added in API level 1

Return the targeted delivery time of this message, in milliseconds.

public boolean isAsynchronous ()

Returns true if the message is asynchronous, meaning that it is not subject to Looper synchronization barriers.

Returns
  • True if the message is asynchronous.
See Also

public static Message obtain (Handler h, int what, int arg1, int arg2, Object obj)

Added in API level 1

Same as obtain(), but sets the values of the target, what, arg1, arg2, and obj members.

Parameters
h The target value to set.
what The what value to set.
arg1 The arg1 value to set.
arg2 The arg2 value to set.
obj The obj value to set.
Returns
  • A Message object from the global pool.

public static Message obtain (Handler h, int what, Object obj)

Added in API level 1

Same as obtain(), but sets the values of the target, what, and obj members.

Parameters
h The target value to set.
what The what value to set.
obj The object method to set.
Returns
  • A Message object from the global pool.

public static Message obtain (Handler h, int what)

Added in API level 1

Same as obtain(), but sets the values for both target and what members on the Message.

Parameters
h Value to assign to the target member.
what Value to assign to the what member.
Returns
  • A Message object from the global pool.

public static Message obtain (Handler h)

Added in API level 1

Same as obtain(), but sets the value for the target member on the Message returned.

Parameters
h Handler to assign to the returned Message object's target member.
Returns
  • A Message object from the global pool.

public static Message obtain (Handler h, Runnable callback)

Added in API level 1

Same as obtain(Handler), but assigns a callback Runnable on the Message that is returned.

Parameters
h Handler to assign to the returned Message object's target member.
callback Runnable that will execute when the message is handled.
Returns
  • A Message object from the global pool.

public static Message obtain ()

Added in API level 1

Return a new Message instance from the global pool. Allows us to avoid allocating new objects in many cases.

public static Message obtain (Handler h, int what, int arg1, int arg2)

Added in API level 1

Same as obtain(), but sets the values of the target, what, arg1, and arg2 members.

Parameters
h The target value to set.
what The what value to set.
arg1 The arg1 value to set.
arg2 The arg2 value to set.
Returns
  • A Message object from the global pool.

public static Message obtain (Message orig)

Added in API level 1

Same as obtain(), but copies the values of an existing message (including its target) into the new one.

Parameters
orig Original message to copy.
Returns
  • A Message object from the global pool.

public Bundle peekData ()

Added in API level 1

Like getData(), but does not lazily create the Bundle. A null is returned if the Bundle does not already exist. See getData() for further information on this.

See Also

public void recycle ()

Added in API level 1

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.

public void sendToTarget ()

Added in API level 1

Sends this Message to the Handler specified by getTarget(). Throws a null pointer exception if this field has not been set.

public void setAsynchronous (boolean async)

Sets whether the message is asynchronous, meaning that it is not subject to Looper synchronization barriers.

Certain operations, such as view invalidation, may introduce synchronization barriers into the 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 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.

Parameters
async True if the message is asynchronous.
See Also

public void setData (Bundle data)

Added in API level 1

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 Also

public void setTarget (Handler target)

Added in API level 1

public String toString ()

Added in API level 1

Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression: 

   getClass().getName() + '@' + Integer.toHexString(hashCode())

See Writing a useful toString method if you intend implementing your own toString method.

Returns
  • a printable representation of this object.

public void writeToParcel (Parcel dest, int flags)

Added in API level 1

Flatten this object in to a Parcel.

Parameters
dest The Parcel in which the object should be written.
flags Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE.