AT&T U verse Enabled · included in a functional U-verse Enabled app. These elements include a...

© 2014 AT&T Intellectual Property. All rights reserved. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property.

AT&T U-verse® Enabled

How to Write Your First AT&T U-verse Enabled iOS® App

Publication Date: September 9, 2014

Legal Disclaimer


i

This document and the information contained herein (collectively, the "Information") is provided to you (both the individual receiving

this document and any legal entity on behalf of which such individual is acting) ("You" and "Your") by AT&T, on behalf of itself and

its affiliates ("AT&T") for informational purposes only. AT&T is providing the Information to You because AT&T believes the

Information may be useful to You. The Information is provided to You solely on the basis that You will be responsible for making

Your own assessments of the Information and are advised to verify all representations, statements and information before using or

relying upon any of the Information. Although AT&T has exercised reasonable care in providing the Information to You, AT&T does

not warrant the accuracy of the Information and is not responsible for any damages arising from Your use of or reliance upon the

Information. You further understand and agree that AT&T in no way represents, and You in no way rely on a belief, that AT&T is

providing the Information in accordance with any standard or service (routine, customary or otherwise) related to the consult ing,

services, hardware or software industries.

AT&T DOES NOT WARRANT THAT THE INFORMATION IS ERROR-FREE. AT&T IS PROVIDING THE INFORMATION TO YOU

"AS IS" AND "WITH ALL FAULTS." AT&T DOES NOT WARRANT, BY VIRTUE OF THIS DOCUMENT, OR BY ANY COURSE OF

PERFORMANCE, COURSE OF DEALING, USAGE OF TRADE OR ANY COLLATERAL DOCUMENT HEREUNDER OR

OTHERWISE, AND HEREBY EXPRESSLY DISCLAIMS, ANY REPRESENTATION OR WARRANTY OF ANY KIND WITH

RESPECT TO THE INFORMATION, INCLUDING, WITHOUT LIMITATION, ANY REPRESENTATION OR WARRANTY OF

DESIGN, PERFORMANCE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, OR

ANY REPRESENTATION OR WARRANTY THAT THE INFORMATION IS APPLICABLE TO OR INTEROPERABLE WITH ANY

SYSTEM, DATA, HARDWARE OR SOFTWARE OF ANY KIND. AT&T DISCLAIMS AND IN NO EVENT SHALL BE LIABLE FOR

ANY LOSSES OR DAMAGES OF ANY KIND, WHETHER DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE,

SPECIAL OR EXEMPLARY, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS

INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF GOODWILL, COVER, TORTIOUS CONDUCT OR OTHER

PECUNIARY LOSS, ARISING OUT OF OR IN ANY WAY RELATED TO THE PROVISION, NON-PROVISION, USE OR NON-USE

OF THE INFORMATION, EVEN IF AT&T HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES OR DAMAGES.

Table of Contents


ii

Contents

1 Introduction .................................................................................................................................... 1

2 Overview ......................................................................................................................................... 2

3 Initial Setup ..................................................................................................................................... 4

4 UIViewController+LaunchUverseEnabledEngagement Category ....................................................... 5

5 RemoteControlViewController Design ............................................................................................. 6

5.1 Implementing the viewDidLoad Method .................................................................................. 6

5.2 Implementing the UverseConnectedManagerDidChangeState Notification Callback Method ... 8

5.3 Implementing the connectToReceiverOrStartDiscovery Method ............................................ 11

5.4 About the UverseConnectedManagerErrorOccurred Notification Callback Method ................ 12

5.5 Handling the RemoteKey and Button Commands on the RemoteControlViewController ........ 12

6 SetTopBoxPickerTableViewController Design ................................................................................. 15

6.1 Implementing the viewDidLoad Method ................................................................................ 15

6.2 Implementing the registerForNotifications Method................................................................ 16

6.3 Implementing the uveSetTopBoxEnagagementDidSucceed notification Callback Method ...... 17

6.4 Implementing the uveSetTopBoxEnagagementDidFail Notification Callback Method ............. 17

6.5 Implementing the UverseConnectedManagerSetTopBoxesUpdated Notification Callback

Method ............................................................................................................................................. 19

6.6 Implementing the setupListOfstb Method .............................................................................. 19

6.7 Implementing the UITableView:cellForRowAtIndexPath Method ........................................... 21

6.8 Implementing the didSelectRowAtIndexPath Method ............................................................ 22

7 PasswordViewController Design .................................................................................................... 25

7.1 Implementing the viewDidLoad Method ................................................................................ 25

Table of Figures


iii

Figure 4-1: The RemoteControlViewController screen. ............................................................................ 6

Figure 5-1: SetTopBoxPickerTableViewController. ................................................................................. 15

Figure 6-1: PasswordViewController. ..................................................................................................... 25

Table of Examples


iv

Example 4-1: viewDidLoad method.......................................................................................................... 8

Example 4-2: UverseConnectedManagerDidChangeState. ..................................................................... 10

Example 4-3: engageToSTBAfterDiscovery. ............................................................................................ 11

Example 4-4: connectToReceiver. .......................................................................................................... 11

Example 4-5: stbCommandbuttonPressed. ............................................................................................ 13

Example 4-6: commandSucceeded. ....................................................................................................... 14

Example 5-1: viewDidLoad. .................................................................................................................... 16

Example 5-2: registerForNotifications. ................................................................................................... 17

Example 5-3: uveSetTopBoxEnagagementDidSucceed. .......................................................................... 17

Example 5-4: uveSetTopBoxEnagagementDidFail notification. ............................................................... 19

Example 5-5: UverseConnectedManagerSetTopBoxesUpdated. ............................................................. 19

Example 5-6: setupListOfstb. ................................................................................................................. 20

Example 5-7: UITableView:cellForRowAtIndexPath. ............................................................................... 22

Example 5-8: didSelectRowAtIndexPath. ............................................................................................... 24

