GCKCastSession Class

GCKCastSession Class Reference

Overview

A class that manages a Cast session with a receiver device.

Sessions are created and managed automatically by the GCKSessionManager. The application should not directly call the session lifecycle methods such as start (GCKSession(Protected)) or endWithAction: (GCKSession(Protected)).

Since
3.0

Inherits GCKSession.

Instance Method Summary

(instancetype) - initWithDevice:sessionID:sessionOptions:castOptions:
 Constructs a new Cast session with the given Cast options. More...
 
(BOOL) - addChannel:
 Registers a channel with the session. More...
 
(BOOL) - removeChannel:
 Removes a previously registered channel from the session. More...
 
(void) - addDeviceStatusListener:
 Adds a GCKCastDeviceStatusListener to this object's list of listeners. More...
 
(void) - removeDeviceStatusListener:
 Removes a GCKCastDeviceStatusListener from this object's list of listeners. More...
 
(GCKRequest *) - setDeviceVolume:forMultizoneDevice:
 Sets the individual device's volume in a multizone group. More...
 
(GCKRequest *) - setDeviceMuted:forMultizoneDevice:
 Sets the individual device's muted state in a multizone group. More...
 
(GCKRequest *) - requestMultizoneStatus
 Request multizone status from a multizone group. More...
 
(instancetype) - initWithDevice:traits:sessionID:
 Initializes a new session object for the given device, with default options. More...
 
(instancetype) - initWithDevice:traits:sessionID:sessionOptions:
 Initializes a new session object for the given device. More...
 
(GCKRequest *) - setDeviceVolume:
 Sets the device's volume. More...
 
(GCKRequest *) - setDeviceMuted:
 Sets the device's mute state. More...
 
(void) - start
 Starts the session. More...
 
(void) - endWithAction:
 Ends the session with the specified action. More...
 
(void) - notifyDidStartWithSessionID:
 Called by subclasses to notify the framework that the session has been started. More...
 
(void) - notifyDidFailToStartWithError:
 Called by subclasses to notify the framework that the session has failed to start. More...
 
(void) - notifyDidEndWithError:willTryToResume:
 Called by subclasses to notify the framework that the session has ended. More...
 
(void) - notifyDidReceiveDeviceVolume:muted:
 Called by subclasses to notify the framework that updated device volume and mute state has been received from the device. More...
 
(void) - notifyDidReceiveDeviceStatus:
 Called by subclasses to notify the framework that updated status has been received from the device. More...
 
(void) - notifyDidSuspendWithReason:
 Deprecated, do not use - implemented as a no-op. More...
 
(void) - notifyDidResume
 Deprecated, do not use - implemented as a no-op. More...
 

Property Summary

GCKActiveInputStatus activeInputStatus
 The device's current "active input" status. More...
 
GCKStandbyStatus standbyStatus
 The device's current "standby" status. More...
 
GCKApplicationMetadataapplicationMetadata
 The metadata for the receiver application that is currently running on the receiver device, if any; otherwise nil. More...
 
GCKDevicedevice
 The device that this session is associated with. More...
 
NSString * sessionID
 The current session ID, if any. More...
 
GCKSessionOptions * sessionOptions
 The session options, if any. More...
 
GCKConnectionState connectionState
 The current session connection state. More...
 
BOOL suspended
 A flag indicating whether the session is currently suspended. More...
 
NSString * deviceStatusText
 The current device status text. More...
 
GCKSessionTraitstraits
 The session traits. More...
 
float currentDeviceVolume
 The current device volume, in the range [0.0, 1.0]. More...
 
BOOL currentDeviceMuted
 The current device mute state. More...
 
GCKRemoteMediaClientremoteMediaClient
 The GCKRemoteMediaClient object that can be used to control media playback in this session. More...
 
GCKMediaMetadatamediaMetadata
 The current media metadata, if any. More...
 

Method Detail

- (instancetype) initWithDevice: (GCKDevice *)  device
sessionID: (nullable NSString *)  sessionID
sessionOptions: (nullable GCKSessionOptions *)  sessionOptions
castOptions: (GCKCastOptions *)  castOptions 

