Added in API level 1

Summary: Inherited Constants | Fields | Ctors | Methods | Inherited Methods

Message

---

Kotlin |Java

public final class Message
extends Object implements Parcelable

java.lang.Object
↳	android.os.Message

---

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

Inherited constants

From interface android.os.Parcelable int CONTENTS_FILE_DESCRIPTOR Descriptor bit used with describeContents(): indicates that the Parcelable object's flattened representation includes a file descriptor. int PARCELABLE_WRITE_RETURN_VALUE Flag for use with writeToParcel(Parcel, int): the object being written is a return value, that is the result of a function such as "Parcelable someFunction()", "void someFunction(out Parcelable)", or "void someFunction(inout 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 instance's marshaled 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 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) Same as obtain(), but sets the value for the target member on the Message returned.
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, Runnable callback) Same as obtain(android.os.Handler), but assigns a callback Runnable on the Message that is returned.
static Message	obtain(Message orig) Same as obtain(), but copies the values of an existing message (including its target) into the new one.
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, int arg1, int arg2) Same as obtain(), but sets the values of the target, what, arg1, and arg2 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() Return a new Message instance from the global pool.
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 representation of the object.
void	writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.

Inherited methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
From interface android.os.Parcelable abstract int describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. abstract void writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.

Fields

CREATOR

Added in API level 1

public static final Creator<Message> CREATOR

arg1

Added in API level 1

public int arg1

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

arg2

Added in API level 1

public int arg2

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

obj

Added in API level 1

public Object obj

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 Build.VERSION_CODES.FROYO release.

replyTo

Added in API level 1

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.

sendingUid

Added in API level 21

public int sendingUid

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

what

Added in API level 1

public int what

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. If not specified, this value is 0. Use values other than 0 to indicate custom message codes.

Public constructors

Message

Added in API level 1

public Message ()

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

Public methods

copyFrom

Added in API level 1

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.

Parameters
o	Message

describeContents

Added in API level 1

public int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of writeToParcel(android.os.Parcel, int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

Returns
int	a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or CONTENTS_FILE_DESCRIPTOR

getCallback

Added in API level 1

public Runnable getCallback ()

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 Handler.handleMessage(Message).

Returns
Runnable

getData

Added in API level 1

public Bundle getData ()

Obtains a Bundle of arbitrary data associated with this event, lazily creating it if necessary. Set this value by calling setData(android.os.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.

Returns
Bundle

See also:

• peekData()
• setData(Bundle)

getTarget

Added in API level 1

public Handler getTarget ()

Retrieve the 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.

Returns
Handler

getWhen

Added in API level 1

public long getWhen ()

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

Returns
long

isAsynchronous

Added in API level 22

public boolean isAsynchronous ()

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

Returns
boolean	True if the message is asynchronous.

See also:

• setAsynchronous(boolean)

obtain

Added in API level 1

public static Message obtain (Handler h)

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

Parameters
h	Handler: Handler to assign to the returned Message object's target member.

Returns
Message	A Message object from the global pool.

obtain

Added in API level 1

public static Message obtain (Handler h, 
                int what)

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

Parameters
h	Handler: Value to assign to the target member.
what	int: Value to assign to the what member.

Returns
Message	A Message object from the global pool.

obtain

Added in API level 1

public static Message obtain (Handler h, 
                Runnable callback)

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

Parameters
h	Handler: Handler to assign to the returned Message object's target member.
callback	Runnable: Runnable that will execute when the message is handled.

Returns
Message	A Message object from the global pool.

obtain

Added in API level 1

public static Message obtain (Message orig)

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

Parameters
orig	Message: Original message to copy.

Returns
Message	A Message object from the global pool.

obtain

Added in API level 1

public 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.

Parameters
h	Handler: The target value to set.
what	int: The what value to set.
arg1	int: The arg1 value to set.
arg2	int: The arg2 value to set.
obj	Object: The obj value to set.

Returns
Message	A Message object from the global pool.

obtain

Added in API level 1

public 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.

Parameters
h	Handler: The target value to set.
what	int: The what value to set.
arg1	int: The arg1 value to set.
arg2	int: The arg2 value to set.

Returns
Message	A Message object from the global pool.

obtain

Added in API level 1

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

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

Parameters
h	Handler: The target value to set.
what	int: The what value to set.
obj	Object: The object method to set.

Returns
Message	A Message object from the global pool.

obtain

Added in API level 1

public static Message obtain ()

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

Returns
Message

peekData

Added in API level 1

public Bundle peekData ()

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.

Returns
Bundle

See also:

• getData()
• setData(Bundle)

recycle

Added in API level 1

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.

sendToTarget

Added in API level 1

public void sendToTarget ()

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

setAsynchronous

Added in API level 22

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 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.

Parameters
async	boolean: True if the message is asynchronous.

See also:

• isAsynchronous()

setData

Added in API level 1

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.

Parameters
data	Bundle

See also:

• getData()
• peekData()

setTarget

Added in API level 1

public void setTarget (Handler target)

Parameters
target	Handler

toString

Added in API level 1

public String toString ()

Returns a string representation of the object.

Returns
String	a string representation of the object.

writeToParcel

Added in API level 1

public void writeToParcel (Parcel dest, 
                int flags)

Flatten this object in to a Parcel.

Parameters
dest	Parcel: The Parcel in which the object should be written. This value cannot be null.
flags	int: Additional flags about how the object should be written. May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE. Value is either 0 or a combination of Parcelable.PARCELABLE_WRITE_RETURN_VALUE, and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES