Package com.google.android.exoplayer2.source.ads

## Class AdPlaybackState

- java.lang.Object
- - com.google.android.exoplayer2.source.ads.AdPlaybackState

- All Implemented Interfaces:
    `Bundleable`

      public final class AdPlaybackState
      extends Object
      implements Bundleable

  Represents ad group times and information on the state and URIs of ads within each ad group.

  Instances are immutable. Call the `with*` methods to get new instances that have the required changes.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `AdPlaybackState.AdGroup` | Represents a group of ads, with information about their states.
    `static interface` | `AdPlaybackState.AdState` | Represents the state of an ad in an ad group.

    - ### Nested classes/interfaces inherited from interface com.google.android.exoplayer2.Bundleable

      `Bundleable.Creator<T extends Bundleable>`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `AD_STATE_AVAILABLE` | State for an ad that has a URL but has not yet been played.
    `static int` | `AD_STATE_ERROR` | State for an ad that could not be loaded.
    `static int` | `AD_STATE_PLAYED` | State for an ad that was played in full.
    `static int` | `AD_STATE_SKIPPED` | State for an ad that was skipped.
    `static int` | `AD_STATE_UNAVAILABLE` | State for an ad that does not yet have a URL.
    `int` | `adGroupCount` | The number of ad groups.
    `long` | `adResumePositionUs` | The position offset in the first unplayed ad at which to begin playback, in microseconds.
    `Object` | `adsId` | The opaque identifier for ads with which this instance is associated, or `null` if unset.
    `long` | `contentDurationUs` | The duration of the content period in microseconds, if known.
    `static Bundleable.Creator<AdPlaybackState>` | `CREATOR` | Object that can restore `AdPlaybackState` from a `Bundle`.
    `static AdPlaybackState` | `NONE` | Ad playback state with no ads.
    `int` | `removedAdGroupCount` | The number of ad groups the have been removed.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `AdPlaybackState​(Object adsId, long... adGroupTimesUs)` | Creates a new ad playback state with the specified ad group times.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(Object o)` |
    `AdPlaybackState.AdGroup` | `getAdGroup​(int adGroupIndex)` | Returns the specified `AdPlaybackState.AdGroup`.
    `int` | `getAdGroupIndexAfterPositionUs​(long positionUs, long periodDurationUs)` | Returns the index of the next ad group after `positionUs` that should be played.
    `int` | `getAdGroupIndexForPositionUs​(long positionUs, long periodDurationUs)` | Returns the index of the ad group at or before `positionUs` that should be played before the content at `positionUs`.
    `int` | `hashCode()` |
    `boolean` | `isAdInErrorState​(int adGroupIndex, int adIndexInAdGroup)` | Returns whether the specified ad has been marked as in `AD_STATE_ERROR`.
    `Bundle` | `toBundle()` | Returns a `Bundle` representing the information stored in this object.
    `String` | `toString()` |
    `AdPlaybackState` | `withAdCount​(int adGroupIndex, int adCount)` | Returns an instance with the number of ads in `adGroupIndex` resolved to `adCount`.
    `AdPlaybackState` | `withAdDurationsUs​(int adGroupIndex, long... adDurationsUs)` | Returns an instance with the specified ad durations, in microseconds, in the specified ad group.
    `AdPlaybackState` | `withAdDurationsUs​(long[][] adDurationUs)` | Returns an instance with the specified ad durations, in microseconds.
    `AdPlaybackState` | `withAdGroupTimeUs​(int adGroupIndex, long adGroupTimeUs)` | Returns an instance with the specified ad group time.
    `AdPlaybackState` | `withAdLoadError​(int adGroupIndex, int adIndexInAdGroup)` | Returns an instance with the specified ad marked as having a load error.
    `AdPlaybackState` | `withAdResumePositionUs​(long adResumePositionUs)` | Returns an instance with the specified ad resume position, in microseconds, relative to the start of the current ad.
    `AdPlaybackState` | `withAdUri​(int adGroupIndex, int adIndexInAdGroup, Uri uri)` | Returns an instance with the specified ad URI.
    `AdPlaybackState` | `withContentDurationUs​(long contentDurationUs)` | Returns an instance with the specified content duration, in microseconds.
    `AdPlaybackState` | `withContentResumeOffsetUs​(int adGroupIndex, long contentResumeOffsetUs)` | Returns an instance with the specified `AdPlaybackState.AdGroup.contentResumeOffsetUs`, in microseconds, for the specified ad group.
    `AdPlaybackState` | `withIsServerSideInserted​(int adGroupIndex, boolean isServerSideInserted)` | Returns an instance with the specified value for `AdPlaybackState.AdGroup.isServerSideInserted` in the specified ad group.
    `AdPlaybackState` | `withNewAdGroup​(int adGroupIndex, long adGroupTimeUs)` | Returns an instance with a new ad group.
    `AdPlaybackState` | `withPlayedAd​(int adGroupIndex, int adIndexInAdGroup)` | Returns an instance with the specified ad marked as played.
    `AdPlaybackState` | `withRemovedAdGroupCount​(int removedAdGroupCount)` | Returns an instance with the specified number of `removed ad groups`.
    `AdPlaybackState` | `withSkippedAd​(int adGroupIndex, int adIndexInAdGroup)` | Returns an instance with the specified ad marked as skipped.
    `AdPlaybackState` | `withSkippedAdGroup​(int adGroupIndex)` | Returns an instance with all ads in the specified ad group skipped (except for those already marked as played or in the error state).

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### AD_STATE_UNAVAILABLE

          public static final int AD_STATE_UNAVAILABLE

      State for an ad that does not yet have a URL.
      See Also:
        Constant Field Values

    - #### AD_STATE_AVAILABLE

          public static final int AD_STATE_AVAILABLE

      State for an ad that has a URL but has not yet been played.
      See Also:
        Constant Field Values

    - #### AD_STATE_SKIPPED

          public static final int AD_STATE_SKIPPED

      State for an ad that was skipped.
      See Also:
        Constant Field Values

    - #### AD_STATE_PLAYED

          public static final int AD_STATE_PLAYED

      State for an ad that was played in full.
      See Also:
        Constant Field Values

    - #### AD_STATE_ERROR

          public static final int AD_STATE_ERROR

      State for an ad that could not be loaded.
      See Also:
        Constant Field Values

    - #### NONE

          public static final AdPlaybackState NONE

      Ad playback state with no ads.

    - #### adsId

          @Nullable
          public final Object adsId

      The opaque identifier for ads with which this instance is associated, or `null` if unset.

    - #### adGroupCount

          public final int adGroupCount

      The number of ad groups.

    - #### adResumePositionUs

          public final long adResumePositionUs

      The position offset in the first unplayed ad at which to begin playback, in microseconds.

    - #### contentDurationUs

          public final long contentDurationUs

      The duration of the content period in microseconds, if known. `C.TIME_UNSET` otherwise.

    - #### removedAdGroupCount

          public final int removedAdGroupCount

      The number of ad groups the have been removed. Ad groups with indices between `0` (inclusive) and `removedAdGroupCount` (exclusive) will be empty and must not be modified by any of the `with*` methods.

    - #### CREATOR

          public static final Bundleable.Creator<AdPlaybackState> CREATOR

      Object that can restore `AdPlaybackState` from a `Bundle`.

      The `adsId` of restored instances will always be `null`.

  - ### Constructor Detail

    - #### AdPlaybackState

          public AdPlaybackState​(Object adsId,
                                 long... adGroupTimesUs)

      Creates a new ad playback state with the specified ad group times.
      Parameters:
        `adsId` - The opaque identifier for ads with which this instance is associated.
        `adGroupTimesUs` - The times of ad groups in microseconds, relative to the start of the `Timeline.Period` they belong to. A final element with the value `C.TIME_END_OF_SOURCE` indicates that there is a postroll ad.

  - ### Method Detail

    - #### getAdGroup

          public AdPlaybackState.AdGroup getAdGroup​(int adGroupIndex)

      Returns the specified `AdPlaybackState.AdGroup`.

    - #### getAdGroupIndexForPositionUs

          public int getAdGroupIndexForPositionUs​(long positionUs,
                                                  long periodDurationUs)

      Returns the index of the ad group at or before `positionUs` that should be played before the content at `positionUs`. Returns `C.INDEX_UNSET` if the ad group at or before `positionUs` has no ads remaining to be played, or if there is no such ad group.
      Parameters:
        `positionUs` - The period position at or before which to find an ad group, in microseconds, or `C.TIME_END_OF_SOURCE` for the end of the stream (in which case the index of any unplayed postroll ad group will be returned).
        `periodDurationUs` - The duration of the containing timeline period, in microseconds, or `C.TIME_UNSET` if not known.
      Returns:
        The index of the ad group, or `C.INDEX_UNSET`.

    - #### getAdGroupIndexAfterPositionUs

          public int getAdGroupIndexAfterPositionUs​(long positionUs,
                                                    long periodDurationUs)

      Returns the index of the next ad group after `positionUs` that should be played. Returns `C.INDEX_UNSET` if there is no such ad group.
      Parameters:
        `positionUs` - The period position after which to find an ad group, in microseconds, or `C.TIME_END_OF_SOURCE` for the end of the stream (in which case there can be no ad group after the position).
        `periodDurationUs` - The duration of the containing timeline period, in microseconds, or `C.TIME_UNSET` if not known.
      Returns:
        The index of the ad group, or `C.INDEX_UNSET`.

    - #### isAdInErrorState

          public boolean isAdInErrorState​(int adGroupIndex,
                                          int adIndexInAdGroup)

      Returns whether the specified ad has been marked as in `AD_STATE_ERROR`.

    - #### withAdGroupTimeUs

          @CheckResult
          public AdPlaybackState withAdGroupTimeUs​(int adGroupIndex,
                                                   long adGroupTimeUs)

      Returns an instance with the specified ad group time.
      Parameters:
        `adGroupIndex` - The index of the ad group.
        `adGroupTimeUs` - The new ad group time, in microseconds, or `C.TIME_END_OF_SOURCE` to indicate a postroll ad.
      Returns:
        The updated ad playback state.

    - #### withNewAdGroup

          @CheckResult
          public AdPlaybackState withNewAdGroup​(int adGroupIndex,
                                                long adGroupTimeUs)

      Returns an instance with a new ad group.
      Parameters:
        `adGroupIndex` - The insertion index of the new group.
        `adGroupTimeUs` - The ad group time, in microseconds, or `C.TIME_END_OF_SOURCE` to indicate a postroll ad.
      Returns:
        The updated ad playback state.

    - #### withAdCount

          @CheckResult
          public AdPlaybackState withAdCount​(int adGroupIndex,
                                             int adCount)

      Returns an instance with the number of ads in `adGroupIndex` resolved to `adCount`. The ad count must be greater than zero.

    - #### withAdUri

          @CheckResult
          public AdPlaybackState withAdUri​(int adGroupIndex,
                                           int adIndexInAdGroup,
                                           Uri uri)

      Returns an instance with the specified ad URI.

    - #### withPlayedAd

          @CheckResult
          public AdPlaybackState withPlayedAd​(int adGroupIndex,
                                              int adIndexInAdGroup)

      Returns an instance with the specified ad marked as played.

    - #### withSkippedAd

          @CheckResult
          public AdPlaybackState withSkippedAd​(int adGroupIndex,
                                               int adIndexInAdGroup)

      Returns an instance with the specified ad marked as skipped.

    - #### withAdLoadError

          @CheckResult
          public AdPlaybackState withAdLoadError​(int adGroupIndex,
                                                 int adIndexInAdGroup)

      Returns an instance with the specified ad marked as having a load error.

    - #### withSkippedAdGroup

          @CheckResult
          public AdPlaybackState withSkippedAdGroup​(int adGroupIndex)

      Returns an instance with all ads in the specified ad group skipped (except for those already marked as played or in the error state).

    - #### withAdDurationsUs

          @CheckResult
          public AdPlaybackState withAdDurationsUs​(long[][] adDurationUs)

      Returns an instance with the specified ad durations, in microseconds.

      Must only be used if `removedAdGroupCount` is 0.

    - #### withAdDurationsUs

          @CheckResult
          public AdPlaybackState withAdDurationsUs​(int adGroupIndex,
                                                   long... adDurationsUs)

      Returns an instance with the specified ad durations, in microseconds, in the specified ad group.

    - #### withAdResumePositionUs

          @CheckResult
          public AdPlaybackState withAdResumePositionUs​(long adResumePositionUs)

      Returns an instance with the specified ad resume position, in microseconds, relative to the start of the current ad.

    - #### withContentDurationUs

          @CheckResult
          public AdPlaybackState withContentDurationUs​(long contentDurationUs)

      Returns an instance with the specified content duration, in microseconds.

    - #### withRemovedAdGroupCount

          @CheckResult
          public AdPlaybackState withRemovedAdGroupCount​(int removedAdGroupCount)

      Returns an instance with the specified number of `removed ad groups`.

      Ad groups with indices between `0` (inclusive) and `removedAdGroupCount` (exclusive) will be empty and must not be modified by any of the `with*` methods.

    - #### withContentResumeOffsetUs

          @CheckResult
          public AdPlaybackState withContentResumeOffsetUs​(int adGroupIndex,
                                                           long contentResumeOffsetUs)

      Returns an instance with the specified `AdPlaybackState.AdGroup.contentResumeOffsetUs`, in microseconds, for the specified ad group.

    - #### withIsServerSideInserted

          @CheckResult
          public AdPlaybackState withIsServerSideInserted​(int adGroupIndex,
                                                          boolean isServerSideInserted)

      Returns an instance with the specified value for `AdPlaybackState.AdGroup.isServerSideInserted` in the specified ad group.

    - #### equals

          public boolean equals​(@Nullable
                                Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### toBundle

          public Bundle toBundle()

      Returns a `Bundle` representing the information stored in this object.

      It omits the `adsId` field so the `adsId` of instances restored by `CREATOR` will always be `null`.

      Specified by:
        `toBundle` in interface `Bundleable`