[This is preliminary documentation and subject to change.]
Broadcast Architecture defines a data format, the show reference, to describe a broadcast episode or episodes by using such information as the time and channel of the show and so on. A show reference is an ASCII string that contains multiple fields. Each field is separated from the next by an exclamation mark ( ! ).
The TSS object library provides methods that build a show reference from its constituent fields, that parse show references, and that build database queries from a show reference. These queries can then be run on the Guide database to return the collection of episodes to which the show reference refers.
The show reference methods are as follows:
The ITelevisionServices::MakeLocalBroadcastSchedule method builds a show reference where a show's channel number, tuning space, and station are known. The ITelevisionServices::MakeRemoteBroadcastSchedule method also builds a show reference but substitutes wildcard values for the channel number, tuning space, and station. Your application can call MakeLocalBroadcastSchedule if you are certain that all users are located in your local broadcast area. Otherwise, your application should call MakeRemoteBroadcastSchedule. When WebTV for Windows uses a show reference created by MakeRemoteBroadcastSchedule, it queries the user's Guide database to fill in the wildcard values with local broadcasting information.
Your application can access the information in a show reference, for example the episode title, by parsing the show reference. To parse show references, the TSS object library offers the ITelevisionServices::SplitBroadcastSchedule method, which splits a show reference into its constituent fields. SplitBroadcastSchedule returns a pointer to an ITaskTrigger interface that specifies time, date, and other task trigger properties, such as a schedule of how often a show task repeats. For example, a task initiating a show might run at 7 P.M. on the twenty-third day of every month starting 7/22/97. The ITelevisionServices::SplitSimpleBroadcastSchedule method performs the same service but returns time and date information as a Microsoft® Visual Basic® DATE variable instead of as an ITaskTrigger pointer. Although SplitSimpleBroadcastSchedule provides less information than SplitBroadcastSchedule, SplitSimpleBroadcastSchedule can be called by Visual Basic applications that cannot access ITaskTrigger. To locate more information about ITaskTrigger, see Further Information on Television Services for the Client.
The ITelevisionServices::ResolveBroadcast method generates a query from a show reference. By running this query on the Guide database, you can retrieve the episode or the list of episodes that match a particular show reference. This functionality is useful in situations where a reference refers to several episodes, which occurs if some of the reference's fields are wildcard values. For example, a show reference that specifies the time and title, but not the date, of a show can refer to all the weekly or monthly episodes of that show.
The ITelevisionServices::ResolveBroadcastInclusively method is identical in function to ResolveBroadcast except that it returns all episodes that match the show reference and that play during the specified time, instead of starting at the specified time.
The ITelevisionServices::ResolveScheduledReminders method returns a Data Access Objects (DAO) QueryDef query that generates a list of the show reminders scheduled. To locate more information on DAO, see Further General Information.
In addition, the TSS object library provides two methods, ITelevisionServices::TuningSpaceNameFromNumber and ITelevisionServices::TuningSpaceNumberFromName, which map the number of a tuning space in the Guide database to its human-readable name (for example cable, TV tuner, or satellite) and the reverse. Your application can use these methods to convert tuning space identifiers into device names to display a list of possible broadcast devices to the user. When the user has selected a device name, your application can call TuningSpaceNumberFromName to recover the tuning space in order to tune to a channel in that space or to reference the space in the Guide database.
For more information on working with show references, see the following topics: