GCKMediaQueue Class

GCKMediaQueue Class Reference

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
cacheSizeThe 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
cacheSizeThe cache size. Must be nonzero.
maxFetchCountThe maxiumum fetch count with minimum being 1.
- (void) addDelegate: (id< GCKMediaQueueDelegate >)  delegate

Adds a delegate to this object's list of delegates.

Parameters
delegateThe 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
delegateThe 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
indexThe index of the item to fetch.
Returns
The item at the given index, or nil if 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
indexThe index of the item to fetch.
fetchWhether the item should be fetched from the receiver if it is not currently in the cache.
Returns
The item at the given index, or nil if 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
itemIDThe 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

- (NSUInteger) itemCount
readnonatomicassign

The number of items currently in the queue.

- (NSUInteger) cacheSize
readnonatomicassign

The cache size.

- (NSUInteger) cachedItemCount
readnonatomicassign

The number of queue items that are currently in the cache.