Constructs a new Cast session with the given Cast options.

Parameters
deviceThe receiver device.
sessionIDThe session ID, if resuming; otherwise nil.
sessionOptionsThe session options, if any; otherwise nil.
castOptionsThe Cast options.
Since
4.0
- (BOOL) addChannel: (GCKCastChannel *)  channel

Registers a channel with the session.

If the session is connected and the receiver application supports the channel's namespace, the channel will be automatically connected. If the session is not connected, the channel will remain in a disconnected state until the session is started.

Parameters
channelThe channel to register.
Returns
YES if the channel was registered successfully, NO otherwise.
- (BOOL) removeChannel: (GCKCastChannel *)  channel

Removes a previously registered channel from the session.

Parameters
channelThe channel to unregister.
Returns
YES if the channel was unregistered successfully, NO otherwise.
- (void) addDeviceStatusListener: (id< GCKCastDeviceStatusListener >)  listener

Adds a GCKCastDeviceStatusListener to this object's list of listeners.

The added listener is weakly held, and should be retained to avoid unexpected deallocation.

Parameters
listenerThe listener to add.
- (void) removeDeviceStatusListener: (id< GCKCastDeviceStatusListener >)  listener

Removes a GCKCastDeviceStatusListener from this object's list of listeners.

Parameters
listenerThe listener to remove.
- (GCKRequest *) setDeviceVolume: (float)  volume
forMultizoneDevice: (GCKMultizoneDevice *)  device 

Sets the individual device's volume in a multizone group.

This is an asynchronous operation.

Parameters
volumeThe new volume, in the range [0.0, 1.0].
deviceThe multizone device.
Returns
A GCKRequest object for tracking the request.
- (GCKRequest *) setDeviceMuted: (BOOL)  muted
forMultizoneDevice: (GCKMultizoneDevice *)  device 

Sets the individual device's muted state in a multizone group.

This is an asynchronous operation.

Parameters
mutedThe new muted state.
deviceThe multizone device.
Returns
A GCKRequest object for tracking the request.
- (GCKRequest *) requestMultizoneStatus

Request multizone status from a multizone group.

This is an asynchronous operation. When the multizone status is received, the castSession:didReceiveMultizoneStatus: (GCKCastDeviceStatusListener-p) delegate method will be messaged.

Returns
A GCKRequest object for tracking the request.
- (instancetype) initWithDevice: (GCKDevice *)  device
traits: (nullable GCKSessionTraits *)  traits
sessionID: (nullable NSString *)  sessionID 

Initializes a new session object for the given device, with default options.

Parameters
deviceThe device.
traitsThe session traits.
sessionIDThe session ID of an existing session, if this object will be used to resume a session; otherwise nil if it will be used to start a new session.
- (instancetype) initWithDevice: (GCKDevice *)  device
traits: (nullable GCKSessionTraits *)  traits
sessionID: (nullable NSString *)  sessionID
sessionOptions: (nullable GCKSessionOptions *)  sessionOptions 

Initializes a new session object for the given device.

Parameters
deviceThe device.
traitsThe session traits.
sessionIDThe session ID of an existing session, if this object will be used to resume a session; otherwise nil if it will be used to start a new session.
sessionOptionsThe session options, if any; otherwise nil.
Since
4.0
- (GCKRequest *) setDeviceVolume: (float)  volume

Sets the device's volume.

This is an asynchronous operation. The default implementation is a no-op that fails the request with a GCKErrorCodeUnsupportedFeature error.

Parameters
volumeThe new volume.
Returns
A GCKRequest object for tracking the request.
Since
3.4; in previous framework versions, this method returned void.
- (GCKRequest *) setDeviceMuted: (BOOL)  muted

Sets the device's mute state.

This is an asynchronous operation. The default implementation is a no-op that fails the request with a GCKErrorCodeUnsupportedFeature error.

Parameters
mutedThe new mute state.
Returns
A GCKRequest object for tracking the request.
Since
3.4; in previous framework versions, this method returned void.
- (void) start

