Package com.google.android.exoplayer2

## Class PlayerMessage

- java.lang.Object
- - com.google.android.exoplayer2.PlayerMessage

-     public final class PlayerMessage
      extends Object

  Defines a player message which can be sent with a `PlayerMessage.Sender` and received by a `PlayerMessage.Target`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `PlayerMessage.Sender` | A sender for messages.
    `static interface` | `PlayerMessage.Target` | A target for messages.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `PlayerMessage​(PlayerMessage.Sender sender, PlayerMessage.Target target, Timeline timeline, int defaultWindowIndex, Clock clock, Looper defaultLooper)` | Creates a new message.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `blockUntilDelivered()` | Blocks until after the message has been delivered or the player is no longer able to deliver the message.
    `boolean` | `blockUntilDelivered​(long timeoutMs)` | Blocks until after the message has been delivered or the player is no longer able to deliver the message or the specified timeout elapsed.
    `PlayerMessage` | `cancel()` | Cancels the message delivery.
    `boolean` | `getDeleteAfterDelivery()` | Returns whether the message will be deleted after delivery.
    `Looper` | `getLooper()` | Returns the `Looper` the message is delivered on.
    `Object` | `getPayload()` | Returns the message payload forwarded to `PlayerMessage.Target.handleMessage(int, Object)`.
    `long` | `getPositionMs()` | Returns position in window at `getWindowIndex()` at which the message will be delivered, in milliseconds.
    `PlayerMessage.Target` | `getTarget()` | Returns the target the message is sent to.
    `Timeline` | `getTimeline()` | Returns the timeline used for setting the position with `setPosition(long)`.
    `int` | `getType()` | Returns the message type forwarded to `PlayerMessage.Target.handleMessage(int, Object)`.
    `int` | `getWindowIndex()` | Returns window index at which the message will be delivered.
    `boolean` | `isCanceled()` | Returns whether the message delivery has been canceled.
    `void` | `markAsProcessed​(boolean isDelivered)` | Marks the message as processed.
    `PlayerMessage` | `send()` | Sends the message.
    `PlayerMessage` | `setDeleteAfterDelivery​(boolean deleteAfterDelivery)` | Sets whether the message will be deleted after delivery.
    `PlayerMessage` | `setHandler​(Handler handler)` | Deprecated. Use `setLooper(Looper)` instead.
    `PlayerMessage` | `setLooper​(Looper looper)` | Sets the `Looper` the message is delivered on.
    `PlayerMessage` | `setPayload​(Object payload)` | Sets the message payload forwarded to `PlayerMessage.Target.handleMessage(int, Object)`.
    `PlayerMessage` | `setPosition​(int windowIndex, long positionMs)` | Sets a position in a window at which the message will be delivered.
    `PlayerMessage` | `setPosition​(long positionMs)` | Sets a position in the current window at which the message will be delivered.
    `PlayerMessage` | `setType​(int messageType)` | Sets the message type forwarded to `PlayerMessage.Target.handleMessage(int, Object)`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### PlayerMessage

          public PlayerMessage​(PlayerMessage.Sender sender,
                               PlayerMessage.Target target,
                               Timeline timeline,
                               int defaultWindowIndex,
                               Clock clock,
                               Looper defaultLooper)

      Creates a new message.
      Parameters:
        `sender` - The `PlayerMessage.Sender` used to send the message.
        `target` - The `PlayerMessage.Target` the message is sent to.
        `timeline` - The timeline used when setting the position with `setPosition(long)`. If set to `Timeline.EMPTY`, any position can be specified.
        `defaultWindowIndex` - The default window index in the `timeline` when no other window index is specified.
        `clock` - The `Clock`.
        `defaultLooper` - The default `Looper` to send the message on when no other looper is specified.

  - ### Method Detail

    - #### getTimeline

          public Timeline getTimeline()

      Returns the timeline used for setting the position with `setPosition(long)`.

    - #### getTarget

          public PlayerMessage.Target getTarget()

      Returns the target the message is sent to.

    - #### setType

          public PlayerMessage setType​(int messageType)

      Sets the message type forwarded to `PlayerMessage.Target.handleMessage(int, Object)`.
      Parameters:
        `messageType` - The message type.
      Returns:
        This message.
      Throws:
        `IllegalStateException` - If `send()` has already been called.

    - #### getType

          public int getType()

      Returns the message type forwarded to `PlayerMessage.Target.handleMessage(int, Object)`.

    - #### setPayload

          public PlayerMessage setPayload​(@Nullable
                                          Object payload)

      Sets the message payload forwarded to `PlayerMessage.Target.handleMessage(int, Object)`.
      Parameters:
        `payload` - The message payload.
      Returns:
        This message.
      Throws:
        `IllegalStateException` - If `send()` has already been called.

    - #### getPayload

          @Nullable
          public Object getPayload()

      Returns the message payload forwarded to `PlayerMessage.Target.handleMessage(int, Object)`.

    - #### setHandler

          @Deprecated
          public PlayerMessage setHandler​(Handler handler)

      Deprecated.
      Use `setLooper(Looper)` instead.

    - #### setLooper

          public PlayerMessage setLooper​(Looper looper)

      Sets the `Looper` the message is delivered on.
      Parameters:
        `looper` - A `Looper`.
      Returns:
        This message.
      Throws:
        `IllegalStateException` - If `send()` has already been called.

    - #### getLooper

          public Looper getLooper()

      Returns the `Looper` the message is delivered on.

    - #### getPositionMs

          public long getPositionMs()

      Returns position in window at `getWindowIndex()` at which the message will be delivered, in milliseconds. If `C.TIME_UNSET`, the message will be delivered immediately. If `C.TIME_END_OF_SOURCE`, the message will be delivered at the end of the window at `getWindowIndex()`.

    - #### setPosition

          public PlayerMessage setPosition​(long positionMs)

      Sets a position in the current window at which the message will be delivered.
      Parameters:
        `positionMs` - The position in the current window at which the message will be sent, in milliseconds, or `C.TIME_END_OF_SOURCE` to deliver the message at the end of the current window.
      Returns:
        This message.
      Throws:
        `IllegalStateException` - If `send()` has already been called.

    - #### setPosition

          public PlayerMessage setPosition​(int windowIndex,
                                           long positionMs)

      Sets a position in a window at which the message will be delivered.
      Parameters:
        `windowIndex` - The index of the window at which the message will be sent.
        `positionMs` - The position in the window with index `windowIndex` at which the message will be sent, in milliseconds, or `C.TIME_END_OF_SOURCE` to deliver the message at the end of the window with index `windowIndex`.
      Returns:
        This message.
      Throws:
        `IllegalSeekPositionException` - If the timeline returned by `getTimeline()` is not empty and the provided window index is not within the bounds of the timeline.
        `IllegalStateException` - If `send()` has already been called.

    - #### getWindowIndex

          public int getWindowIndex()

      Returns window index at which the message will be delivered.

    - #### setDeleteAfterDelivery

          public PlayerMessage setDeleteAfterDelivery​(boolean deleteAfterDelivery)

      Sets whether the message will be deleted after delivery. If false, the message will be resent if playback reaches the specified position again. Only allowed to be false if a position is set with `setPosition(long)`.
      Parameters:
        `deleteAfterDelivery` - Whether the message is deleted after delivery.
      Returns:
        This message.
      Throws:
        `IllegalStateException` - If `send()` has already been called.

    - #### getDeleteAfterDelivery

          public boolean getDeleteAfterDelivery()

      Returns whether the message will be deleted after delivery.

    - #### send

          public PlayerMessage send()

      Sends the message. If the target throws an `ExoPlaybackException` then it is propagated out of the player as an error using `Player.Listener.onPlayerError(PlaybackException)`.
      Returns:
        This message.
      Throws:
        `IllegalStateException` - If this message has already been sent.

    - #### cancel

          public PlayerMessage cancel()

      Cancels the message delivery.
      Returns:
        This message.
      Throws:
        `IllegalStateException` - If this method is called before `send()`.

    - #### isCanceled

          public boolean isCanceled()

      Returns whether the message delivery has been canceled.

    - #### markAsProcessed

          public void markAsProcessed​(boolean isDelivered)

      Marks the message as processed. Should only be called by a `PlayerMessage.Sender` and may be called multiple times.
      Parameters:
        `isDelivered` - Whether the message has been delivered to its target. The message is considered as being delivered when this method has been called with `isDelivered` set to true at least once.

    - #### blockUntilDelivered

          public boolean blockUntilDelivered()
                                      throws InterruptedException

      Blocks until after the message has been delivered or the player is no longer able to deliver the message.

      Note that this method must not be called if the current thread is the same thread used by the message `looper` as it would cause a deadlock.

      Returns:
        Whether the message was delivered successfully.
      Throws:
        `IllegalStateException` - If this method is called before `send()`.
        `IllegalStateException` - If this method is called on the same thread used by the message `looper`.
        `InterruptedException` - If the current thread is interrupted while waiting for the message to be delivered.

    - #### blockUntilDelivered

          public boolean blockUntilDelivered​(long timeoutMs)
                                      throws InterruptedException,
                                             TimeoutException

      Blocks until after the message has been delivered or the player is no longer able to deliver the message or the specified timeout elapsed.

      Note that this method must not be called if the current thread is the same thread used by the message `looper` as it would cause a deadlock.

      Parameters:
        `timeoutMs` - The timeout in milliseconds.
      Returns:
        Whether the message was delivered successfully.
      Throws:
        `IllegalStateException` - If this method is called before `send()`.
        `IllegalStateException` - If this method is called on the same thread used by the message `looper`.
        `TimeoutException` - If the `timeoutMs` elapsed and this message has not been delivered and the player is still able to deliver the message.
        `InterruptedException` - If the current thread is interrupted while waiting for the message to be delivered.