Example 6-1: viewDidLoad. .................................................................................................................... 26

Example 5-9: PasswordViewController. ................................................................................................. 27

Example 6-2: passwordEntered. ............................................................................................................ 28

Example 6-3: shouldChangeCharactersInRange:replacementString:....................................................... 30


Page 1 of 30

1 Introduction

This document takes you through the creation of the elements that must be included in a functional U-verse Enabled app. These elements include a discovery and authentication process similar to that described in the U-verse Enabled User Device Guidelines document, which establishes the connection between your app and the U-verse receiver (set-top box), and a basic remote control that allows your app to invoke receiver commands. The code that is shown and discussed in this document is available for download from the U-verse Enabled iOS Sample Code page.

The main body of the sample app described in this document primarily focuses on the authentication, discovery and receiver selection processes. This portion of the sample app has been designed to be as reusable as possible and similar functionality must be included in every U-verse Enabled application.

Some of the terminology that is used in the U-verse APIs, and in this document, is different from the terms used on the U-verse receiver and in AT&T U-verse Support. The main differences are:

The U-verse receiver is referred to as the SetTopBox.

Default mode is referred to as "Open" mode for the receiver engagement.

Custom mode is referred to as "Managed" mode for the receiver engagement.

To complete this tutorial and create your first U-verse Enabled iOS app, it is assumed that you have completed the following prerequisites:

You have completed your app registration and have been issued an AAP for test purposes. The process for completing both of these tasks is described in the document How to Register and Start Developing for U-verse Enabled.

You have set up your project as described in the document How to Set Up a U-verse-Enabled Project in Xcode®.

https://developer.att.com/static-assets/documents/u-verse-enabled/develop/att-uverse-enabled-guidelines-for-user-devices.pdf

https://developer.att.com/static-assets/documents/u-verse-enabled/develop/att-uverse-enabled-guidelines-for-user-devices.pdf

https://developer.att.com/apis/u-verse-enabled/develop/ios/sample-code

https://developer.att.com/apis/u-verse-enabled/develop/ios/sample-code

https://developer.att.com/static-assets/documents/u-verse-enabled/start/how-to-register-and-start-developing-for-uverse-enabled.pdf

https://developer.att.com/static-assets/documents/u-verse-enabled/start/how-to-register-and-start-developing-for-uverse-enabled.pdf

https://developer.att.com/static-assets/documents/u-verse-enabled/develop/ios/how-to-set-up-a-uverse-enabled-project-in-xcode-ios.pdf

https://developer.att.com/static-assets/documents/u-verse-enabled/develop/ios/how-to-set-up-a-uverse-enabled-project-in-xcode-ios.pdf


Page 2 of 30

2 Overview

To implement the discovery, authentication, and remote control elements that are essential to a functional U-verse Enabled app, the project described in this tutorial uses these three objects in the U-verse Enabled SDK:

The SetTopBox object contains state information, such as the current

program that the user is watching. The object also contains methods for sending commands to the SetTopBox, querying for information about the current program or the user’s recording status, and for engaging with the SetTopBox.

UverseConnectedManager Is a singleton object used to manage all the

communication between your app, the U-verse Network Service and the U-verse receivers on the local network. The UverseConnectedManager is created by calling [UverseConnectedManager sharedManager], and it is kept alive for the lifetime of the app. The UverseConnectedManager object handles discovery of the U-verse receivers on the network and has a number of helpful properties such as SetTopBoxes which returns an

NSArray of the SetTopBox objects on the current network after discovery has completed. The property mostRecentlyEngagedSetTopBox provides a reference to the U-verse receiver that the user most recently engaged with. If they are not currently engaged this will point to the last receiver that they engaged with. If they are currently engaged it will point to the current receiver as that is the most recent. This is used for two purposes in the application:

After launch it is checked to see if it contains a value. If it is not nil, it will contain a reference to the SetTopBox that the user of the application had previously engaged with, and this SetTopBox is automatically engaged with, allowing the user to start using the application without having to select a receiver to engage with each time on launch.

It is used as a reference to the currently engaged SetTopBox when the user is engaged with a SetTopBox. This property will be updated automatically by the UverseConnectedManager if the user changes the U-verse receiver they are using in a multi-receiver network.

The uveRemoteButtonCommand object is used to send RemoteKey

commands to the SetTopBox. These commands are used to emulate buttons on the remote control (like channel up), or to send alphanumeric characters.

The structure of this project also contains two UIStoryboards:

The main storyboard, RemoteControlViewController, is used to create

the main screen. This view controller is embedded in a navigation controller, which is the root view controller for the app. It displays a simple


Page 3 of 30

remote control interface using default iOS buttons to demonstrate the functionality of the uveRemoteKeyCommand, and to handle discovery and control of a U-verse receiver.

In addition to one view controller, the main storyboard includes the UIViewController+LaunchUverseEnabledEngagement category, which contains methods for launching the engagementFlow storyboard and a UIView overlay to signal a long-running task such as discovery. The reason these methods are placed in a category is to enable them to be called from all of the UIViewControllers in the app, without the need to repeat the code in each UIViewController.

The engagementFlow storyboard and its view controllers handle the flow

when a user selects a U-verse receiver from a list of the available receivers, PIN entry if the receiver is in Custom (managed) mode, and help screens to assist the user when setting up U-verse receivers for use with U-verse Enabled Applications.

This storyboard contains three view Controllers:

o The SetTopBoxPickerTableViewController handles the selection and engagement of a receiver on the local network. This is done automatically in the discovery phase, or as a user event if the user wishes to change the receiver they are engaged with.

o The LinkingInfoViewController is the simplest view controller in

the project. Its role is to help the user with the steps to engage a receiver with a U-verse Enabled application. Details for implementing this view controller will not be explained in this tutorial, but the details are included in the accompanying sample code.

