GCKDeviceManager Class

GCKDeviceManager Class Reference

Overview

A controller for Cast devices.

This class can send messages to, receive messages from, launch, and close applications running on a Cast device.

The GCKDeviceManager instance must stay in scope as long as a connection to the Cast device is established or is in the process of being created or torn down. It is safe to release the object before a connection has been started with connect (GCKDeviceManager), or after either the deviceManager:didDisconnectWithError: (GCKDeviceManagerDelegate-p), deviceManager:didSuspendConnectionWithReason: (GCKDeviceManagerDelegate-p), or deviceManager:didFailToConnectWithError: (GCKDeviceManagerDelegate-p) delegate callback has been invoked.

Deprecated:
Use GCKSessionManager and GCKCastSession to interact with Cast receivers.

Inherits NSObject.

Instance Method Summary

(instancetype) - initWithDevice:clientPackageName:
 Constructs a new GCKDeviceManager with the given device. More...
 
(instancetype) - initWithDevice:clientPackageName:ignoreAppStateNotifications:
 Designated initializer. More...
 
(void) - connect
 Connects to the device. More...
 
(void) - disconnect
 Disconnects from the device. More...
 
(void) - disconnectWithLeave:
 Disconnects from the device. More...
 
(BOOL) - addChannel:
 Adds a channel which can send and receive messages for this device on a particular namespace. More...
 
(BOOL) - removeChannel:
 Removes a previously added channel. More...
 
(NSInteger) - launchApplication:
 Launches an application. More...
 
(NSInteger) - launchApplication:withLaunchOptions:
 Launches an application using the given launch options. More...
 
(NSInteger) - launchApplication:relaunchIfRunning:
 Launches an application, optionally relaunching it if it is already running. More...
 
(NSInteger) - joinApplication:
 Joins an application. More...
 
(NSInteger) - joinApplication:sessionID:
 Joins an application with a particular application session ID. More...
 
(BOOL) - leaveApplication
 Leaves the current application. More...
 
(NSInteger) - stopApplication
 Stops any running application(s). More...
 
(NSInteger) - stopApplicationWithSessionID:
 Stops the application with the given application session ID. More...
 
(NSInteger) - setVolume:
 Sets the system volume. More...
 
(NSInteger) - setMuted:
 Turns muting on or off. More...
 
(NSInteger) - requestDeviceStatus
 Requests the device's current status. More...
 

Property Summary

BOOL ignoreAppStateNotifications
 Whether this object will listen for app state notifications. More...
 
GCKConnectionState connectionState
 The device manager's current connection state. More...
 
GCKConnectionState applicationConnectionState
 The device manager's current application connection state. More...
 
BOOL isConnected
 True if the device manager has established a connection to the device. More...
 
BOOL isConnectedToApp
 True if the device manager has established a connection to an application on the device. More...
 
BOOL isReconnecting
 True if the device manager is disconnected due to a potentially transient event (for example, the app is backgrounded, or there was a network error which might be solved by reconnecting). More...
 
NSTimeInterval reconnectTimeout
 Reconnection will be attempted for this long in the event that the socket disconnects with a potentially transient error. More...
 
GCKDevicedevice
 The device that is being controlled by this GCKDeviceManager. More...
 
id< GCKDeviceManagerDelegatedelegate
 The delegate for receiving notifications from the GCKDeviceManager. More...
 
float deviceVolume
 The current volume of the device in the range [0.0, 1.0], if known; otherwise 0. More...
 
BOOL deviceMuted
 The current mute state of the device, if known; otherwise NO. More...
 
GCKActiveInputStatus activeInputStatus
 The device's current "active input" status. More...
 
GCKStandbyStatus standbyStatus
 The device's current "standby" status. More...
 
NSString * applicationSessionID
 The application session ID for the currently connected receiver application, if any; otherwise nil. More...
 
GCKApplicationMetadataapplicationMetadata
 The metadata for the receiver application that is currently running on the receiver, if any; otherwise nil. More...
 
