Intro

The Beyond TV SDK is an amazingly powerful set of methods and web services that you can use to access, customize, and control every aspect of your Beyond TV server. Exciting scenarios include outputting the status of Beyond TV to an LCD display and writing an entire front-end for your digital media adapter or alternative OS using the SDK and Beyond TV as the server backend. The following is a brief description of how to get up and running with the SDK using Visual Studio .NET 2003. This may be old hat to some experienced developers, but for those of you who are new to web services or Visual Studio .NET in general, it should help to get you up and running in no time.

Setting up your solution and project

First, we're going to want to create a new solution. Click on the "File" menu option, highlight the "New" option, then click "Blank Solution".

The following dialog appears. Enter whatever name you want for the solution in the "Name" field. We used "BTVTutorial1" or "BTVSDKSample1". Click OK to continue.

Next, you will want to create a project inside this new solution. Right click on the newly created solution and choose "Add", followed by "New Project...".

The following dialog appears. Under "Project Types", select "Visual C# Projects". Under Templates, let's select "Console Application", which will create a simple console application that we will use to output the results of our method calls against the Beyond TV SDK. Enter a name in the "Name" field. We used "BTVSDKSample1". We're now ready to go, so click OK to continue.

Congratulations! You now have an empty solution and project which we will now setup for use with the Beyond TV SDK.

Adding references to the Beyond TV SDK web services

Next, we need to add references to the Beyond TV SDK web services. First of all, be sure that you are running a fully licensed and paid for copy of Beyond TV. Beyond TV must be running to add these references. For the purposes of this tutorial, we will assume you are accessing a Beyond TV server located on the local machine.

The first thing you need to know is that only the BTVLicenseManager.asmx web service is available at first. Once you log on, all the other web services become accessible. In order to add references in Visual Studio, you will need to logon with BTVLicenseManager.

The following assumes you are accessing Beyond TV locally and do not have security or a web admin password enabled. There are extra steps that have to be taken to develop against a remote server, which we do not get into here.

Enter the URL "http://localhost:8129/wsdl/BTVLicenseManager.asmx?op=Logon" into Internet Explorer. You should see a web service test page appear with a networkLicense field and a password field. Enter your product key into the networkLicense field. This tutorial assumes you do not have a password set on your web admin, so leave the password field blank and click the "Invoke" button. A blank page should appear, which indicates a successful logon.

OK, now we're ready to add our web references to Visual Studio. Expand the References item under the "BTVSDKSample1" project. Right-click on the References item and select "Add Web Reference...".

The following dialog appears. Enter "http://localhost:8129/wsdl/BTVLicenseManager.asmx" into the URL field and click "Go". Next, change the Web reference name field to "WebLicenseManager". Finally, click "Add Reference" to complete the process.

OK, we just added our first web reference. We need to add a couple more. Repeat the previous step, but use "http://localhost:8129/wsdl/BTVScheduler.asmx" for the URL and "WebScheduler" for the Web reference name. Then repeat the previous step again, but use "http://localhost:8129/wsdl/BTVDispatcher.asmx" for the URL and "WebDispatcher" for the Web reference name.

After all that, your Solution Explorer should look like this...with three new web references.

It gets a little tricky here now. Basically, each of these web references have been added...but under different namespaces, with separate, though actually identical, datatypes. We need to fix this.

Click on the "Show All Files" toolbar button, shown below.

Next, expand each web reference item completely, as shown below.

We want to edit the "Reference.cs" item of each web service. First, we need to change each namespace.

Under the WebLicenseManager Reference.cs, change the "BTVSDKSample1.WebLicenseManager" text to "BTVSDKSample1.BTVServer".

Under the WebScheduler Reference.cs, change the "BTVSDKSample1.WebScheduler" text to "BTVSDKSample1.BTVServer".

Under the WebDispatcher Reference.cs, change the "BTVSDKSample1.WebDispatcher" text to "BTVSDKSample1.BTVServer".

This puts all webservices under a single namespace.

[ Click to Enlarge ]

Next, we need to comment out or delete duplicate data types. Let's decide on using the data types in WebScheduler as where we want the definitions of our data types to be located. Now, as it happens, WebLicenseManager doesn't have any data types. But WebDispatcher does.

Under the WebDispatcher Reference.cs, scroll to the bottom and comment out the property bag data types as shown below.

[ Click to Enlarge ]

OK, that's it for the references. Now let's write some code!

Writing code

OK, here's a screenshot of a simple code sample that logs onto the server and dumps all upcoming recordings and active recordings. It's amazing how little code it takes, isn't it?

This code should be in your Class1.cs file of the project.

[ Click to Enlarge ]

Let's try to explain this a little further. In order to use the web services, you must log on with an authorized license to unlock the other services. You can use either a Beyond TV Link license or a full Beyond TV server license. You cannot use the server's license from anywhere except the local server.

Since this example assumes you're at the local machine, go ahead and put your product key in the license string, instead of that huge set of zeroes.

The remaining code is simple and just dumps upcoming recordings and active recordings to the console. The PVSProperty is a basic data type of the SDK that is simply a name string and a value string. The PVSPropertyBag is another simple type which is just an array of PVSProperty types. You'll use these extensively as you interact with the SDK.

Let's assume you've got all this code in the Class1.cs file of your project. Last, just right click on the "BTVSDKSample1" project and click build. If you typed everything in correctly, you'll have a working command line app that dumps all your upcoming recordings and active recordings. Hit "F5" on your keyboard to run the application. By the way, you aren't going to see anything if you don't actually have any upcoming recordings or active recordings, so make sure you add something there so you can see some output from your new program.

OK, that's your first taste of the Beyond TV SDK. There are several more web services and many more documented properties in the help documentation of the SDK. Be sure to read more there to keep going! Remember, Beyond TV puts the power in YOUR hands...and the community!

Discuss it in our forums.

Back to Community Page