GCKRemoteDisplayChannel Class

GCKRemoteDisplayChannel Class Reference

Overview

Orchestrates the creation of Remote Display sessions.

This class is the starting point for establishing Remote Display sessions to Google Cast receivers. Remote Display allows an app to render content locally and stream the end result to the receiver.

See also
GCKRemoteDisplaySession

Requirements

To use Remote Display, a Remote Display App ID is required. The Google Developers site contains information and links to do this. When scanning for available receivers, make sure to filter using the Remote Display App ID.

In addition, Remote Display has hardware and software requirements. Call isRemoteDisplaySupported (GCKRemoteDisplayChannel) sometime after app launch to check if Remote Display is available and disable Remote Display UI and functionality if it is not available.

How to create a Remote Display session

The basic steps for creating a Remote Display Session are as follows:

  • Check for availability by calling isRemoteDisplaySupported (GCKRemoteDisplayChannel).
  • Scan for Cast receivers using an App ID filter using GCKDeviceScanner and GCKFilterCriteria. Not all receivers support Remote Display.
  • Connect to a receiver by creating a GCKDeviceManager object and calling its connect method.
  • Once the device manager is connected, launch the Remote Display receiver app, using a custom GCKLaunchOptions object with the relaunchIfRunning property set to YES.
  • Once the receiver app has launched, create an instance of GCKRemoteDisplayChannel and add it to the device manager. Store the session ID to stop the receiver app later.
  • Once the channel has connected, create an instance of GCKRemoteDisplayConfiguration, modify the default values to suit the app and local network conditions and call beginSessionNegotiationWithConfiguration:error: to send the configuration to the receiver and finalize its parameters.
  • If the configuration is accepted by the receiver, remoteDisplayChannel:didBeginSession: will be called on the channel delegate with a new active session object.

After the session is received, an app has 15 seconds to send a frame, otherwise the session times out. Once a frame has been received, the session will remain active indefinitely as long as the app remains active (see the backgrounding section).

To end a Remote Display session, call stopApplicationWithSessionID: on the device manager with the session ID stored when the app launched. Calling stopApplication should be avoided as much as possible because another receiver app may have been launched by someone else and that method will kill it.

Resuming after app backgrounding

Normally when an iOS app goes to the background, all network connections are closed and all hardware encoder access is terminated. This effectively means that without special handling a Remote Display session will end upon app backgrounding.

However, a session can be kept alive in the background by doing the following:

  • Initialize the GCKDeviceManager with initWithDevice:clientPackageName:ignoreAppStateNotifications:, specifying YES as the ignoreAppStateNotifications argument. This transfers all responsibility for managing the device connection (specifically disconnections due to backgrounding) to the app.
  • Register a background task using UIApplication beginBackgroundTaskWithExpirationHandler: to keep the app running if it is backgrounded for an amount of time controlled by iOS. The expiration handling must be used to disconnect the device manager, invalidate the Remote Display session and end the background task.

Note that audio and video encoders are not available in the background, so no new audio or video frames can be sent in the background. One way to possibly send a "paused" frame is to register for the UIApplicationDidEnterBackgroundNotification notification, enqueue the frame on the session and block the main thread for between 100-200 ms. This should allow the frame to be delivered to the receiver before iOS cuts off access.

Background tasks are limited to about 3 minutes on iOS 8.

Inherits GCKCastChannel.

Instance Method Summary

(instancetype) - init
 Create a new Remote Display channel. More...
 
(instancetype) - initWithNamespace:
 
(BOOL) - beginSessionWithConfiguration:error:
 Create a new Remote Display session by sending the specified configuration to the receiver. More...
 
(void) - didReceiveTextMessage:
 Called when a text message has been received on this channel. More...
 
(BOOL) - sendTextMessage:
 Sends a text message on this channel. More...
 
(BOOL) - sendTextMessage:error:
 Sends a text message on this channel. More...
 
