Overview
A data model representation of a media queue of arbitrary length.
This class can be used as the basis for an implementation of a UITableViewDataSource for driving a media queue UI.
GCKMediaQueue listens for GCKSessionManager events and automatically attaches itself to the GCKRemoteMediaClient when a Cast session is started. It listens for queue change notifications from the GCKRemoteMediaClient and updates its internal data model accordingly. Likewise, it uses the GCKRemoteMediaClient to fetch queue information on demand.
The model maintains a list of queue item IDs for the entire queue; it automatically fetches this list whenever it attaches to a Cast session. It also maintains an LRU cache (of configurable size) of GCKMediaQueueItems, keyed by the queue item ID.
The method itemAtIndex: (GCKMediaQueue) is used to fetch a queue item at a given index. If the GCKMediaQueueItem is not currently in the cache, an asynchronous request is made to fetch that item from the receiver, and the delegate is eventually notified when the requested items are received.
If multiple calls to this method are made in a very short amount of time, the requested item IDs are batched internally to reduce the number of network requests made. Because there is an upper limit to how many queue items can be fetched from the receiver at a time, GCKMediaQueue keeps a rolling window of the last N item IDs to be fetched. Therefore if a very large number of items is requested in a short amount of time, only the last N items will actually be fetched. This behavior allows for the efficient management of a very long queue in the app's UI which may be quickly and/or frequently scrolled through by a user.
GCKMediaQueue does not provide any methods for directly modifying the queue, because any such change involves an asynchronous network request to the receiver (via methods on GCKRemoteMediaClient), which can potentially fail with an error. GCKMediaQueue must ensure a consistent representation of the queue as it exists on the receiver, so making local changes to the data model which are not yet committed on the receiver could result in incorrect UI behavior.
See GCKMediaQueueDelegate for the delegate protocol.
- Since
- 4.3.4
Inherits NSObject.
Instance Method Summary | |
| (instancetype) | - init |
| (instancetype) | - initWithRemoteMediaClient: |
| Initializes a new GCKMediaQueue with the default cache size and default max fetch count. More... | |
| (instancetype) | - initWithRemoteMediaClient:cacheSize: |
| Initializes a new GCKMediaQueue with the given cache size and default max fetch count. More... | |
| (instancetype) | - initWithRemoteMediaClient:cacheSize:maxFetchCount: |
| Initializes a new GCKMediaQueue with the given cache size and given max fetch count. More... | |
| (void) | - addDelegate: |
| Adds a delegate to this object's list of delegates. More... | |
| (void) | - removeDelegate: |
| Removes a delegate from this object's list of delegates. More... | |
| (nullable GCKMediaQueueItem *) | - itemAtIndex: |
| Returns the media queue item at the given index in the queue, or arranges to have the item fetched from the receiver if it is not currently in the cache. More... | |
| (nullable GCKMediaQueueItem *) | - itemAtIndex:fetchIfNeeded: |
| Returns the media queue item at the given index in the queue, or optionally arranges to have the item fetched from the receiver if it is not currently in the cache. More... | |
| (GCKMediaQueueItemID) | - itemIDAtIndex: |
| Returns the item ID of the item at the given index in the queue. More... | |
| (NSInteger) | - indexOfItemWithID: |
| Looks up the index of a queue item in the queue. More... | |
| (void) | - reload |
| Reloads the queue. More... | |
| (void) | - clear |
| Clears the queue, removing all elements and flushing the cache. More... | |
Property Summary | |
| NSUInteger | itemCount |
| The number of items currently in the queue. More... | |
| NSUInteger | cacheSize |
| The cache size. More... | |
| NSUInteger | cachedItemCount |
| The number of queue items that are currently in the cache. More... | |
Method Detail
| - (instancetype) initWithRemoteMediaClient: | (GCKRemoteMediaClient *) | remoteMediaClient |
Initializes a new GCKMediaQueue with the default cache size and default max fetch count.
| - (instancetype) initWithRemoteMediaClient: | (GCKRemoteMediaClient *) | remoteMediaClient | |
| cacheSize: | (NSUInteger) | cacheSize | |
Initializes a new GCKMediaQueue with the given cache size and default max fetch count.
- Parameters
-
cacheSize The cache size. Must be nonzero.
| - (instancetype) initWithRemoteMediaClient: | (GCKRemoteMediaClient *) | remoteMediaClient | |
| cacheSize: | (NSUInteger) | cacheSize | |
| maxFetchCount: | (NSUInteger) | maxFetchCount | |
Initializes a new GCKMediaQueue with the given cache size and given max fetch count.
- Parameters
-
cacheSize The cache size. Must be nonzero. maxFetchCount The maxiumum fetch count with minimum being 1.
| - (void) addDelegate: | (id< GCKMediaQueueDelegate >) | delegate |
Adds a delegate to this object's list of delegates.
- Parameters
-
delegate The delegate to add. The delegate will be retained until removeDelegate: is called.
| - (void) removeDelegate: | (id< GCKMediaQueueDelegate >) | delegate |
Removes a delegate from this object's list of delegates.
- Parameters
-
delegate The delegate to remove.
| - (nullable GCKMediaQueueItem *) itemAtIndex: | (NSUInteger) | index |
Returns the media queue item at the given index in the queue, or arranges to have the item fetched from the receiver if it is not currently in the cache.
- Parameters
-
index The index of the item to fetch.
- Returns
- The item at the given index, or
nilif the item is not currently in the cache, but will be fetched asynchronously.
| - (nullable GCKMediaQueueItem *) itemAtIndex: | (NSUInteger) | index | |
| fetchIfNeeded: | (BOOL) | fetch | |
Returns the media queue item at the given index in the queue, or optionally arranges to have the item fetched from the receiver if it is not currently in the cache.
- Parameters
-
index The index of the item to fetch. fetch Whether the item should be fetched from the receiver if it is not currently in the cache.
- Returns
- The item at the given index, or
nilif the item is not currently in the cache.
| - (GCKMediaQueueItemID) itemIDAtIndex: | (NSUInteger) | index |
Returns the item ID of the item at the given index in the queue.
- Returns
- The item ID at the given index, or kGCKMediaQueueInvalidItemID if the index is invalid.
| - (NSInteger) indexOfItemWithID: | (GCKMediaQueueItemID) | itemID |
Looks up the index of a queue item in the queue.
- Parameters
-
itemID The queue item ID.
- Returns
- The index (that is, the cardinal position) of the item within the queue, or NSNotFound if there is no such item in the queue.
| - (void) reload |
Reloads the queue.
The cache will be flushed and the item ID list will be re-fetched from the receiver.
| - (void) clear |
Clears the queue, removing all elements and flushing the cache.
Property Detail
|
readnonatomicassign |
The number of items currently in the queue.
|
readnonatomicassign |
The cache size.
|
readnonatomicassign |
The number of queue items that are currently in the cache.