o The PasswordViewController is used to prompt the user for a PIN. The controller then passes the entered password to its delegate for verification.

The SetTopBoxPickerTableViewController presents the user with the list of U-verse receivers available on the local network. The other view controllers are normally presented to the user only on first-time setup.


Page 4 of 30

3 Initial Setup

Before your app can send commands to a U-verse receiver or use the TV UI API to draw content on the TV screen, its startup process includes the following elements:

The Discovery process includes multiple processes, with the most important being a scan for available U-verse receivers on the local network and authentication of your app with the U-verse Enabled network service.

o Any U-verse Receivers discovered on the local network are added to the SetTopBoxes property of the UverseConnectedManager. When the Discovery process is successfully completed, the DiscoveryState will be LibraryReady, and the user may then select a receiver to engage with.

o The authentication process checks whether the app is approved for the U-verse Enabled environment, including its version and App Bundle Identifier. AAP bundles are valid only for a specific environment, either test or production. If your app is operating in the production environment, its version is also checked using its CFBundleShortVersionString, which is its build number in Xcode. If the version you register in the U-verse Enabled onboarding tool does not match exactly, your app will not complete Discovery successfully, and the library will return a 3002 error (uveApplicationBlocked).

After the app successfully completes Discovery, the library is placed in the LibraryReady DiscoveryState and the user can start communicating with a U-verse Receiver. Your app can engage with a receiver in two ways:

o Your app may present a list of U-verse receivers on the local network that are in the default or custom mode, and let the user select the receiver to engage with. The user should be able to easily access this list at any time to change the engaged receiver.

o Your app may also check for the mostRecentlyEngagedSetTopBox property of the UverseConnectedManager. The mostRecentlyEngagedSetTopBox property persists across app launches, will contain the last engaged U-verse receiver. You can use this property to engage with the previous receiver on launch, enabling the user to use the receiver without requiring setup every time the app is launched. The sample code includes this check. The first time the app is launched on a device, this property will be nil.


Page 5 of 30

4 UIViewController+LaunchUverseEnabledEngagement Category

The sample code includes a category on UIViewController which contains four commonly used methods:

launchUVEEngagement – This method loads the engagementFlow storyboard into memory, instantiates the initial view controller for this storyboard, the SetTopBoxPickerTableViewController, and displays it on screen

launchSpinnerWithTitle:andInfo – This method displays an activity view on the screen when a potentially long-running task is being performed by the library.

launchSpinnerForDiscovery – This method calls the launchSpinnnerWithTitle:andInfo: method with a title equal to “Please Wait” and the infoLabel equal to “Discovering Network.”

removeSpinner – This method will remove the activity view from the device screen.

These are relatively short methods that can be called from different areas of the project. Placing these methods within a UIViewController category reduces the view controller code used in this project to just one instance, thus also reducing code maintenance.


Page 6 of 30

5 RemoteControlViewController Design

The RemoteControlViewController is embedded within the

UINavigationController, the root view controller for the app. This controller is used to create the main screen of the app.

Note: The default View is very basic and not intended to be used in a production

app. Instead, it should be replaced with a custom View in your app.

Figure 5-1: The RemoteControlViewController screen.

5.1 Implementing the viewDidLoad Method

The code to implement the RemoteControlViewController begins with the viewDidLoad method which performs the following actions:

Retrieving a reference to the sharedManager from the UverseConnectedManager object.

Registering for the notifications uveSetTopBoxCommandDidSucceed, uveSetTopBoxCommandDidFail, UverseConnectedManagerDidChangeState, and UverseConnectedManagerErrorOccurred.

This is the bare minimum set of notifications that you need to register for in order to create a functional U-verse app. The UverseConnectedManagerDidChangeState notification is used for the changes in discovery state, but it can also inform you of any state changes that occur after discovery. For example, it will notify you if the app loses the


Page 7 of 30

network connection to the U-verse receiver. In the sample code, registration for NSNotifications is handled by the registerForNotifications method.

Checking the state of the UverseConnectedManager (using the reference uvcMgr in the code example).

If the state is LibraryNotReady, then discovery is started with the command startDiscovery.

Checking whether the discovery state is not LibraryReady. While this condition is similar to the last check, the subtle difference is that it is checking whether the state is LibraryNotReady, or DiscoveringNetwork. These are the states that the app can be in before it is ready to use. If it is in one of these states, the code displays an alert to the user indicating that the app is performing discovery.

Sets up a UITapGestureRecognizer to handle the dismissal of the Program Info View, if it is displayed on the screen. The Program Info View appears on the screen with information about the currently viewed program, and other programs available by using the Channel-Up and Channel-Down buttons.


Page 8 of 30

The following code shows the implementation of the viewDidLoad method.

viewDidLoad

1 | - (void)viewDidLoad

2 | {

3 | [super viewDidLoad];

3 | self.edgesForExtendedLayout = UIRectEdgeNone;

4 | UverseConnectedManager *uvcMgr = [UverseConnectedManager sharedManager];

5 | [self registerForNotifications];

6 | if(uvcMgr.state == LibraryNotReady){

7 | [uvcMgr startDiscovery];

8 | }

9 | if (uvcMgr.state != LibraryReady){

10 | [self launchSpinnerForDiscovery];

11 |

12 | }

13 | UITapGestureRecognizer *singleTap = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(handleSingleTap:)];

14 | singleTap.delegate = self;

15 | [self.view addGestureRecognizer:singleTap];

16 | [self hideInfoView:nil];

17 | }

Example 5-1: viewDidLoad method.

5.2 Implementing the UverseConnectedManagerDidChangeState Notification Callback Method

The next method for implementing the RemoteControlViewController is the callback for the UverseConnectedManagerDidChangeState notification. This method handles the state changes of the UverseConnectedManager during discovery.

The UverseConnectedManager can be in one of three possible states:

LibraryNotReady

