Message
class Message : Parcelable
kotlin.Any | |
↳ | 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 #obtain or one of the android.os.Handler#obtainMessage methods, which will pull them from a pool of recycled objects.
Summary
Inherited constants | |
---|---|
Public constructors | |
---|---|
Message() Constructor (but the preferred way to get a Message is to call |
Public methods | |
---|---|
Unit |
Make this message like o. |
Int | |
Runnable! |
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! |
Retrieve the |
Long |
getWhen() Return the targeted delivery time of this message, in milliseconds. |
Boolean |
Returns true if the message is asynchronous, meaning that it is not subject to |
static Message! |
obtain() Return a new Message instance from the global pool. |
static Message! |
Same as |
static Message! |
Same as |
static Message! |
Same as |
static Message! |
Same as |
static Message! |
Same as |
static Message! |
Same as |
static Message! |
Same as |
Bundle? |
peekData() Like getData(), but does not lazily create the Bundle. |
Unit |
recycle() Return a Message instance to the global pool. |
Unit |
Sends this Message to the Handler specified by |
Unit |
setAsynchronous(async: Boolean) Sets whether the message is asynchronous, meaning that it is not subject to |
Unit |
Sets a Bundle of arbitrary data values. |
Unit | |
String |
toString() |
Unit |
writeToParcel(dest: Parcel, flags: Int) |
Properties | |
---|---|
static Parcelable.Creator<Message!> | |
Int |
arg1 and arg2 are lower-cost alternatives to using |
Int |
arg1 and arg2 are lower-cost alternatives to using |
Any! |
An arbitrary object to send to the recipient. |
Messenger! |
Optional Messenger where replies to this message can be sent. |
Int |
Optional field indicating the uid that sent the message. |
Int |
User-defined message code so that the recipient can identify what this message is about. |
Public constructors
Message
Message()
Constructor (but the preferred way to get a Message is to call Message.obtain()
).
Public methods
copyFrom
fun copyFrom(o: Message!): Unit
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.
describeContents
fun describeContents(): Int
Return | |
---|---|
Int |
a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or android.os.Parcelable#CONTENTS_FILE_DESCRIPTOR |
getCallback
fun getCallback(): Runnable!
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)
.
getData
fun getData(): Bundle!
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.
See Also
getTarget
fun getTarget(): Handler!
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.
getWhen
fun getWhen(): Long
Return the targeted delivery time of this message, in milliseconds.
isAsynchronous
fun isAsynchronous(): Boolean
Returns true if the message is asynchronous, meaning that it is not subject to Looper
synchronization barriers.
Return | |
---|---|
Boolean |
True if the message is asynchronous. |
See Also
obtain
static fun obtain(): Message!
Return a new Message instance from the global pool. Allows us to avoid allocating new objects in many cases.
obtain
static fun obtain(orig: Message!): Message!
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. |
Return | |
---|---|
Message! |
A Message object from the global pool. |
obtain
static fun obtain(h: Handler!): Message!
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. |
Return | |
---|---|
Message! |
A Message object from the global pool. |
obtain
static fun obtain(
h: Handler!,
callback: Runnable!
): Message!
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. |
Return | |
---|---|
Message! |
A Message object from the global pool. |
obtain
static fun obtain(
h: Handler!,
what: Int
): Message!
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. |
Return | |
---|---|
Message! |
A Message object from the global pool. |
obtain
static fun obtain(
h: Handler!,
what: Int,
obj: Any!
): Message!
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 |
Any!: The object method to set. |
Return | |
---|---|
Message! |
A Message object from the global pool. |
obtain
static fun obtain(
h: Handler!,
what: Int,
arg1: Int,
arg2: Int
): Message!
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. |
Return | |
---|---|
Message! |
A Message object from the global pool. |
obtain
static fun obtain(
h: Handler!,
what: Int,
arg1: Int,
arg2: Int,
obj: Any!
): Message!
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 |
Any!: The obj value to set. |
Return | |
---|---|
Message! |
A Message object from the global pool. |
peekData
fun peekData(): Bundle?
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
recycle
fun recycle(): Unit
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
fun sendToTarget(): Unit
Sends this Message to the Handler specified by getTarget
. Throws a null pointer exception if this field has not been set.
setAsynchronous
fun setAsynchronous(async: Boolean): Unit
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 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.
Parameters | |
---|---|
async |
Boolean: True if the message is asynchronous. |
See Also
setData
fun setData(data: Bundle!): Unit
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
toString
fun toString(): String
Return | |
---|---|
String |
a string representation of the object. |
writeToParcel
fun writeToParcel(
dest: Parcel,
flags: Int
): Unit
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_WRITE_RETURN_VALUE . Value is either 0 or a combination of android.os.Parcelable#PARCELABLE_WRITE_RETURN_VALUE , and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES |
Properties
arg1
var arg1: Int
arg1 and arg2 are lower-cost alternatives to using setData()
if you only need to store a few integer values.
arg2
var arg2: Int
arg1 and arg2 are lower-cost alternatives to using setData()
if you only need to store a few integer values.
obj
var obj: Any!
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
.
Note that Parcelable objects here are not supported prior to the android.os.Build.VERSION_CODES#FROYO
release.
replyTo
var replyTo: Messenger!
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
var sendingUid: Int
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
var what: Int
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.