NSString * applicationStatusText
 The most recently reported status text from the currently running receiver application, if any; otherwise nil. More...
 

Method Detail

- (instancetype) initWithDevice: (GCKDevice *)  device
clientPackageName: (NSString *)  clientPackageName 

Constructs a new GCKDeviceManager with the given device.

The object will listen for app state notifications, and will automatically disconnect from the device when the app goes into the background and attempt to reconnect to the device when the app returns to the foreground.

Parameters
deviceThe device to control.
clientPackageNameThe client package name.
- (instancetype) initWithDevice: (GCKDevice *)  device
clientPackageName: (NSString *)  clientPackageName
ignoreAppStateNotifications: (BOOL)  ignoreAppStateNotifications 

Designated initializer.

Constructs a new GCKDeviceManager for controlling the given device.

If ignoreAppStateNotifications is NO, the object will listen for changes to the app state and will automatically disconnect from the device when the app goes into the background and attempt to reconnect to the device when the app returns to the foreground.

If ignoreAppStateNotifications is YES, the object will not listen for these notifications, and it will be the app's responsibility to manage the connection lifecycle. Note that in general, a backgrounded iOS app cannot continue running indefinitely, and its active network connections will eventually be closed by the operating system.

Parameters
deviceThe device to control.
clientPackageNameThe client package name.
ignoreAppStateNotificationsWhether this object will ignore app state notifications.
- (void) connect

Connects to the device.

- (void) disconnect

Disconnects from the device.

This is an explicit disconnect.

One of the disconnect methods must be called at some point after connect was called and before this object is released by its owner.

- (void) disconnectWithLeave: (BOOL)  leaveApplication

Disconnects from the device.

One of the disconnect methods must be called at some point after connect was called and before this object is released by its owner.

Parameters
leaveApplicationYES if this is an explicit disconnect that should disconnect from ("leave") the receiver application before closing the connection; NO if this is an implicit disconnect that should just close the connection.
- (BOOL) addChannel: (GCKCastChannel *)  channel

Adds a channel which can send and receive messages for this device on a particular namespace.

Parameters
channelThe channel.
Returns
YES if the channel was added, NO if it was not added because there was already a channel attached for that namespace.
- (BOOL) removeChannel: (GCKCastChannel *)  channel

Removes a previously added channel.

Parameters
channelThe channel.
Returns
YES if the channel was removed, NO if it was not removed because the given channel was not previously attached.
- (NSInteger) launchApplication: (NSString *)  applicationID

Launches an application.

Parameters
applicationIDThe application ID.
Returns
The request ID, or kGCKInvalidRequestID if the request could not be sent.
- (NSInteger) launchApplication: (NSString *)  applicationID
withLaunchOptions: (GCKLaunchOptions *__nullable)  launchOptions 

Launches an application using the given launch options.

Parameters
applicationIDThe application ID.
launchOptionsThe launch options for this request. If nil, defaults will be used.
Returns
The request ID, or kGCKInvalidRequestID if the request could not be sent.
- (NSInteger) launchApplication: (NSString *)  applicationID
relaunchIfRunning: (BOOL)  relaunchIfRunning 

Launches an application, optionally relaunching it if it is already running.

Deprecated:
Use launchApplication:withLaunchOptions: instead.
Parameters
applicationIDThe application ID.
relaunchIfRunningIf YES, relaunches the application if it is already running instead of joining the running application.
Returns
The request ID, or kGCKInvalidRequestID if the request could not be sent.
- (NSInteger) joinApplication: (NSString *__nullable)  applicationID

Joins an application.

Parameters
applicationIDThe application ID. If nil, attempts to join whichever application is currently running; otherwise, attempts to join the specified application.
Returns
The request ID, or kGCKInvalidRequestID if the request could not be sent.
- (NSInteger) joinApplication: (NSString *)  applicationID
sessionID: (NSString *)  sessionID 