This is the initial state of the library. When the app starts it will be in LibraryNotReady. The library can be returned to LibraryNotReady after discovery if there is an error in Discovery. You can listen for the notification UverseConnectedManagerErrorOccurred to be notified of any errors that occur.

DiscoveringNetwork


Page 9 of 30

This is a transient state while the Library performs discovery. Discovery will search for the U-verse receivers on the same local Wi-Fi network as the iOS Device.

LibraryReady

The LibraryReady state is when you are able to interact with the library. All the setup has completed and the next step is to engage with a U-verse receiver. After you engage with a U-verse receiver, you will then be able to interact with that U-verse receiver.

The most important of these states is the LibraryReady state, which indicates that the library is set up and ready for use. The method removes the alert from the screen and then calls the engageToSTBAfterDiscovery method.

UverseConnectedManagerDidChangeState

1 | -(void)uveMgrDidChangeState:(NSNotification *)notification{

2 |


4 |

5 | switch(uvcMgr.state) {

6 | case LibraryReady:{

7 |

8 | [self removeSpinner];

9 | // this is a special case for handling an 4016 (uveModeChanged) error.

10 | If (self.connectionModeDidChange){

11 | self.connectionModeDidChange = NO; [self luanchUVEEngagement]; } else {

11 | [self engageToSTBAfterDiscovery];

12 | }

13 | break;

14 | }

15 | case LibraryNotReady:{


17 | self.spinnerView = nil;

18 | NSLog(@"NOTIFICATION UverseConnectedManagerDidChangeState: LibraryNotReady");

19 | break;

20 | }


Page 10 of 30

21 | case DiscoveringNetwork:{

22 | NSLog(@"NOTIFICATION UverseConnectedManagerDidChangeState: DiscoveringNetwork");

23 | UILabel *infoLabel = self.spinnerView.infoLabel;

24 | infoLabel.text = @"Discovering Network";

25 | break;

26 | }

27 }

28 | }

Example 5-2: UverseConnectedManagerDidChangeState.

The engageToSTBAfterDiscovery method is where the majority of the work will

be done after discovery. The method performs the following actions:

Checking whether the mostRecentlyEngagedSetTopBox property of the UverseConnectedManager singleton is set. If this property is not nil, we know that the user has previously engaged with the receiver.

Determining the mode of operation of the receiver. The reason for this is as follows: if the receiver is in Default mode, or in Custom mode and the user has previously entered the four-digit passcode for this application, you are able to engage with the receiver without sending the four-digit passcode to the U-verse receiver. The four-digit passcode must be entered by the user if this is the first use of this U-verse Enabled app and the U-verse receiver, and if the receiver they are engaging with is in Custom (Managed) mode. This would be the most common use case in a household that has only one receiver. When the app launches and goes through the discovery process, the user does not need to select a receiver to interact with. This can be done by either calling the engage

method on a SetTopBox or by calling the associatedAndEngageWithOneTimeToken with an argument of nil.

The following code shows the implementation of the engageToSTBAfterDiscovery method.

engageToSTBAfterDiscovery

1 | -(void)engageToSTBAfterDiscovery{


3 | SetTopBox *lastUsedSTB = uvcMgr.mostRecentlyEngagedSetTopBox;

4 | BOOL shouldAttemptToAutomaticlyEngage = lastUsedSTB != nil && (lastUsedSTB.mode == UverseModeOpen || (lastUsedSTB.mode == UverseModeManaged && lastUsedSTB.isAssociated));


Page 11 of 30

5 | if (shouldAttemptToAutomaticlyEngage){

6 | [lastUsedSTB associateAndEngageWithOneTimeToken:nil];

7 | self.title = uvcMgr.mostRecentlyEngagedSetTopBox.friendlyName;

11 | } else {

12 | [self launchUVEEngagement];

13 | }

14 | }

Example 5-3: engageToSTBAfterDiscovery.

5.3 Implementing the connectToReceiverOrStartDiscovery Method

The following code example shows the connectToReceiverOrStartDiscovery method, where a View Controller (SettopBoxPickerTableViewController) is

launched so the user can select the receiver that they wish to connect to, and if necessary, launch the passcode entry screen. The View Controller is embedded in a UINavigationController for easier management of the UINavigationBar and so that it can be presented modally.

connectToReceiver

1 | -(IBAction)connectToReceiverOrStartDiscovery{


3 | if (uvcMgr.state == LibraryReady && uvcMgr.SetTopBoxes != nil){


5 | [self launchUVEEngagementFlow];

9 | } else if (uvcMgr.state == LibraryNotReady) {

[self launchSpinnerForDiscovery];

10 | [uvcMgr startDiscovery];

11 | } else {

12 | // if the middle of Discovery

13 | }

14 | }

Example 5-4: connectToReceiver.


Page 12 of 30

5.4 About the UverseConnectedManagerErrorOccurred Notification Callback Method

The callback method that handles the UverseConnectedManagerErrorOccurred notification covers any errors that may occur while the app is running. When you are first creating a U-verse Enabled project, the most common errors that you will receive are:

uveInternalError (3000) - This normally occurs if there is a problem with the AAP bundle that you used, e.g., you are using the wrong AAP for the environment.

uveNetworkError (3001) - This error occurs when your app has a problem communicating with the server. The most common cause of this error is a network error; it can also occur if you set the server to the wrong URL.

uveApplicationBlocked (3002) - This occurs when either the app bundle identifier or the build number of the app have not been registered with AT&T.

The code for this callback method is not described here, but the implementation is in the sample code of the project.

5.5 Handling the RemoteKey and Button Commands on the RemoteControlViewController

The view of the RemoteControlViewController (shown in figure 1) displays a

navigation bar with a bar button (labeled “Connect”) on the right, to start the authentication process. The remainder of the view controller contains the remote control buttons.

The view controller is split into two sections, the top section, which contains the basic buttons necessary for navigation through any U-verse app and through the menu system on the SetTopBox, and the lower section which contains a number pad and a few extra buttons.