(NSInteger) - generateRequestID
 Generates a request ID for a new message. More...
 
(NSNumber *) - generateRequestNumber
 A convenience method which wraps generateRequestID in an NSNumber. More...
 
(void) - didConnect
 Called when this channel has been connected, indicating that messages can now be exchanged with the Cast device over this channel. More...
 
(void) - didDisconnect
 Called when this channel has been disconnected, indicating that messages can no longer be exchanged with the Cast device over this channel. More...
 

Class Method Summary

(BOOL) + isRemoteDisplaySupported
 Returns YES if Remote Display is supported, NO otherwise. More...
 

Properties

id
< GCKRemoteDisplayChannelDelegate
delegate
 The channel delegate receives new sessions initialized via the channel. More...
 
NSString * protocolNamespace
 The channel's namespace. More...
 
BOOL isConnected
 A flag indicating whether this channel is currently connected. More...
 
GCKDeviceManagerdeviceManager
 The device manager with which this channel is registered, if any. More...
 

Method Detail

+ (BOOL) isRemoteDisplaySupported

Returns YES if Remote Display is supported, NO otherwise.

The first invocation may be slow as it will attempt to probe various software and hardware capabilities. As an exception to the general rule of this class, it can be invoked on a background thread to avoid blocking the UI.

- (instancetype) init

Create a new Remote Display channel.

Calls isRemoteDisplaySupported and returns nil if NO.

- (BOOL) beginSessionWithConfiguration: (GCKRemoteDisplayConfiguration *)  configuration
error: (NSError **)  outError 

Create a new Remote Display session by sending the specified configuration to the receiver.

The configuration shoud be customized to fit the needs of the app and local network conditions. In particular, the resolution (video) and bitrates (audio & video) should be changed.

The configuration will be offered to the receiver which may either accept it or reject it. In either case, a suitable delegate method will be called.

If the receiver accepts the offer, a Remote Display session created internally and returned via the delegate. If the receiver rejects the offer, the app can attempt to modify the configuration and try again.

If NO is returned, no delegate method will be called and the error will indicate why the configuration could not be sent to the receiver at all.

- (void) didReceiveTextMessage: (NSString *)  message

Called when a text message has been received on this channel.

The default implementation is a no-op.

Parameters
messageThe message.
- (BOOL) sendTextMessage: (NSString *)  message

Sends a text message on this channel.

Parameters
messageThe message.
Returns
YES on success or NO if the message could not be sent (because the channel is not connected, or because the send buffer is too full at the moment).
- (BOOL) sendTextMessage: (NSString *)  message
error: (GCKError **)  error 

Sends a text message on this channel.

Parameters
messageThe message.
errorA pointer at which to store the error result. May be nil.
Returns
YES on success or NO if the message could not be sent.
- (NSInteger) generateRequestID

Generates a request ID for a new message.

Returns
The generated ID, or kGCKInvalidRequestID if the channel is not currently connected.
- (NSNumber *) generateRequestNumber

A convenience method which wraps generateRequestID in an NSNumber.

Returns
The generated ID, or nil if the channel is not currently connected.
- (void) didConnect

Called when this channel has been connected, indicating that messages can now be exchanged with the Cast device over this channel.

The default implementation is a no-op.

- (void) didDisconnect

Called when this channel has been disconnected, indicating that messages can no longer be exchanged with the Cast device over this channel.

The default implementation is a no-op.

Property Documentation

- (id<GCKRemoteDisplayChannelDelegate>) delegate
readwritenonatomicweak

The channel delegate receives new sessions initialized via the channel.

- (NSString*) protocolNamespace
readnonatomiccopyinherited

The channel's namespace.

- (BOOL) isConnected
readnonatomicassigninherited

A flag indicating whether this channel is currently connected.

- (GCKDeviceManager*) deviceManager
readnonatomicweakinherited

The device manager with which this channel is registered, if any.

Google Cast iOS Sender API Reference v 2.10.1 4691