Joins an application with a particular application session ID.

The request will fail if the given session ID is no longer active on the receiver.

Parameters
applicationIDThe application ID.
sessionIDThe application session ID.
Returns
The request ID, or kGCKInvalidRequestID if the request could not be sent.
- (BOOL) leaveApplication

Leaves the current application.

Returns
NO if the message could not be sent.
- (NSInteger) stopApplication

Stops any running application(s).

Returns
The request ID, or kGCKInvalidRequestID if the request could not be sent.
- (NSInteger) stopApplicationWithSessionID: (NSString *__nullable)  sessionID

Stops the application with the given application session ID.

The request will fail if the given session ID is no longer active on the receiver.

Parameters
sessionIDThe application session ID, which may not be nil.
Returns
The request ID, or kGCKInvalidRequestID if the request could not be sent.
- (NSInteger) setVolume: (float)  volume

Sets the system volume.

Parameters
volumeThe new volume, in the range [0.0, 1.0]. Out of range values will be silently clipped.
Returns
The request ID, or kGCKInvalidRequestID if the request could not be sent.
- (NSInteger) setMuted: (BOOL)  muted

Turns muting on or off.

Parameters
mutedWhether audio should be muted or unmuted.
Returns
The request ID, or kGCKInvalidRequestID if the request could not be sent.
- (NSInteger) requestDeviceStatus

Requests the device's current status.

This will result in all of the delegate status update callbacks being invoked once the updated status information is received.

Returns
The request ID, or kGCKInvalidRequestID if the request could not be sent.

Property Detail

- (BOOL) ignoreAppStateNotifications
readnonatomicassign

Whether this object will listen for app state notifications.

This flag may be specified in the initializer. The default value is NO.

- (GCKConnectionState) connectionState
readnonatomicassign

The device manager's current connection state.

- (GCKConnectionState) applicationConnectionState
readnonatomicassign

The device manager's current application connection state.

- (BOOL) isConnected
readnonatomicassign

True if the device manager has established a connection to the device.

Deprecated:
Use connectionState.
- (BOOL) isConnectedToApp
readnonatomicassign

True if the device manager has established a connection to an application on the device.

Deprecated:
Use applicationConnectionState.
- (BOOL) isReconnecting
readnonatomicassign

True if the device manager is disconnected due to a potentially transient event (for example, the app is backgrounded, or there was a network error which might be solved by reconnecting).

Note that the disconnection/connection callbacks will not be called while the device manager attemps to reconnect after a potentially transient event, but the properties will always reflect the actual current state and can be observed.

- (NSTimeInterval) reconnectTimeout
readwritenonatomicassign

Reconnection will be attempted for this long in the event that the socket disconnects with a potentially transient error.

The default timeout is 15 seconds.

- (GCKDevice*) device
readnonatomicassign

The device that is being controlled by this GCKDeviceManager.

- (id<GCKDeviceManagerDelegate>) delegate
readwritenonatomicweak

The delegate for receiving notifications from the GCKDeviceManager.

- (float) deviceVolume
readnonatomicassign

The current volume of the device in the range [0.0, 1.0], if known; otherwise 0.

- (BOOL) deviceMuted
readnonatomicassign

The current mute state of the device, if known; otherwise NO.

- (GCKActiveInputStatus) activeInputStatus
readnonatomicassign

The device's current "active input" status.

- (GCKStandbyStatus) standbyStatus
readnonatomicassign

The device's current "standby" status.

- (NSString*) applicationSessionID
readnonatomiccopy

The application session ID for the currently connected receiver application, if any; otherwise nil.

A new, unique session ID is generated whenever a receiver application is launched (including when the same application is relaunched) and remains in effect as long as the receiver application continues running.

- (GCKApplicationMetadata*) applicationMetadata
readnonatomiccopy

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

- (NSString*) applicationStatusText
readnonatomiccopy

The most recently reported status text from the currently running receiver application, if any; otherwise nil.