Each of the RemoteKeys is exposed by the SDK in an enum contained in the file RemoteKey.h. The easiest way to send a command to the SetTopBox is to set the tag property of a button to the value of that button in the RemoteKey.h file.

For example, the up button on the directional pad has the value of 24. By passing RemoteKey values to an action method, the same action method can be reused for each RemoteKey. The stbCommandbuttonPressed method, shown in the following code snippet, uses this technique.

The method performs these actions:


Page 13 of 30

Casting the sender to a UIButton so that the compiler will not give a warning when the tag property of the object is accessed.

Creating the command object which is of type uveRemoteButtonCommand. This is the object that is used anytime you are sending a remote Control Button to the receiver, i.e., any of the Remote keys declared in RemoteKey.h file.

Sending the command to the receiver and releasing the command.

stbCommandbuttonPressed

1 | - (IBAction)stbCommandbuttonPressed:(id)sender{

2 | UIButton *button = (UIButton *)sender;

3 | uveRemoteButtonCommand *buttonCommand =[[uveRemoteButtonCommand alloc] initWithRemoteKey:button.tag];

4 |

5 | [[[UverseConnectedManager sharedManager] mostRecentlyEngagedSetTopBox] sendSetTopBoxCommand:buttonCommand];

6 |

7 | }

Example 5-5: stbCommandbuttonPressed.

As the command object will not contain any information that will be returned, it is safe to release the object after it has been sent. However, this is different for some of the other commands that inherit from uveBaseCommand. For example, the uveRecordingsCommand includes the array of recordings as a property called recordings on the uveRecordingCommand, so you must have a reference to the command so that you can access the recordings property in the

callback to the uveSetTopBoxCommandDidSucceed notification.

All commands that are sent to the receiver are asynchronous, so you will need to listen for the uveSetTopBoxCommandDidSucceed and uveSetTopBoxCommandDidFail notifications to determine the success or failure of the command. As all commands that inherit from uveBaseCommand will send

the same notification, the first step is to find out what type of command has sent the notification. This can be queried from the uveSetTopBoxCommandKey key

that is passed as a parameter in the notification object.

The following code shows the commandSucceeded method which is the callback for the uveSetTopBoxCommandDidSucceed notification.


Page 14 of 30

commandSucceeded

1 | -(void)commandSucceeded:(NSNotification *)notification {

2 | uveBaseCommand *baseCommand = (uveBaseCommand *)[notification objectForKey:uveSetTopBoxCommandKey];

3 | if ([baseCommand isKindOfClass:[uveRecordingsCommand class]]){

4 | uveRecordingCommand *recordingsCommand = (uveRecording *)baseCommand;

5 | // handle for uveRecordingCommand

6 |

7 | } else if ([baseCommand isKindOfClass:[uveRemoteKeyCommand class]]){

8 | // handle for uveRemoteKeyCommand

9 | }

Example 5-6: commandSucceeded.


Page 15 of 30

6 SetTopBoxPickerTableViewController Design

The purpose of the SetTopBoxPickerTableViewController, which inherits from UITableViewController, is to display a list of the SetTopBoxes that the user has on their local network. The list will include any SetTopBoxes that are in Default mode (those that do not require a passcode to engage), or Custom mode (those that require the user to enter a passcode on first time engagement). If there are any SetTopBoxes in UverseModeUnknown, it means that the user has not yet enabled the U-verse Enabled features on those U-verse receivers. The user is also able to disable the U-verse Enabled functionality on a U-verse receiver. In this case the U-verse receiver will be in Closed Mode.

To handle the case of receivers in Closed or Unknown mode, an extra row in the tableview is displayed with the text “Add New Receiver”, and a new view controller with instructions for the user on how to enable the U-verse Enabled features on their SetTopBox. If there are any receivers in UverseModeClosed or UverseModeUnknown, , it should not be displayed in the list, and instead the Add New Receiver” cell should be displayed .

Figure 6-1: SetTopBoxPickerTableViewController.


The viewDidLoad method performs the following actions:


Page 16 of 30

Setting up the UINavigationBar with a title (“Receivers”) and a button that allows the user to cancel out of the Model view and go back to the main viewController for the app (the RemoteControlViewController).

Calling the registerForNotifications method which registers for the Notifications necessary to handle the engagement process.

Calling the setupListOfstb method. This method prepares the model (a

list of SetTopBoxes) that the tableview will use.


viewDidLoad

1 | - (void)viewDidLoad

2 | {


4 | [self registerForNotifications];

5 | self.title = @"Receivers";

6 | [self setupListOfstb];

7 | }

Example 6-1: viewDidLoad.

6.2 Implementing the registerForNotifications Method

The following code shows the implementation of the registerForNotifications method that is called from viewDidLoad of the SetTopBoxPickerTableViewController. In the registerForNotifications

method, the two notifications that you will need to observe are uveSetTopBoxEngagementDidFail and uveSetTopBoxEngagementDidSucceed. With the update to fast discovery caching with the 3.0 library, you should now also listen for the UverseConnectedManagerSetTopBoxUpdated notification, which will informed you that the property SetTopBoxes on the UverseConnectedManager has been updated.

registerForNotifications

1 | -(void)registerForNotifications

2 | {

3 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(uvcSTBAssociationDidFail:) name: uveSetTopBoxEngagementDidFail object:nil];

4 | [[NSNotificationCenter defaultCenter] addObserver:self


Page 17 of 30

selector:@selector(uvcSTBAssociationDidSucceed:) name: uveSetTopBoxEngagementDidSucceed object:nil];

5 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(uvcMgrErrorOcurred:) name: UverseConnectedManagerErrorOccurred object:nil];

6 |

7 | [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(uveMgrSetTopBoxesUpdated:) name:UverseConnectedManagerSetTopBoxesUpdated object:nil];