Starts the session.

This is an asynchronous operation. Must be overridden by subclasses.

Provided by category GCKSession(Protected).

- (void) endWithAction: (GCKSessionEndAction action

Ends the session with the specified action.

This is an asynchronous operation. Must be overridden by subclasses.

Parameters
actionThe action to take when ending the session; see GCKSessionEndAction for more details.

Provided by category GCKSession(Protected).

- (void) notifyDidStartWithSessionID: (NSString *)  sessionID

Called by subclasses to notify the framework that the session has been started.

Parameters
sessionIDThe session's unique ID.

Provided by category GCKSession(Protected).

- (void) notifyDidFailToStartWithError: (GCKError *)  error

Called by subclasses to notify the framework that the session has failed to start.

Parameters
errorThe error that occurred.

Provided by category GCKSession(Protected).

- (void) notifyDidEndWithError: (nullable NSError *)  error
willTryToResume: (BOOL)  willTryToResume 

Called by subclasses to notify the framework that the session has ended.

Parameters
errorThe error that caused the session to end, if any. Should be nil if the session was ended intentionally.
willTryToResumeWhether the session will try to resume itself automatically.

Provided by category GCKSession(Protected).

- (void) notifyDidReceiveDeviceVolume: (float)  volume
muted: (BOOL)  muted 

Called by subclasses to notify the framework that updated device volume and mute state has been received from the device.

Parameters
volumeThe device's current volume. Must be in the range [0, 1.0];
mutedThe device's current mute state.

Provided by category GCKSession(Protected).

- (void) notifyDidReceiveDeviceStatus: (nullable NSString *)  statusText

Called by subclasses to notify the framework that updated status has been received from the device.

Parameters
statusTextThe new status.

Provided by category GCKSession(Protected).

- (void) notifyDidSuspendWithReason: (GCKConnectionSuspendReason reason

Deprecated, do not use - implemented as a no-op.

Deprecated:
Do not call.

Provided by category GCKSession(Protected).

- (void) notifyDidResume

Deprecated, do not use - implemented as a no-op.

Deprecated:
Do not call.

Provided by category GCKSession(Protected).

Property Detail

- (GCKActiveInputStatus) activeInputStatus
readnonatomicassign

The device's current "active input" status.

- (GCKStandbyStatus) standbyStatus
readnonatomicassign

The device's current "standby" status.

- (GCKApplicationMetadata*) applicationMetadata
readnonatomiccopy

The metadata for the receiver application that is currently running on the receiver device, if any; otherwise nil.

- (GCKDevice*) device
readnonatomicstronginherited

The device that this session is associated with.

- (NSString*) sessionID
readnonatomiccopyinherited

The current session ID, if any.

- (GCKSessionOptions*) sessionOptions
readnonatomicstronginherited

The session options, if any.

Since
4.0
- (GCKConnectionState) connectionState
readnonatomicassigninherited

The current session connection state.

- (BOOL) suspended
readnonatomicassigninherited

A flag indicating whether the session is currently suspended.

Deprecated:
GCKSession no longer supports being in suspended state. If needed, move this functionality to a subclass.
- (NSString*) deviceStatusText
readnonatomiccopyinherited

The current device status text.

- (GCKSessionTraits*) traits
readnonatomiccopyinherited

The session traits.

- (float) currentDeviceVolume
readnonatomicassigninherited

The current device volume, in the range [0.0, 1.0].

- (BOOL) currentDeviceMuted
readnonatomicassigninherited

The current device mute state.

- (GCKRemoteMediaClient*) remoteMediaClient
readnonatomicstronginherited

The GCKRemoteMediaClient object that can be used to control media playback in this session.

It is nil before the session has started, or if the session does not support the GCKRemoteMediaClient API. Subclasses which provide a GCKRemoteMediaClient interface must override the getter method.

- (GCKMediaMetadata*) mediaMetadata
readnonatomicstronginherited

The current media metadata, if any.

Will be nil if the session does not support the media namespace or if no media is currently loaded on the receiver.