11 | }

Example 6-2: registerForNotifications.

6.3 Implementing the uveSetTopBoxEnagagementDidSucceed notification Callback Method

The callback for uveSetTopBoxEngagementDidSucceed removes the network activity view from the display and then performs an exit segue, walking up the stack of view controllers in memory until a view controller handles this segue, and then pops to the view controller which handles this method.

uveSetTopBoxEnagagementDidSucceed

1 | -(void)uvcSTBAssociationDidSucceed:(NSNotification *)notification

2 | {

3 | [self.navigationController.visibleViewController removeSpinner];

4 |

[self.navigationController.visibleViewController performSegueWithIdentifier:@"exit"

5 | }

Example 6-3: uveSetTopBoxEnagagementDidSucceed.

6.4 Implementing the uveSetTopBoxEnagagementDidFail Notification Callback Method

The following code demonstrates error cases from the uveSetTopBoxEngagementDidFail notification:

The uveNonceRequired error informs your app that the user must enter the four-digit passcode, and then the app must engage with this passcode. In the example, the pushPasswordEntry segue will be performed to launch the PasswordViewController to handle the password entry from the user.


Page 18 of 30

The uveSetTopBoxProtocolError is caused when an app built for the ZDEV environment attempts to authenticate a receiver on the U-verse Enabled Channel (9301), or when an app built for production attempts to authenticate a receiver on the U-verse Enabled Developer Test Channel (9315).

On U-verse receivers with a U-verse Enabled Developer Test Channel, both of these U-verse Enabled management channels are available. The receiver always tries to authenticate with the last of these two channels to be launched, and the uveSetTopBoxProtocolError is triggered when an app built for one environment engages with a receiver on which the other channel was the last launched. If you encounter this error with an ZDEV app, launch the Developer Test Channel and re-launch the app. If you encounter this error with a production app, launch the U-verse Enabled channel and then re-launch the app.

Regular U-verse users will never encounter this issue, as their U-verse receivers only have access to the regular U-verse Enabled Channel.

uveSetTopBoxEnagagementDidFail notification

1 | -(void)uvcSTBAssociationDidFail:(NSNotification *)notification{

2 | NSDictionary *userInfo = [notification userInfo];

3 | NSError *error = [userInfo objectForKey:UverseConnectedManagerErrorKey];

4 | switch (error.code) {

5 | case uveNonceRequired:

6 | NSLog(@"NOTIFICATION uvcSetTopBoxAssociationDidFail:uveNonceRequired");

7 | [self performSegueWithIdentifier:@"pushPasswordEntry" sender:self.currentSTB];

8 | break;

9 | case uveNotOnSubscriberNetwork:

10 | NSLog(@"NOTIFICATION uvcSetTopBoxAssociationDidFail:uvcNotOnSubscriberNetwork");

11 | errorString = [NSString stringWithFormat:@"ERROR %ld: %@",(long) error.code, error.description];

12 | break;

13 |

14 | case uveSetTopBoxProtocolError:{

15 | NSLog(@"NOTIFICATION uvcSetTopBoxAssociationDidFail: uveSetTopBoxProtocolError");

16 | errorString = @"A common cause of the uveSetTopBoxProtocolError is using a U-verse receiver with both the U-verse Enabled Channel (9301) and the U-verse Enabled Developer Test Channel (9315). If you are using a ZDEV AAP Bundle,


Page 19 of 30

channel 9315 must be the last channel to be launched, and for running apps with a production AAP bundle, channel 9301 must be the last to be launched";

17 | break;

18 |

19 case uveNotOnAUverseNetwork:

20 NSLog(@"NOTIFICATION uvcSetTopBoxAssociationDidFail:uvcNotOnAUverseNetwork");

21 errorString = @”Not on a U-verse Network. There were no U-verse Receivers found during discovery. Please check that you are on the same network as a U-verse Receiver.

22 break;

23

24 |

25 |

Example 6-4: uveSetTopBoxEnagagementDidFail notification.

6.5 Implementing the UverseConnectedManagerSetTopBoxesUpdated Notification Callback Method

The callback for UverseConnectedManagerSetTopBoxesUpdated (shown here) simply calls the setupListOfstb method (described in the next section).

UverseConnectedManagerSetTopBoxesUpdated

1 | -(void)uveMgrSetTopBoxesUpdated:(NSNotification *)notification

2 | {

3 | [self setupListOfstb];

4 | }

Example 6-5: UverseConnectedManagerSetTopBoxesUpdated.

6.6 Implementing the setupListOfstb Method

The setupListOfstb method performs the following actions:

Sets the unknownSTBs flag to NO.

Clears the list of SetTopBoxes.

Enumerates through the NSArray of the UverseConnectedManager property SetTopBoxes, and adds any SetTopBoxes that are in the open (UverseModeOpen) or managed (UverseModeManaged ) modes to the


Page 20 of 30

list that will be displayed in the tableView. If any SetTopBoxes are in the UverseModeUnknowns state, the unknownSTBs flag will be set to YES.

Sorts the list in alphabetical order.

The following code shows the implementation of the setupListOfstb method.

setupListOfstb

1 | -(void)setupListOfstb{

2 | unknownSTBs = NO;


4 | [self.list removeAllObjects];

5 | for (SetTopBox *stb in [uvcMgr SetTopBoxes]){

6 |

7 | switch (stb.mode) {

8 | // if the mode is open or managed, add the stb to the list of the U-verse receivers to display

9 | case UverseModeOpen:

10 | case UverseModeManaged:

11 | [self.list addObject:stb];

12 | break;

13 | case UverseModeUnknown:

14 | unknownSTBs = YES;

15 | break;

16 | case UverseModeClosed:

17 | break;

18 | default:

19 | break;

20 | }

21 | }

22 | [self.list sortedArrayUsingComparator:^(SetTopBox *first, SetTopBox *second){

23 | return [first.friendlyName localizedCaseInsensitiveCompare:second.friendlyName];

24 | }];

25 | }

Example 6-6: setupListOfstb.


Page 21 of 30

6.7 Implementing the UITableView:cellForRowAtIndexPath Method

The UITableView:cellForRowAtIndexPath: method, shown in the following code, begins by setting up a new cell.

The method then contains the condition if (indexPath.row < [self.list count]) which checks whether the row should be for an Open or managed SetTopBox on the local network, and if this condition fails, a row is displayed at the end of the tableview for “Add New Receiver”. If the condition is true, the cell is built by first getting a reference to the SetTopBox for the row and setting the name of the SetTopBox as the main text of the cell.

Within this condition there is a check to see whether the SetTopBox is in UverseModeManaged mode. If it is, the row’s image is set to be an open lock if the SetTopBox has previously been engaged or if it is currently engaged. This means that the user will not need to enter the four-digit passcode when they engage with the receiver. The isAssociated property of the SetTopBox will return YES if the user has previously entered the four-digit passcode for this U-verse Enabled app. If the U-verse receiver is in managed mode and the isAssociated property returns YES for the device and app, the user does not need to enter the four-digit passcode again. If the isAssociated property returns NO, the user will need to enter the four-digit passcode before they can engage with the U-verse receiver, and the row’s image is set to be a closed lock to indicate that the user will need to enter the four-digit passcode before using this SetTopBox.

The final check inside this condition checks to see whether the SetTopBox is currently engaged. If it is engaged, an imageView is set to display a checkmark, otherwise, it is left blank.

UITableView:cellForRowAtIndexPath

1 | - (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath

2 | {

3 | static NSString *CellIdentifier = @"stbCell";

4 | stbCell *cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier];

5 |

6 | if (indexPath.row < [self.list count] ){

7 |

8 | // Configure the cell...

9 | SetTopBox *listSTB = [self.list objectAtIndex:indexPath.row];

10 | // set up the name


Page 22 of 30

11 | cell.textLabel.text = listSTB.friendlyName;

12 |

13 | // check whether to display the lock

14 | if (listSTB.mode = UverseModeManaged){

15 | if (listSTB.isAssociated || listSTB.isEngaged){

16 | cell.lockImage.image = [UIImage imageNamed:@"PairingUnlock.png"];

17 | } else {

18 | cell.lockImage.image = [UIImage imageNamed:@"PairingLock.png"];

19 | }

20 | }

21 |

22 | if (listSTB.isEngaged && listSTB == [UverseConnectedManager sharedManager].mostRecentlyEngagedSetTopBox){

23 | cell.imageView.image = [UIImage imageNamed:@”PairingCheck.png”];

24 | } else {

Cell.imageView.image = nil;

25 | cell.accessoryView = nil;

26 | cell.accessoryType = UITableViewCellAccessoryNone;

27 | }

28 | } else {

29 | cell.textLabel.textColor = [UIColor blueColor];

30 | cell.textLabel.text = @"Add New Receiver...";

31 | }

32 | return cell;

33 | }

Example 6-7: UITableView:cellForRowAtIndexPath.

6.8 Implementing the didSelectRowAtIndexPath Method

The didSelectRowAtIndexPath method, shown in the following code, tests the

mode of the selected SetTopBox to see whether it is open or engaged.

The method contains a main test that checks whether the row is less than the size of the list. If this is true, it indicates that the item is a SetTopBox. If this condition fails, the flow for engaging a new SetTopBox is started by calling the displayLinkingInfoController method.


Page 23 of 30

Inside this branch, the mode of the SetTopBox is checked. If the SetTopBox is in the UverseModeOpen mode, it will be engaged and the app will return to the main view Controller.

If the SetTopBox is in the UverseModeManaged mode, the method checks whether the SetTopBox has previously been engaged, by checking the isAssociated property of the SetTopBox. If it has been, it will engage again and the app will return to the main screen. If this condition fails, a new view controller will be displayed for the user to enter the passcode and connect with the SetTopBox.

didSelectRowAtIndexPath

1 | -(void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath

2 | {

3 | [self.tableView deselectRowAtIndexPath:indexPath animated:YES];

4 | if (indexPath.row < [self.list count]) {

5 | SetTopBox *selectedSTB = [self.list objectAtIndex:indexPath.row];

6 | switch (selectedSTB.mode) {

7 | case UverseModeOpen:{

8 | [selectedSTB engage];

9 | [self launchSpinnerWithTitle:@"Engaging" andInfo:[NSString stringWithFormat:@"Engaging with %@",selectedSTB.friendlyName]];

10 | break;

11 | case UverseModeManaged:{

12 | if (YES == self.currentSTB.isAssociated || YES == self.currentSTB.isEngaged) {

13 | [self.currentSTB engage];

14 | [self launchSpinnerWithTitle:@"Engaging" andInfo:[NSString stringWithFormat:@"Engaging with %@",selectedSTB.friendlyName]];

15 | } else {

16 | [self performSegueWithIdentifier:@"pushPasswordEntry" sender:selectedSTB];

17 | }

18 | break;

19 | }

20 | default:

21 | break;


Page 24 of 30

22 | } // END switch

23 | }else {

24 | [self performSegueWithIdentifier:@"pushEngageInfo" sender:selectedSTB];

25 | }

26 | }

Example 6-8: didSelectRowAtIndexPath.


Page 25 of 30

7 PasswordViewController Design

The purpose of the passwordViewController is to take a passcode entered by the user and use the passcode to engage with the U-verse receiver.

The design of this viewController uses a hidden text field that stores the passcode and captures the input from the keyboard. It then sets the digits into the text fields that are displayed to the users. It’s important to note that the passwordHiddenField is not setup as a property, because this variable must not be exposed outside of the class.

Figure 7-1: PasswordViewController.


The viewDidLoad method, performs the following actions:

Sets up the passwordHiddenField with a frame of CGRectZero, a zero sized rect.

Sets the delegate to be the PasswordViewController.

Sets the keyboard type to be the number pad.

Calls becomeFirstResponder so the keyboard will be displayed on load.

Sets up the title and a label with the name of the SetTopBox.


Page 26 of 30


viewDidLoad

1 | - (void)viewDidLoad {


3 |

4 | passwordHiddenField = [[UITextField alloc] initWithFrame:CGRectZero];

5 | passwordHiddenField.delegate = self;

6 | passwordHiddenField.keyboardType = UIKeyboardTypeNumberPad;

7 | passwordHiddenField.text = @"";

8 | [passwordHiddenField becomeFirstResponder];

9 | [self.view addSubview:passwordHiddenField];

10 |

11 |

12 | self.navigationItem.title = @”Enter Passcode");

13 | self.topLabel.text = [NSString stringWithFormat: @"Using your U-verse remote, tune to channel %d on receiver %@",[UverseConnectedManager sharedManager].UverseConnectedChannel, self.currentSTB.friendlyName];

14 | }

Example 7-1: viewDidLoad.

The view controller will listen for the uveSetTopBoxEngagementDidSucceed and the uveSetTopBoxEngagementDidFail notifications in the viewDidAppear. The callback for uveSetTopBoxEngagementDidSucceed is handled in uveSetTopBoxEngagementDidSucceed, which will remove the spinner view from the display and perform an exit segue which will return the user to the Remote Control view controller. The uveSetTopBoxEngagementDidFail notification is handled by the uveSetTopBoxEngagementDidFail method

The uveSetTopBoxEngagementDidFail method will first clear the text fields and remove the spinner view from the display, then handle the three possible passcode errors:

uveNonceAttemptedManyTimes – The user entered an incorrect passcode too many times and the system will disallow further attempts to engage with an U-verse receiver for a period of about fifteen minutes.

uveNonceExpired - The user attempted to enter a passcode which is no longer valid. In this case the app should instruct the user to return to the “Add a Device” page of the U-verse Enabled Channel and try again with the new passcode, which will appear on-screen.

uveNonceInvalid – The user entered the passcode incorrectly. The app should ask the user to re-enter the passcode.


Page 27 of 30

-(void)uveSetTopBoxEngagementDidFail:(NSNotification *)note

1 | -(void)uveSetTopBoxEngagementDidFail:(NSNotification *)note{

2 | passwordHiddenField.text = @"";

3 | self.passwordField0.text = nil;





8 |

9 | NSError *error = [[note userInfo] objectForKey:uveSetTopBoxErrorKey];

10 | NSLog(@ERROR: %@, error);

11 | NSString *msg = nil;

12 | switch (error.code){

13 | case uveNonceAttemptedTooManyTimes:

14 | msg = @"The passcode has been attempted too many times. Please try again after 15 minutes";

15 | break;

16 | case uveNonceExpired:

17 | msg = [NSString stringWithFormat: @"The passcode has expired. Please return to the \"Add a Device\" page on channel %d for a new passcode. If currently on the \"Add a Device\" screen, please leave the page and return to obtain a new passcode.", [UverseConnectedManager sharedManager].UverseConnectedChannel];

18 | break;

19 | case uveNonceInvalid:

20 | msg = @"The passcode is incorrect, please retry";

21 | break;

22 | default:

23 | break;

24 | }

25 | [[[UIAlertView alloc] initWithTitle:@"Passcode Error" message:msg delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil] show];

26 | }

Example 7-2: PasswordViewController.

The checkPassword method calls the checkPassword method of the delegate. passwordEntered is called when the user enters the four-digit passcode.


Page 28 of 30

checkPassword

1 | - (void)passwordEntered:(NSString *)password {

2 | //self.waitView = [[ProgressIndictator alloc]initWithTitleLabelText:@"Please Wait" andInfoLabelText:@"Checking Passcode"];

3 |

4 | if (self.delegate && [self.delegate respondsToSelector:@selector(passwordController:checkPassword:)]){

5 | [self.delegate passwordController:self checkPassword:password];

6 | }

7 | }

Example 7-3: passwordEntered.

The UITextFieldDelegate method shouldChangeCharactersInRange:replacementString: is used to update the

characters in the one character text fields on the screen. This method is the delegate for the UITextField called passwordHiddenField that was set in the viewDidLoad method.

The shouldChangeCharactersInRange:replacementString: method uses the

length of the characters in the passwordHiddenField, and then updates the four password test fields that are displayed to the user. After the user has entered four characters, the passwordEntered method is called.

shouldChangeCharactersInRange:replacementString:

1 | - (BOOL)textField:(UITextField *)textField shouldChangeCharactersInRange:(NSRange)range replacementString:(NSString *)string {

2 | NSString *password = [textField text];

3 | password = [password stringByReplacingCharactersInRange:range withString:string];

4 |

5 | switch ([password length]) {

6 | case 0:





11 | break;

12 | case 1:

13 | self.passwordField0.text = [password


Page 29 of 30

substringWithRange:NSMakeRange(0, 1)];




17 | break;

18 | case 2:

19 | self.passwordField0.text = [password substringWithRange:NSMakeRange(0, 1)];




23 | break;

24 | case 3:





29 | break;

30 | case 4:





35 |

36 | [self performSelector:@selector(passwordEntered:) withObject:password afterDelay:0];

37 |

38 | return NO;

39 |

40 | break;

41 | default:

42 | return NO;

43 | break;

44 | }

45 |


Page 30 of 30

46 | return YES;

47 |

48 | }

Example 7-4: shouldChangeCharactersInRange:replacementString:

AT&T U verse Enabled · included in a functional U-verse Enabled app. These elements include a...

Documents

Transcript of AT&T U verse Enabled · included in a functional U-verse Enabled app. These elements include a...