Legal Information

[This is preliminary documentation and subject to change.]

Broadcast Architecture Programmer's Reference

This is a preliminary document and may be changed substantially prior to final commercial release. This document is provided for informational purposes only and Microsoft Corporation makes no warranties, either express or implied, in this document. The entire risk of the use or the results of the use of this document remains with the user. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, without the express written permission of Microsoft Corporation.

Portions of this document specify and accompany software that is still in development. Some of the information in this documentation may be inaccurate or may not be an accurate representation of the functionality of final documentation or software. Microsoft assumes no responsibility for any damages that might occur directly or indirectly from these inaccuracies.

Microsoft may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft Corporation, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property rights.

© 1997–1998 Microsoft Corporation. All rights reserved.

ActiveMovie, ActiveX, Direct3D, DirectDraw, DirectShow, DirectX, JScript, Microsoft, Microsoft Press, MSDN, MS-DOS, MSN, Natural, NetShow, Sidewalk, SQL Server, Visual Basic, Visual C++, Visual J++, WebTV, Win32, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the USA and/or other countries.

Intel is a registered trademark of Intel Corporation.

Gemstar and the Gemstar logo design are either trademarks or registered trademarks of Gemstar International Group Limited in the U.S. and/or other countries.

Other product and company names mentioned herein may be the trademarks of their respective owners.


About This Programmer's Reference

This March 1998 edition of the Broadcast Architecture Programmer's Reference presents documentation on developing software for broadcast clients and broadcast servers.

Note For information on developing hardware that supports Broadcast Architecture, see the Broadcast Architecture Device-Driver Kit (DDK). This DDK is part of the DDK for the Microsoft® Windows® 98 operating system.

The following sections provide more information about Broadcast Architecture and this reference documentation:

  • Broadcast Architecture Defined
  • Documentation Structure
  • Prerequisites for Broadcast Architecture Development


Broadcast Architecture Defined

The Broadcast Architecture documented here is an integral part of the Microsoft® Windows® 98 operating system. Broadcast Architecture enables personal computers to serve as broadcast clients for digital data networks and for analog broadcast networks.

Using Broadcast Architecture, video, audio, and computing data content for computer receivers can be broadcast over existing networks. Content can also be transmitted by analog cable or analog terrestrial means, and in later versions will be transmitted by satellite.


Documentation Structure

The Broadcast Architecture Programmer's Reference contains the following sections:

  • Overview, including these topics:
    • Introduction to Broadcast Architecture, which covers basic concepts of Broadcast Architecture.
    • How Broadcast Architecture Works, which briefly describes the hardware required, the software to be designed, and the software standards to follow for Broadcast Architecture.
  • Broadcast Client, illustrating how to develop software for the broadcast client on the Microsoft® Windows® 98 operating system. This section includes these topics:
    • Broadcast Client Architecture, outlining the subsystems included in the broadcast client.
    • Television Services, describing the WebTV for Windows component, Television System Services, the Show References data format, and Show Reminders, which remind a user to watch or record a broadcast.
    • Program Guide Services, documenting services that support the Program Guide provided by Broadcast Architecture. This section presents an Overview of Program Guide Services, followed by sections on Guide Data, Guide Database Loaders, Loadstub, Guide Data Objects, the Guide Database Schema, and Program Guide Registry Entries.
    • Streaming Video Services, documenting the streaming video services of Broadcast Architecture in the sections Video Control, Enhancement Video Control, and DirectShow Filter Reference.
    • Data Services, describing the broadcast data support provided by Announcement Listener, Video Enhancements and the Microsoft® Internet Channel Client.

    In the Microsoft® Platform Software Development Kit (SDK), the Broadcast Client section also includes Client Hardware Requirements, describing hardware and operating system requirements of a broadcast client.

  • Broadcast Server, covering development of broadcast server software. This section includes the following topics:
    • Broadcast Server Architecture, providing an overview of the server architecture used to broadcast data to clients in the home.
    • Writing Content Server Applications, discussing design and programming issues to address when creating a data service system for Broadcast Architecture.
    • Working with the Microsoft Multicast Router, documenting the Microsoft Multicast Router (MMR), which enables content servers to send data over a broadcast head end.
    • Internet Channel Server, briefly discussing the Microsoft® Internet Channel Server, which supports Internet channel broadcasting in Broadcast Architecture.
  • Using Broadcast Architecture, providing information on how to develop software for Broadcast Architecture. This section includes the following topics:
    • Displaying Video, discussing how to present audio and video on a computer and how to manage devices associated with video.
    • Writing a Custom Guide Database Loader, covering how to write programs that load information into the Guide database.
    • Scheduling Show Reminders, describing how to schedule show reminders using your applications.
    • Recording Shows, discussing how to write programs that automatically record shows that a user selects from the Program Guide.
    • Creating Controls for WebTV for Windows, discussing how to extend the Broadcast Architecture user interface by writing custom controls to be hosted by Microsoft WebTV for Windows.
    • Building Enhancement Authoring Tools, covering how to develop enhancement authoring tools for users to produce interactive video.
    • Writing and Testing Server Applications, describing how to write applications that send data to the MMR for routing to the broadcast network.
  • Glossary, defining Broadcast Architecture terms.


Prerequisites for Broadcast Architecture Development

The Broadcast Architecture Programmer's Reference assumes the reader is familiar with Hypertext Markup Language (HTML) and with general concepts of programming for Microsoft® Windows® operating systems, such as:

  • The Network Driver Interface Specification (NDIS) driver model
  • The Windows Sockets (WinSock) application programming interface (API)
  • The Microsoft® DirectShow™ API
  • Stream class drivers based on the Windows Driver Model (WDM)

To locate more information on these or other subjects related to Broadcast Architecture development, see Finding Further Information. For more information on working with type libraries in Broadcast Architecture, see Creating Type Libraries for Broadcast Architecture.

In addition, to locate sample applications that demonstrate concepts described in this programmer's reference, see Broadcast Architecture Sample Applications.


Finding Further Information

Depending on what type of software you are developing, you may need to review information on programming topics.

You can obtain much of this information, including all documentation in the Microsoft® Platform Software Development Kit (SDK), through the Microsoft® Developer Network (MSDN™). Microsoft strongly encourages you to enroll in MSDN Level 2 or greater. For enrollment information, contact your local reseller or call (800) 759-5474. For the most timely development information from MSDN, connect to the http://www.microsoft.com/msdn/ site.

The following lists indicate where to find documentation or other information on topics referred to in the Broadcast Architecture Programmer's Reference:

  • Further General Information
  • Further Information on Television Services for the Client
  • Further Information on Program Guide Services for the Client
  • Further Information on Streaming Video Services for the Client
  • Further Information on Data Services for the Client
  • Further Server Information
  • Further Information on Development Tasks in Broadcast Architecture


Further General Information

  • For information on NDIS, see the Microsoft® Windows NT® version 4.0 DDK. This DDK contains most NDIS information Broadcast Architecture developers require. Broadcast Architecture relies on NDIS version 5.0, a recent update; for any information specific to NDIS 5.0, see the NDIS 5.0 specification.
  • For information on Windows base services, including the Microsoft® Win32® application programming interface (API), see the Windows Base Services section of the Microsoft® Platform SDK. For information on the Win32 error function GetLastError, see the Debugging and Error Handling section within the Windows Base Services section.
  • For information on WinSock version 2.0, see the Windows Sockets 2 section in the Platform SDK.
  • For information on WDM stream class drivers and filters, including those that are part of the Microsoft® Windows® 98 operating system, see the device-driver documentation for Windows 98. This documentation is provided as part of the Windows 98 beta program.
  • For information on how to create show enhancements and other content data, see the Design Kit for the Microsoft® Broadcast Architecture compact disc.
  • For information on DirectShow, including information on constructing a custom filter graph and creating new DirectShow filters, see the Microsoft DirectShow SDK section in the Platform SDK.
  • For information on video card requirements for Broadcast Architecture, see Hardware Design Guide for Microsoft® Windows® 95, available from Microsoft Press®.
  • For information on the Component Object Model (COM) and on Microsoft® ActiveX® technologies, see the COM and ActiveX Object Services section of the Platform SDK.
  • For information on Data Access Objects (DAO), see the DAO SDK documentation in the Platform SDK.
  • For information on Structured Query Language (SQL), see the Microsoft® Jet Database SQL Reference in the DAO SDK documentation.
  • For information on the Microsoft® NetShow™ server, see the Microsoft NetShow section of the Platform SDK, or the http://www.microsoft.com/netshow/ World Wide Web site.
  • For information about the Task Scheduler feature of Microsoft® Windows® 98, see the Task Scheduler section of the Platform SDK.


Further Information on Television Services for the Client

  • For more information about WM_POWERBROADCAST messages and the Advanced Configuration and Power Interface (ACPI), see the Power Management Messages section in the Platform SDK and the http://www.microsoft.com/hwdev/desinit/default4.htm Web site.
  • For information about the GetActiveObject function used when connecting to Microsoft® WebTV® for Windows®, see the Automation section of the Platform SDK.
  • For information about the idle processes used by ITVControl, see the OnIdle function topic in Microsoft® Foundation Classes (MFC) documentation supplied with the Microsoft® Visual C++ development system or with MSDN Level 2.
  • For information about the IOleObject interface and the IOleObject::DoVerb method used by the Broadcast Architecture ITVControl interface, see the COM section of the Platform SDK.
  • For information on the QueryDef query definition, see the DAO SDK documentation.
  • For more information on using the Jet database, as required by some functions of Television System Services (TSS), see the Data Access Objects (DAO) SDK documentation in the Platform SDK.
  • For information on the ITaskTrigger interface, the TaskTrigger object, and the TASK_TRIGGER structure used with TSS and with show references, see the Task Scheduler section of the Platform SDK.
  • For information on the IDispatch Component Object Model (COM) interface used by the TSS object library and Microsoft WebTV for Windows applications, and on the IErrorInfo Automation interface, see the Automation section of the Platform SDK.
  • To view the Winerror.h header file, which includes error codes returned by methods of the ITelevisionServices and IScheduledItems interfaces, among others, see the Reference section of the Platform SDK.
  • For access to the Dbdaoerr.h header file, which includes error codes returned by some methods of the ITelevisionServices and IScheduledItems interfaces, see the DAO SDK documentation.
  • For information about using the Jet Installable Sequential Access Module (ISAM), see the DAO SDK documentation.
  • For information on the SAFEARRAY and VARIANT data types, see the Automation section of the Platform SDK.
  • For information about the IEnumVARIANT interface used in enumerating collections, see the Automation section of the Platform SDK.
  • For information about ITask interface, see the Task Scheduler section of the Platform SDK.


Further Information on Program Guide Services for the Client

  • For information on accessing the Jet database engine from a Guide database loader when developing in the Microsoft® Visual Basic® development system, see the Visual Basic documentation supplied with the product or with MSDN Level 2.
  • For information on accessing a Jet database from a Guide database loader when developing in Visual C++, see the Data Access Objects (DAO) SDK documentation in the Platform SDK.
  • For additional information on working with DAO and the Guide database, see the DAO SDK documentation.
  • For information about the Microsoft Foundation Classes (MFC) base class, CObject, and other MFC classes for use with the Guide data objects, see the MFC documentation supplied with Visual C++ or with MSDN Level 2.
  • For information on specifying a Structured Query Language (SQL) WHERE clause as part of setting user viewing restrictions, see the Microsoft Jet Database SQL Reference in the DAO SDK documentation.
  • For information about the SendMessageTimeout and PostMessage functions used when performing event notification for Guide database loaders, see the Windowing section in the Setup and Systems Management Services section of the Platform SDK.
  • For information on locale identifiers for use with the Guide database, see the International Features section in the Windows Base Services section of the Platform SDK.
  • For information about using the Jet Installable Sequential Access Module (ISAM) when loading show enhancements, see the DAO SDK documentation.


Further Information on Streaming Video Services for the Client

  • For information about the WS_CLIPCHILDREN window style and the CWnd::PreCreateWindow and CWnd::OnEraseBkgnd methods, see the Microsoft Foundation Class Reference supplied with the Visual C++ documentation.
  • For information about the methods, properties, and events used with the Visual Basic Extender object when working with the Video control, see the Visual Basic documentation supplied with the product or with MSDN Level 2.
  • For information on the Visual Basic Object Browser, see the Visual Basic documentation.
  • For information about the IFontDisp interface used by the Font property of the BPCVid object for the Video control, see the COM section of the Platform SDK.
  • For information on locale identifiers for use with Video control properties, see the International Features section in the Windows Base Services section of the Platform SDK.
  • For more information about the RGB and QBColor methods of Visual Basic, see "Working with Color" in the Visual Basic documentation.
  • For information on the HWnd handle property used with the BPCDevices collection, see the User Interface Services section of the Platform SDK.
  • For information about the IAMTVTuner::ChannelsMinMax method, values for which correspond to values provided by the BPCVid.MinMaxChannel method, see the Microsoft DirectShow SDK section of the Platform SDK.
  • For more information about Windows power management messages for use with the BPCVid.Power event, see the Power Management Messages section in the Windows Base Services section of the Platform SDK
  • For information on country codes for use with CountryCode, a property of the BPCDeviceBase object used with the Video control, see the Microsoft DirectShow SDK section of the Platform SDK.
  • For information on the BPCDeviceBase property Rate, see the IMediaPosition object documentation in the Microsoft DirectShow SDK section of the Platform SDK.
  • To access the file Axextend.idl, which contains the value AMTUNER_SUBCHAN_DEFAULT for use with the BPCVBIControl.VBITune method, see the DirectShow SDK.
  • For information on device states defined by DirectShow, for use with the BPCVid.StateChange event, see the Axcore.idl file included with the DirectShow SDK.


Further Information on Data Services for the Client

  • For more information about services in Windows that support the Session Description Protocol (SDP), see the reference entry for the ITSdp interface in the TAPI Version 3.0 section of the Platform SDK.
  • For information on the relationship between an announcement in Announcement Listener and a deletion notice for that announcement, see the Session Announcement Protocol (SAP) specification.
  • For information on the IPersistStream interface used by Announcement Listener, see the COM section of the Platform SDK.
  • For information on designing and creating enhancements for shows and on enhancement design issues, see the documentation included on the Design Kit for the Microsoft Broadcast Architecture compact disc.
  • For information on how to sign an ActiveX control, see the article "Signing and Marking ActiveX Controls" on the http://www.microsoft.com/workshop/prog/controls/signmark-f.htm Web page.
  • For information on the stream compiler language and its syntax, see the reference on stream compiler syntax included with the Design Kit for the Microsoft Broadcast Architecture compact disc.
  • For documentation on File Transfer Service (FTS), a component of NetShow used to transmit enhancement files and their dependencies, see the Microsoft NetShow section of the Platform SDK.
  • For information on the Enhancement Stream Editor, see the Design Kit for the Microsoft Broadcast Architecture compact disc.
  • For more information on using the Enhancement control on the broadcast client, see the Design Kit for the Microsoft Broadcast Architecture compact disc.
  • For more information on the CSS positioning feature of Dynamic Hypertext Markup Language (DHTML) for use in enhancement layouts, see the Dynamic HTML section of the Internet Client SDK or the Internet Explorer Reference section of the Platform SDK.
  • For more information on working with cabinet files, see the Microsoft® Cabinet SDK, located at the Web site http://www.microsoft.com/workshop/prog/cab/cabdl.htm.
  • For information on the channel subscription mechanism of Microsoft® Internet Explorer version 4.0, used in Internet channel broadcasting, see the Internet Client SDK or the Internet Explorer Reference section of the Platform SDK. This documentation includes information on channels and Channel Definition Format (CDF) files.


Further Server Information

  • For information on providing system administration for a Microsoft® Multicast Router, see the administrator's guide for Windows NT Server.
  • For documentation on the WinSock structure FLOWSPEC used with Microsoft Broadcast Data Network (MSBDN) functions, see the Windows Sockets 2 section of the Platform SDK.
  • For information on the speed of the serial interface to use for communication with the TES-3 encoder, information used by the serial VBI virtual interface (VIF), see the documentation for the Norpak TES-3 encoder.
  • For documentation on the Win32 application programming interface (API) functions that VIF functions call, see the Windows Base Services section of the Platform SDK.


Further Information on Development Tasks in Broadcast Architecture

  • For more information on working with display surfaces, also called drawing surfaces, see the documentation for the Microsoft® DirectDraw® application programming interface (API) in the DirectX 5 section of the Platform SDK.
  • For information on the registry and retrieving data from it, see the Registry section of the Platform SDK.
  • For information on the CdbDBEngine object used when creating a custom database loader, see the Data Access Objects (DAO) SDK documentation in the Platform SDK.
  • For information on how to sign an ActiveX control, see the article "Signing and Marking ActiveX Controls" on the http://www.microsoft.com/workshop/prog/controls/signmark-f.htm Web page.
  • For information about the GetActiveObject function used when connecting to WebTV for Windows, see the Automation section of the Platform SDK.


Creating Type Libraries for Broadcast Architecture

Broadcast Architecture does not provide separate type library files for its components. Instead, type library information is included as a resource in the .dll or .ocx file for the component in question. Including type library information as a resource ensures that this information is always the correct version for the object library. To create a type library from a .dll or .ocx file, use the type library utilities provided by your compiler.

If you are using Visual C++, the type library utility is the ClassWizard available from the View menu. In the Microsoft® Visual J++™ development system for Java, use the Java Type Library Wizard available from the Tools menu. In Visual Basic, simply create a reference to the object library or add the component to the project.


Introduction to Broadcast Architecture

The design of Broadcast Architecture enables personal computers to receive video and digital data from virtually any broadcast source, including existing satellite, cable, and terrestrial television networks. Effective with the Microsoft® Windows® 98 operating system, every copy of Windows shipped includes extensions that support Broadcast Architecture. Any computer running these extensions, and equipped with enabling hardware, can receive interactive entertainment and information delivered through high-speed, nationwide broadcast channels.

Broadcast Architecture offers an evolutionary step in the progress of computers and television. By using Broadcast Architecture, you can build upon your existing content and technologies, while creating added value by combining them in new ways. At the same time, Broadcast Architecture suggests new avenues for the distribution of home entertainment, news, information, education, software, and general retail merchandise.

The following sections introduce the concepts, goals, and implications of Broadcast Architecture:

  • Concept: Computers Receive Broadcasts. In a nutshell, Broadcast Architecture allows personal computers to receive broadcasts transmitted over any kind of network.
  • The Broadcast Push Model. Why broadcasting is an efficient way to deliver large amounts of information.
  • Computer Power. As a receiver of television, radio, and data broadcasts, a personal computer has many advantages over older technologies.
  • New Kinds of Television. The combination of television and computers creates a new medium that not only provides information and entertainment for users, but also offers many new opportunities for advertisers, broadcasters, network operators, all types of publishers, and hardware and software manufacturers.
  • New Kinds of Data. New types of content can be designed and created specifically for broadcast clients. At the same time, broadcast client viewers can watch standard television with top-of-the-line picture quality and sound.


Concept: Computers Receive Broadcasts

Broadcast Architecture relies on Internet Protocol (IP) multicast and other standard technologies to let a personal computer receive unidirectional digital and analog transmissions over any kind of television or computer network. Broadcast Architecture is transport independent; in other words, Broadcast Architecture data can travel over any standard data-transfer system.

Following a standard client/server computing model, broadcast-enhanced computers are equipped to act as "clients." In other words, they serve as data tuners that receive and process streams transmitted to them by broadcast "servers."

The following diagram illustrates client computers receiving broadcast data over different kinds of television network.

A broadcast client can easily be equipped with appropriate receiver cards and supporting software to receive broadcasts in virtually any format from almost any source. Whether the transmission travels by satellite, cable, conventional terrestrial antenna, or over a computer network, whether the signal is digital or analog, whether it is a video, audio, or binary data stream, broadcast clients are designed to accommodate it. Clients accommodate all these types of data in a standard way using the Microsoft® Windows® 98 operating system. In fact, the same broadcast client is designed to receive almost any combination of sources and data types.

Almost all the technology and infrastructure needed to create broadcast clients is currently in place. In particular, broadcast clients rely on broadcast networks and a phone-line back channel that are inexpensively and reliably available in virtually every home today.

Broadcast clients provide a particularly flexible and cost-effective path to television of the future. Not only do they have a lot to offer immediately, but also they support low-cost incremental steps to higher television resolutions, growing back-channel bandwidth, increasing interactivity, and new multimedia forms of television. For viewers and content producers alike, broadcast clients provide painless interim solutions at every stage of the path. Rather than becoming obsolete when new technology becomes available, they are designed to incorporate technological advances smoothly.

Broadcast client software has been designed so that some simple, impressive combinations of television and information content can immediately be delivered in the form of World Wide Web pages. Broadcasters can thus take advantage of standard Web design tools, scripts built in the Microsoft® Visual Basic® development system, and skills they already have to create multimedia television rapidly and easily. In the cases where Web functionality is insufficient, programmers can readily take advantage of the power of the operating-system software provided for the broadcast client to write special-purpose applications.

Note Satellite support is not enabled in version 1 of Broadcast Architecture.


The Broadcast Push Model

Data transmitted over a computer or broadcast network using a unidirectional "push" model can reach very large numbers of people much more efficiently than the bidirectional "pull" model used on most computer networks today.

Computer networks today, including the Internet, generally use a pull model for transmitting data. In a pull model, a client sends a request for specific data to a server. The server processes the request and then sends back the requested information. In this model, clients "pull" information from the server. The process breaks down when too many clients request information at once. This breakdown occurs because even very powerful servers can handle only a limited number of requests at a time, and they must send a separate response to every request.

In a true push model, by contrast, the server broadcasts a large amount of information onto the network on its own schedule, without waiting for requests. The clients scan incoming information and save the parts users have indicated interest in, while discarding the rest. In this model, one server transmission can service an unlimited number of clients at once. In cases where many people need the same information, this push model is a much more efficient use of network bandwidth than the pull model.

The combination of a true push model and the very high bandwidths of existing broadcast channels allows Broadcast Architecture to deliver large quantities of data to customers conveniently. Such data can include video, audio, high-resolution images, large aggregated blocks of World Wide Web pages, databases, software, and data in other formats. This kind of data is generally too large to send or receive over telephone connections on a regular basis, even with the fastest modems. Broadcast Architecture can deliver this data to a client automatically, in the background, without the customer ever having to dial in, tune in, or download anything.

Soon, satellite broadcast digital data streams with capacities of between 1.2 and 6 megabits per second will be available on broadcast clients. At 1.2 megabits per second, a channel can transfer over 10 gigabytes every 24 hours, while 6 megabits per second translates into more than 60 gigabytes of information per day. By contrast, a compact disc today holds about two-thirds of a gigabyte. In future versions of Broadcast Architecture, a variety of 30-megabit-per-second channels may each deliver over 300 gigabytes per day.

Not only is broadcasting an efficient way to distribute information, existing broadcast networks already reach an enormous national and international audience. Digital Household Report of August 31, 1996, projected that 96.9 million households in the United States would receive analog and digital broadcast transmissions by the end of 1996. Broadcasts also reach a growing number of households internationally as broadcast satellite networks continue to proliferate.

Broadcast Architecture uses the existing standard Internet Protocol (IP) for broadcasting data. Over the Internet and other computer networks that make use of IP, broadcasts take the form of IP multicasts sent to many recipients at once, in contrast to usual unicasts, which are directed to a single recipient. In a corporate context, multicasting can greatly reduce network traffic over intranets when compared to unicasting the same data to the same recipients. A broadcast client is a perfect client for corporate multicasts both because of its high-bandwidth capabilities and because Broadcast Architecture handles all broadcast data as standard IP multicasts.


Computer Power

Broadcast Architecture applies the versatility and power of computers in home or office to provide capabilities far beyond what televisions equipped with set-top boxes can achieve. Even before new programming becomes available, broadcast clients provide an appealing integration of excellent picture and sound quality with a state-of-the-art multimedia computer.

The computer gives viewers a great deal of flexibility in planning television programming, and it displays Program Guide information very conveniently and clearly. Using a modem connection to the Internet, data services of all kinds are available today.

State-of-the-Art Computer Capabilities

To start with, you have all the power of a state-of-the-art computer, including multimedia and game playing. New power-saving instant response technology keeps the system available at all times. The Internet is fully accessible by modem, and some Internet content is already coordinated with television, as in the case of the MSNBC news network.

Digital Display Technology for Television Signals

In addition, broadcast clients offer an incremental, flexible, and affordable migration path to higher resolution television. Instead of buying a whole new, very expensive digital set every time broadcast technology shifts to a new standard, all users have to do is plug a new card into their computers.

Powerful Control over Programming Choices

Broadcast clients display program guide information of many different sorts in a single form. In this combined program guide, shows can easily be previewed, scheduled, and if appropriate paid for.

Broadcast clients offer the convenience and ease of use of finding, selecting, and scheduling entertainment and information in one place, using one familiar interface.


New Kinds of Television

Broadcast Architecture transforms television into a multimedia experience. The combination of television with broadcast digital data displayed on a computer offers a new world of entertainment possibilities. It gives you the flexibility to become more actively involved in the television programs you watch, when you want to.

Digital data broadcasts synchronized to television shows can provide all kinds of annotation and extension of existing television and advertising content, using Hypertext Markup Language (HTML), Microsoft® Visual Basic® scripts, and controls based on the Microsoft® ActiveX® technology platform.

The combination of television and computer content can offer these new possibilities, among many others:

  • During sporting events, you can ask about statistics, track your favorite players or teams, and scan your preferred syndicated commentary.
  • During dramas and comedies, you can locate cast information, recaps of past episodes, links to related Internet and bulletin board sites, and other such background information.
  • Educational programs can supplement their presentations with broader and deeper information than fits into their time slots, together with links and references to additional resources.
  • News and weather reports can be accompanied by local or other specialized information that satisfies the needs of limited audiences.
  • Music-only channels can add background graphics containing song title, album, and artist information, so you know what you are listening to and how to find it again.

With the addition of a back channel, viewers can interact not only with the computer but also more directly with broadcasters, advertisers, and other viewers. A secure back channel also offers an unprecedented opportunity to sell directly into people's homes, letting them purchase from the comfort of their couches.

Broadcast Architecture Provides Potential for Immediate Viewer Response

Even without a back channel, television and digital data broadcasts can be synchronized and combined to let viewers interact on-screen with shows so as to play games, obtain supplementary information, test their knowledge or skills, and so on. Content providers can use common tools for World Wide Web site design to create enhancements for their shows, delivered as HTML pages.

By taking advantage of the low-cost, low-bandwidth back channel offered by the computer's modem, however, advertisers can also actually solicit real-time responses from viewers. Viewers can, for example, express product preferences, or they can inquire about products of interest.

Using the back channel, viewers can also vote on issues presented in a show, express opinions, take part in polls, play along with game shows, enter contests, and take quizzes. In addition, consumers can use the back channel to purchase products from the comfort of their living rooms.


New Kinds of Data

Broadcast channels provide a fast and inexpensive way of distributing information. The broadcast client can monitor digital data streams 24 hours a day to keep caches of subscribed information up-to-date, without using the phone.

Broadcast clients are designed to filter high-bandwidth broadcast data streams and save whatever the viewer may have subscribed to, requested, or purchased. In combination with the broadcast client's system security and strong encryption, this capacity provides a reliable and economical channel for selling even high-priced or confidential digital goods and services.

Digital data can not only be sent over digital networks, it can also be incorporated into analog television signals in the vertical blanking interval (VBI). Digital data automatically transmitted in the VBI includes the Program Guide data provided by Gemstar and other companies. Digital transmissions can also use analog bandwidth directly through broadband modems, such as cable modems.

Digital data broadcasts are ideal for delivering such time-sensitive information as stock prices, local news and weather, product catalogs, software updates, and much other information provided by subscription services. For example, frequently visited Internet sites can easily be broadcast in this fashion and cached on a hard drive. They are thus instantly available in an up-to-date form when a viewer wants them, perhaps in conjunction with an associated show or advertisement. Caching such sites eliminates frustrating busy signals, slow server response, and long download times that may be associated with visiting the sites using a modem.

Not only can broadcasting and caching popular Internet content make visiting useful pages much less frustrating for consumers, it can also reduce server loads so that other interactions, such as purchases, can proceed without delay.

In addition, background images, video, and music downloaded over high-bandwidth broadcast channels can be used to make computer experiences more attractive and fun, particularly in the realm of entertainment software and educational programs. All kinds of digital information previously difficult or very time-consuming to acquire can be made immediately available. For example, games or courseware might be regularly updated with new scenarios, information, backgrounds, and so forth to provide users a constantly changing landscape of interactivity.


How Broadcast Architecture Works

Broadcast Architecture capabilities are achieved through a combination of hardware and software components that allows personal computers to serve as clients of broadband digital and analog broadcast networks. The following sections provide more information on these components:

  • Overview of the Hardware
  • Overview of the Software
  • Sticking to Standard Technologies
  • System Software Components
  • System Software Extensions


Overview of the Hardware

To achieve their purposes, broadcast clients require hardware components of the following sort:

  • A digital-ready display. Broadcast clients are intended for home display of television. To achieve this goal requires a progressive-scan super VGA (SVGA) monitor with a resolution of at least 800 x 600 pixels, a refresh rate of 60 or 120 hertz, and phosphors with matching persistence so as to minimize flicker while matching the luminance of television picture tubes. Suitable monitors vary in size from under 17 inches to over 35 inches.
  • A network receiver card. The receiver card, installed on a PCI or other high-bandwidth bus, provides functionality such as data tuning, decryption, demultiplexing, and other capabilities that permit it to receive signals from specific broadcast sources.
  • A video card capable of MPEG-2 compression. A video card with MPEG-1 and MPEG-2 audio and video decoding capabilities, also installed on a PCI or other high-bandwidth bus, must provide functionality such as SVGA video display, MPEG decoding, and NTSC or PAL signal demodulation and encoding. This functionality is needed for digital video disks (DVDs) as well as for videotape input/output and ordinary television broadcasts.
  • A standard modem. Customers require a back channel to purchase pay-per-view movies and other premium data services and to interact with advertisers and broadcasters. A 14.4-kilobit-per-second or faster telephone modem provides a low-bandwidth back channel that is more than adequate for these needs. As Integrated Services Digital Network (ISDN), Asymmetrical Digital Subscriber Line (ADSL), and cable modems become widely available, faster back channels will become practical. As they do, more dynamic forms of interactive entertainment will evolve.
  • A keyboard, pointing device, and remote control. Viewers must be able to control a broadcast client, together with other consumer electronic devices such as a VCR or stereo system, comfortably and conveniently from a seat some distance from the screen. The keyboard, pointer, or remote control device or devices that meet this need should be wireless and designed for easy use on the lap.
  • Custom hardware device drivers. Vendors of special-purpose cards to be part of the system need to provide standard device drivers for their hardware based on the Network Driver Interface Specification (NDIS).

Detailed minimum and recommended hardware configurations are specified in Client Hardware Requirements. However, within the given boundaries, alternate configurations are encouraged, as long as good television and data reception for broadcasts continues to be provided.


Overview of the Software

Broadcast clients must be able to handle a wide variety of very high-bandwidth streams. These streams require different kinds of special-purpose hardware for reception and processing. The software that makes this demanding environment work is characterized by three design objectives:

  • To use industry-standard technology wherever possible.
  • To expose and document extensions specific to Broadcast Architecture.
  • To maintain adequate security to protect all parties using Broadcast Architecture.

The software needed to make a broadcast client work can be divided into three categories:

  • Operating-system software. The system software provided with Broadcast Architecture is based on industry standards to ensure its reliability and ongoing development.
  • The container for Broadcast Architecture applications. Broadcast Architecture applications all run within the standard browser container provided by Microsoft® Internet Explorer. This container allows new applications downloaded by data broadcasters to take full advantage of all broadcast client capabilities, just as if the applications were integral parts of the system.
  • Broadcast Architecture applications. These applications can be controls or scripts associated with World Wide Web pages, any other Internet application supported by Internet Explorer, or even ordinary Windows-based programs running outside the Internet Explorer container. Among the most important Broadcast Architecture applications is the Program Guide control that lets viewers search, sort, filter, select, and schedule television shows and other content of all kinds.

To locate documentation on creating specific types of Broadcast Architecture applications, see Documentation Structure.


Sticking to Standard Technologies

Wherever possible, Broadcast Architecture software relies on standard solutions that are widely accepted, understood, and supported in the industry. These standards include:

  • The Transmission Control Protocol/Internet Protocol (TCP/IP) networking protocol. This protocol is the one used by the Internet. By using TCP/IP as their primary networking protocol, broadcast clients make a standard way available to communicate with virtually any network in the world.
  • MPEG-2 compression. This format is becoming the most widely accepted standard for delivering compressed video and audio and related data.
  • The Microsoft® Windows® 98 operating system. In addition to being the successor to the most widely used and understood 32-bit operating system, Microsoft® Windows® 95, Windows 98 includes a number of components that are becoming or have become standards themselves:
    • Windows Sockets (WinSock) version 2.0. This application programming interface (API) provides a network abstraction layer that allows applications to receive and send network data without needing any information about the network involved. WinSock also provides access to TCP/IP.
    • Network Driver Interface Specification (NDIS) version 5.0 ports. The NDIS standard allows hardware device drivers to be written independently of the target operating system.
    • CryptoAPI. This API provides an abstraction layer for encryption and decryption services, so that applications can use different encryption methods without requiring any information about the hardware or software involved.
    • Microsoft® Internet Explorer. By incorporating Internet Explorer technology, the broadcast client can take advantage of all the latest Internet and Web enhancements.
    • Component Object Model (COM). This open standard allows different software modules, written without information about each other, to work together as if they were part of the same program.
    • Microsoft DirectShow (formerly called Microsoft® ActiveMovie™). This Microsoft® ActiveX® technology provides an extremely flexible and capable architecture for managing and playing interrelated multimedia streams, which the broadcast client relies on. The key concept of the Microsoft® DirectShow™ API is to connect many independent filter programs together. Each filter handles a part of the process of receiving, decoding, transforming, scheduling, and displaying interdependent video, audio, and data streams.
    • Key codes for television remote controls. The remote control buttons included on keyboards and other devices communicate with broadcast clients by using standard Windows key codes. Use of standard key codes makes integration of remote functions into hardware very simple for manufacturers.

The DirectShow technology and the related stream class driver technology, part of the Windows Driver Model (WDM), is sufficiently important for broadcast clients that its flexibility should be stressed. DirectShow filters are modular software components that work together to process a data stream. When one feature of the stream changes, only the filter dealing with that feature need be replaced. For example, if a stream's encoding changes, only its decoding filter is affected. This modularity makes it easy to use and support clients that work with virtually any kind of broadcast possible.

To get the maximum performance, Broadcast Architecture supports DirectShow by using WDM stream class drivers. These drivers operate on data in kernel mode. DirectShow provides control of these drivers to applications through the use of proxy filters running in user mode. For example, an application can call a proxy filter in DirectShow to change channels on a television tuner card. Then the proxy filter calls the WDM stream class driver, which controls the television tuner card.

To locate more information on how to create and use new DirectShow filters to handle changing technologies, and on WDM stream class drivers and filters, see Further General Information.


System Software Components

Operating-system software components particularly important to software development for Broadcast Architecture include:

  • The Program Guide control, which gives a user access to the Guide database.
  • Microsoft WebTV for Windows, a Microsoft® ActiveX® container. Microsoft® WebTV® for Windows® is the primary user interface of the Broadcast Architecture component in the Microsoft® Windows® 98 operating system.
  • The standard Broadcast Architecture control that parses and displays Hypertext Markup Language (HTML)

Of these, probably the most visible one is the Program Guide control. In clear graphical form, the Program Guide control displays information on all broadcast programming available to the user over various time periods. With this control, the user can search for favorite shows, keep track of episodes, set up reminders to watch or record shows, and watch previews. This control is continuously updated with Program Guide information from various providers.

The primary user interface of the Broadcast Architecture system component, WebTV for Windows, is an ActiveX container that hosts several important types of control. One type of control can play full-motion video over some or all of the screen. In other words, ActiveX controls within the WebTV for Windows container create the television video and audio that viewers see and hear. Another type of control displayed in WebTV for Windows uses Microsoft® Internet Explorer technology to interpret and display Web pages, either in conjunction with video or on their own.

This control, the standard Broadcast Architecture control that parses and displays HTML data, can also process scripts and host any ActiveX controls that a broadcaster chooses to include with a show. Because HTML is the language of the World Wide Web, the presence of this control not only means that a large amount of Internet data can immediately be combined with television programming, but also that there are existing, good tools for quickly designing and creating new HTML content without software development. A broadcaster can use triggers to synchronize the display of HTML material with television and can add, update, or remove HTML material without any intervention on the viewer's part.

Furthermore, through scripts and ActiveX controls included with HTML pages, broadcasters and independent software vendors can take full advantage of the broadcast client's computing capabilities to enhance a show in new ways, to provide complex interactivity with viewers, and to deliver valuable services. To locate more information on doing so, see Further General Information.

Although Broadcast Architecture software is designed to be open to developers, great care has been taken to ensure that system security can be maintained. Broadcast clients can thus provide a secure platform for commercial transactions.


System Software Extensions

The operating-system software that forms part of Broadcast Architecture is intentionally based on industry standards, as described in Sticking to Standard Technologies. These standards guarantee developers, manufacturers, and viewers a stable, well-supported platform that will gracefully evolve to support new technologies as they appear.

In some areas, extensions to these standard technologies have been required. These extensions include:

  • Extensions to accommodate the very large bandwidth occupied by high-quality digital audio and video streams, and to provide for flexible control over these streams. These extensions are special filters based on the Microsoft® DirectShow™ application programming interface (API). To locate more information on DirectShow, see Further General Information.
  • Extensions to support interactions with users. Broadcast clients use specialized software to control, process, and display high-bandwidth broadcast streams. Some of this software, such as the Guide database system, also handles user interactions. The Guide database provides a single secure repository for program data. At the same time, any service provider can deliver application data to the database by writing a loader program.
  • Extensions to support Television System Services (TSS), which allows users to tune to, schedule, and control available broadcasts. For more information, see Television System Services.

Microsoft also provides other types of system software extensions, such as a transport layer specifically designed for broadcast needs. Because such components all function as part of the Microsoft® Windows® 98 operating system, third-party programmers can easily write programs that take advantage of them.

Microsoft makes interfaces that support operating-system extensions available through the Microsoft® Platform Software Development Kit (SDK) and the Device-Driver Kit (DDK) for Windows 98. The Broadcast Architecture Programmer's Reference and the Broadcast Architecture DDK documentation cover these interfaces.


Broadcast Client Architecture

The architecture of the broadcast client enables computers based on the Microsoft® Windows® 98 operating system to be client systems for many types of broadcast network. The broadcast client is a standard computer enhanced with hardware and software components that enable it to process video, audio, and data from a variety of sources.

Some networks that broadcast clients can support include:

  • The Internet's multicast backbone (MBONE), and the networks and telephone lines that support it — Integrated Services Digital Network (ISDN), Ethernet, Asymmetrical Digital Subscriber Line (ADSL), and others.
  • Cable television networks, such as Comcast and Tele-Communications, Inc. (TCI).
  • Wireless cable networks.
  • Conventional television networks.
  • Television networks that broadcast digital data to viewers in the vertical blanking interval (VBI) of the television signal, such as Intel Intercast.

Some networks used by Broadcast Architecture send information as one-way data streams. Such networks have several unique aspects that must be considered. These networks cannot run server applications that require a back channel to receive data from the client. In other circumstances, the architecture of the broadcast client allows the use of another network, such as the Internet, to provide this back channel. Another effect of the one-way nature of such networks is that the client cannot request that a bad packet be resent. To reduce the problems this inability causes, the server must periodically resend data so the client can replace any corrupted or lost data. Finally, one-way broadcast networks are capable of very high data transfer rates. Devices for Broadcast Architecture networks, and the software associated with these devices, must be capable of handling this data rate without burdening the CPU.

The high bandwidth of many broadcast networks make them ideal for transmission of audio and video data as well as computing data. Broadcast Architecture uses a set of modular components to receive, process, and present this data. This modular design means application developers can create applications without regard for the underlying technology. Hardware vendors can provide drivers to make their devices compatible with other broadcast client components.


Broadcast Architecture Subsystems Overview

The broadcast client consists of a number of functional subsystems. These subsystems provide the capabilities needed to receive and use audio, video, and other data from a broadcast server on a client running the Microsoft® Windows® 98 operating system.

The following illustration shows an overview of the Broadcast Architecture subsystems.

Of the components in these subsystems, some are supplied with Broadcast Architecture, and others come from the Microsoft® Windows® 98 operating system or third party developers. In order to give a complete overview of the broadcast client, the following sections briefly describe all components regardless of their source. The subsystems covered are:

  • Broadcast Data Receiver Subsystem describes the components that receive data and pass it on to the other subsystems.
  • Data Services Subsystem describes the components that process the computing data within the broadcast data stream, in other words, the data that does not present audio or video.
  • Broadcast Client Presentation Subsystem describes the Microsoft® DirectShow™ filter graph used in a broadcast client and the components that present audio and video.
  • Television Client Services Subsystem describes components for configuring and controlling television channels.
  • WebTV for Windows Subsystem describes Microsoft WebTV for Windows and its components.


Broadcast Data Receiver Subsystem

The broadcast client receives a number of different data streams over one or more broadcast networks by means of miniports. Broadcast Architecture NIC miniports, drivers for the Microsoft® Windows® 98 operating system, allow different hardware devices to have a common interface to the broadcast client. These miniports conform to the Network Driver Interface Specification (NDIS) version 5.0 including the Broadcast Architecture NDIS extensions. For more information on Broadcast Architecture NDIS extensions, see the NDIS Extensions section of the Broadcast Architecture Device-Driver Kit (DDK), part of the Windows 98 DDK.

A Broadcast Architecture NIC miniport splits broadcast data into two streams. The first stream includes audio and video data sent by way of the Broadcast Architecture transport to the DirectShow filter graph. Any other data received, such as Hypertext Markup Language (HTML) pages, data files, or control information, is formatted as Internet Protocol (IP) packets and sent to Windows Sockets (WinSock) version 2.0.

Applications that require a back channel to the server can connect to another network by using WinSock. Routing all data through WinSock simplifies the interface to the server, as WinSock then provides a single application programming interface (API) for data exchange.

The following illustration shows how the components of the Broadcast Data Receiver subsystem fit together.

The following topics briefly describe the components of the Broadcast Data Receiver subsystem.

Windows Sockets

WinSock 2.0, a Windows API, is a Windows 98 system component. It provides a networking standard that gives applications an abstraction of the networking software below it. In Broadcast Architecture, WinSock handles digital computing data, as opposed to audio and video data streams.

TCP/IP

Transmission Control Protocol/Internet Protocol (TCP/IP) is the industry-standard protocol used by WinSock 2.0 to send and receive data. WinSock packages and unpackages data into IP packets that it sends to and receives from a TCP/IP network.

Broadcast Architecture Transport

The Broadcast Architecture transport is a Broadcast Architecture component. The Broadcast Architecture transport allows various system components to move audio and video data through the system. It is a high-bandwidth transport with special support for features such as television channel selection. For more information, see the Broadcast Architecture Transport section of the Broadcast Architecture DDK.

NDIS 5.0

NDIS 5.0 is a device driver model for Windows 98 and the Microsoft® Windows NT® operating system that provides an operating system-independent standard for writing network device drivers. NDIS 5.0 allows independent hardware vendors (IHVs) to extend existing drivers to create hardware-specific drivers; the extensions written by an IHV are called a miniport. In Broadcast Architecture, NDIS-compliant miniports provide an interface between network interface cards (NICs) and other broadcast client components.

Broadcast Architecture NIC Miniports

A Broadcast Architecture NIC miniport, provided by an independent hardware vendor, is the NIC-specific portion of an NDIS 5.0 driver. Each type of NIC requires a unique miniport. For more information, see the NIC Miniport section of the Broadcast Architecture DDK.

NDIS 802.3 Intermediate Driver

The NDIS 802.3 intermediate driver is a Broadcast Architecture component that translates Multipacket Transport (MPT) packets, from satellite networks, into IP packets. This translation makes it possible for WinSock to handle satellite data as it does any other data carried by TCP/IP.

Receiver Cards

A receiver card is a component provided by independent hardware vendors. This card receives incoming broadcast signals and converts them to data the computer can use. In Broadcast Architecture, it provides a point of entry for broadcast data into the system.


Data Services Subsystem

The Data Services subsystem receives computing data streams from broadcast servers by using Windows Sockets (WinSock) 2.0. The subsystem then routes that data to applications.

Using the Data Services subsystem over a broadcast network allows data to be sent to many users without the extra bandwidth required for such data transfer by nonbroadcast networks. Instead of sending separate packets to each client that requests data, as nonbroadcast servers do, broadcast servers send one packet that is received by all clients that are "listening" (monitoring the data stream) for that data. The Data Services subsystem monitors for such broadcasts and stores the data received on the broadcast client.

The following illustration shows how the components of the Data Services subsystem fit together.

Announcement Listener

Announcement Listener is a Broadcast Architecture component that monitors incoming announcements of upcoming transmissions. These announcements indicate when the specified data will be sent. Announcement Listener can handle announcements itself or pass them through announcement filters, allowing the filters to handle them.

Announcement Listener maintains a list of the current announcement filters and passes announcements to each filter in its list. If a filter recognizes the announcement, it handles the announcement. If no filter in the list recognizes the announcement, Announcement Listener can respond to the announcement. For announcements that immediately precede the data they are announcing, Announcement Listener uses the information in the announcement to set up File Transfer Service (FTS) to receive data and starts the FTS receiver. Otherwise, Announcement Listener uses the Task Manager in the Microsoft® Windows® 98 operating system to schedule FTS to run at the time specified in the announcement.

Announcement Filters

Announcement filters are supplied both as components in Broadcast Architecture and by independent software vendors. These filters are Automation servers used by Announcement Listener to determine which types of data broadcast to receive. A typical action for an announcement filter is to schedule the FTS receiver to receive a file.

FTS Receiver

The FTS receiver is a Broadcast Architecture component that receives data from a broadcast network. A typical use of the FTS receiver is to receive file packages for the Microsoft® Internet Channel Client. Other uses of the FTS receiver are to receive files and database updates. Depending on options passed to it, FTS can save the data to a disk or pass the data to another application, or if the data is an executable file FTS can load the data into memory and execute it.

Internet Channel Client

The Internet Channel Client is a Broadcast Architecture component that receives information from a Microsoft® Internet Channel Server. The information that the client receives can be Hypertext Markup Language (HTML) pages from the World Wide Web or data files. The Internet Channel Client includes an announcement filter that checks for announcements about upcoming Internet channel broadcasts. When the filter receives an announcement, it compares the announcement to the IE 4 subscription list to see if it should receive the data. If the announcement matches a subscription, the filter runs a program that downloads the data and saves it in the Microsoft® Internet Explorer cache or to a directory specified in the announcement.

Internet Explorer

Internet Explorer is a World Wide Web browser included in Windows 98. Internet Explorer stores Web pages it has received in a cache on a local hard disk. The Internet Channel Client puts pages into this cache so the user can see them.

Broadcast Architecture includes Microsoft® ActiveX® controls for showing video in Web pages displayed by Internet Explorer.

Windows File System

The Windows file system is simply the data storage system used by Windows 98.


Broadcast Client Presentation Subsystem

Broadcast clients can work with data streams from a wide range of video and audio devices. To do this, Broadcast Architecture works with Microsoft® DirectShow™, a component of the Microsoft® Windows® 98 operating system that lets applications control high-bandwidth data streams.

Broadcast Architecture components such as Microsoft® WebTV® for Windows use a DirectShow filter graph to control the presentation of audio and video data. The following illustration shows how the components of the Broadcast Client Presentation subsystem fit together.

DirectShow Filter Graph

The DirectShow filter graph is a Broadcast Architecture component that tells DirectShow what filters to use for Broadcast Architecture and how these filters connect to each other. The filters for Broadcast Architecture represent Windows Driver Model (WDM) stream class drivers for audio and video devices. Each filter has pins that represent inputs, outputs, and controls for the driver. The filter graph shows how these pins connect to other filters' pins and to applications that use the drivers.

DirectDraw

The Microsoft® DirectDraw® application programming interface (API) is provided through a dynamic-link library (DLL) in Windows 98. Broadcast clients use a new feature of DirectDraw called Video Port Extensions (VPE). VPE provides an application programming interface (API) that accelerates graphics by providing direct access to bitmaps in off-screen display memory, as well as extremely fast access to hardware.

Audio Subsystem

The audio subsystem is a component of Windows 98 that provides an API for applications to play audio.

WDM Stream Class Drivers

WDM stream class drivers are components of Windows 98 used to handle high-bandwidth data streams. Filters in the DirectShow filter graph let applications control these drivers.

An important feature of the filters that control stream drivers is that they can be connected directly to each other to reduce the overhead of handling the stream data. For example, an audio stream driver for a satellite receiver can be connected directly to an audio stream driver for a sound card. This direct connection enables the audio to play without requiring an application to copy data from one device to another.


Television Client Services Subsystem

The following sections briefly describe the components of the Television Client Services subsystem. This subsystem includes a database called the Guide database. Other components in this subsystem use the Guide database to control Microsoft WebTV for Windows and the DirectShow filter graph. The following illustration shows how the components of the Television Client Services subsystem fit together.

Video Access Server

The Video Access server is a Broadcast Architecture component that runs on the broadcast client as a separate process. It handles device contention among multiple instances of the Microsoft® WebTV® for Windows® ActiveX control.

Program Guide ActiveX Controls

The Program Guide Microsoft® ActiveX® controls are Broadcast Architecture components. These controls display the user interface for the Program Guide. For information on the Program Guide, see Overview of Program Guide Services.

Guide Database

The Guide database is a Broadcast Architecture component. A Microsoft® Jet database, it stores current information about broadcast television programs from various broadcast networks. For more information on the Guide database, see Overview of Program Guide Services.

Guide Database Loaders

Guide database loaders are Broadcast Architecture components. In addition to the loaders provided, the Television Client Services subsystem also supports the use of third-party loaders. Generally, a vendor of Program Guide information furnishes a vendor-written loader to the broadcast client when a user subscribes to that vendor's service.

These loaders process incoming Program Guide data and load it into the Guide database. The software supporting the Broadcast Architecture Programmer's Reference includes a skeleton loader as an example for third-party developers. For more information on database loaders, see Updating the Guide Database. To locate the loader sample application, see Broadcast Architecture Sample Applications.


WebTV for Windows Subsystem

Microsoft WebTV for Windows is a Broadcast Architecture component that is part of the Microsoft® Windows® 98 operating system. It displays interactive television programs and their enhancements, if any.

When viewing a television program using Broadcast Architecture, the user first selects a channel using the Program Guide ActiveX controls, part of the Television Client Services subsystem. Then Microsoft® WebTV® for Windows® displays the program being broadcast on the selected channel. WebTV for Windows uses an ActiveX control to display this conventional television program. It also hosts an Hypertext Markup Language (HTML) browser to display a program's interactive content.

The following illustration shows how the components of the WebTV for Windows subsystem fit together.

WebTV for Windows Executable File

The WebTV for Windows executable file, Tvx.exe, is a Broadcast Architecture component. It is the component that users run to see television programs, both interactive and noninteractive.

WebTV for Windows HTML Browser

The WebTV for Windows HTML browser is a Broadcast Architecture component. It displays enhancements received as HTML pages through the broadcast data stream.

Video Display Controls

The video display controls present audio and video on the screen. The Video control presents audio and video in a variety of environments, such as World Wide Web pages and stand-alone applications. The Enhancement Video control shows video and audio on a Web page displayed by WebTV for Windows. For more information about these controls and when to use them, see Which Video Control Should I Use?


Client Hardware Requirements

The following sections explain the minimum and recommended hardware and operating system requirements for a broadcast client, including the Microsoft hardware manufacturing policy for such a client. These requirements extend the Microsoft PC 97 initiative to include requirements for a broadcast client, as follows:

  • Minimum Configuration
  • Recommended Configuration
  • Windows 98 Requirements
  • Hardware Manufacturer Policy
  • Client Hardware Architecture

The following sections detail the hardware requirements for each of the components of a broadcast client:

  • Network Receiver Card
  • MPEG Decoding and Video Display
  • Sound Card
  • Monitor
  • Input Devices
  • Modem
  • Related Hardware Information


Minimum Configuration

The minimum hardware requirements for a broadcast client are:

  • Intel Pentium 120 megahertz processor or compatible
  • High-speed bus with slots adequate to accommodate high-speed broadcast network and video cards, such as PCI or Universal Serial Bus (USB)
  • 16 megabytes (MB) RAM
  • 1 gigabyte hard disk
  • 27-inch super Video Graphics Array (SVGA) monitor capable of 640 x 480 resolution with a noninterlaced refresh rate of 60 hertz
  • 3.5-inch 1.44 MB floppy disk drive
  • Quad-speed CD-ROM drive
  • Internal or external modem with a speed of 14,400 baud and compatible with Telephony Application Programming Interface (TAPI)
  • Standard computer keyboard
  • Pointing device with two buttons

For more information on the minimum requirements for the Monitor, the Network Receiver Card, the Sound Card, and other components of the system, as well as Video Card Recommendations, see the sections detailing each component.


Recommended Configuration

The recommended hardware configuration for a broadcast client is:

  • Intel Pentium 150 megahertz processor.
  • PCI bus with at least four slots available.
  • Computer case of the consumer electronics type, with low-noise fan or noiseless cooling system. A user should not perceive broadcast client noise from a distance of 6 feet in a quiet living-room environment.
  • Support for Simply Interactive PC (SIPC) initiatives such as OnNow, Drive Bay, 1394, and Universal Serial Bus (USB) to provide a more consumer-friendly appearance for the client.
  • 16 megabytes (MB) RAM or more.
  • Hard disk of 2 gigabytes (GB) or larger with a fast data transfer rate.
  • 3.5-inch 1.44 MB floppy drive.
  • 6x-speed CD-ROM drive or digital video disk (DVD).
  • 31-inch monitor capable of 800 x 600 resolution with a noninterlaced refresh rate of 60 hertz.
  • Internal fax modem with a speed of 28,800 baud or higher that is compatible with the AT command set. Modem functionality can be incorporated on expansion cards for the broadcast client, so the modem does not need to be a separate peripheral.
  • Wireless keyboard that responds to radio or infrared frequencies, that is battery-operated, and that has a built-in pointing device.
  • Wireless, television-style remote control.
  • Combination remote control and wireless mouse with power and sleep button, TV buttons (channel up and down, volume up and down, and mute. This remote control/mouse should be battery operated.
  • Sound-system expansion card with:
    • Digital audio, specifically Pulse Code Modulated (PCM) digital input
    • MIDI port
    • MIDI-controlled wave-table synthesizer
    • Multiple analog and digital audio inputs
    • Audio mixer and preamplifier that is software-controllable and low-noise
    • Multiple audio outputs

    Sound-card functionality can be incorporated on motherboard or expansion cards for the broadcast client, so the sound card does not need to be a separate peripheral.

  • Built-in microphone or a front-mounted microphone jack suitable for teleconferencing, education, karaoke, and other applications requiring sound input.
  • Audio compression using the AC-3 algorithm for DVD compatibility.
  • Infrared remote control capable of controlling consumer electronic devices.

For more information on the recommended configuration for the Monitor, the Network Receiver Card, the Sound Card, and other components of the system, as well as Video Card Recommendations, see the sections detailing each component.


Windows 98 Requirements

Because Broadcast Architecture uses the Microsoft® Windows® 98 operating system, hardware designed for it must conform to the Plug and Play architecture. For detailed information on designing hardware compliant with Plug and Play, see Plug and Play Specifications.


Hardware Manufacturer Policy

Broadcast Architecture components are not sold directly to the end user, with possible future exceptions being keyboards and pointing devices. Rather, OEMs and hardware vendors license the technology from a network provider, where applicable. OEMs also license Microsoft Broadcast Data Network (MSBDN) designs and services from Microsoft.

OEMs and hardware vendors are free to build, sell, install, and service their own products compatible with Broadcast Architecture. Because hardware designs and software components are available to numerous OEMs, competition is expected to drive the development of many feature enhancements, and to create distinct price points from which the end user can choose.


Client Hardware Architecture

The following illustration shows how the data flows through the various components of the broadcast client hardware. In this illustration, SVHS is super VHS, SVGA is super Video Graphic Array, MB is megabyte, ns is nanosecond, K is kilobyte, SRAM is static RAM, DES is Data Encryption Standard, MPEG is the video standard, I/O is input/output, IDE is integrated device electronics, and STT is Secure Transaction Technology.


Network Receiver Card

The following sections describe the functionality of a broadcast receiver card and the requirements it must meet to support Broadcast Architecture:

  • Receiver Card Functionality
  • Network Interface Connector or Antenna
  • Signal Paths
  • Receiver Card Requirements
  • Other Networks


Receiver Card Functionality

Because Broadcast Architecture works with many different types of broadcast digital networks, the exact details of a broadcast receiver card depend on the broadcast network and on network-specific access-control mechanisms. Broadcast Architecture software requires a specific software driver for each card. The card vendor or network provider supplies this driver. For more information on such drivers, see the NIC Miniport section of the Broadcast Architecture Device-Driver Kit (DDK), part of the DDK for the Microsoft® Windows® 98 operating system.


Network Interface Connector or Antenna

For a broadcast satellite network, the antenna is typically an outdoor unit. For a cable network interface, the connector is likely a typical F connector used with standard television cabling. For a wireless cable system that supports the Multichannel Multipoint Distributed System (MMDS), a microwave antenna is required.


Signal Paths

The broadcast receiver card must be able to receive both standard broadcast information from broadcast networks and data stream information, as defined by the MSBDN format for data transmission, which supports Multipacket Transport (MPT) and Internet Protocol (IP). For more information on this format, see the MSBDN Receiver section of the Broadcast Architecture Device-Driver Kit (DDK), part of the Windows 98 DDK.

Data streams are likely to be on channels, for example cable and Multichannel Multipoint Distributed System (MMDS) channels, separate from video and audio streams. Similarly, data streams are likely be on transponders, for example transponders for digital broadcast systems, separate from video and audio streams. This separation being usual, the broadcast receiver card requires two paths and signal lines. This section refers to these two paths as the "digital audio-video signal path" and the "digital data signal path." The following sections describe these signal paths separately to clarify their differences.

It is anticipated that hardware vendors will eventually combine both signal paths on the same PCI-bus card and also provide two separate tuners on one PCI-bus card. Such a combination means control, interface, bus mastering, power, and antenna connector resources can be shared. However, early versions of the broadcast receiver card need include only one tuner.

One-tuner versions of the card must receive both data and audio-video signals without user intervention. However, one-tuner cards need not receive both data and audio-video signals simultaneously, unless the signals are broadcast on the same channel or transponder. This reception functionality requires the card to include both network access control circuitry and MSBDN circuitry. The receiver card can also include a smart card as appropriate.

Digital Audio-Video Signal Path

The digital audio-video signal path contains network-specific technology for tuning, demodulating, decoding, error-correcting, demultiplexing, decrypting, and controlling access to digital audio and video signals.

The digital audio-video signal path must be capable of receiving at least four substreams simultaneously, such as video, audio, data, and Program Guide substreams. The design of the receiver card must allow transfer of these streams to computer memory with very low CPU utilization (less than 10 percent). Such a design ensures that the transfer does not interfere with the performance of applications running on the computer. This design implies that the card uses bus mastering or other direct memory access techniques.

Certain network designs mandate that particular access control functionality be resident in hardware. Such access control functionality controls some types of interaction with the consumer, for example preventing certain users from viewing video of specified ratings. In the broadcast client system, the software that verifies access for a particular network is divided into a number of parts. Security functions typically run on a microprocessor on the receiver card. The user interface and any modem interface functions are implemented in the computer. The different verifier portions communicate with each other through Broadcast Architecture driver interfaces; these interfaces manage verifier communication with the user and the network authorization center.

Digital audio-video data is tuned, demodulated, and error-corrected by a module referred to as the transport. The transport then routes the data to circuitry that selects portions of interest from the total stream. These portions may be identified by packet identifiers (PIDs). Information of interest can be passed through MSBDN circuitry for Data Encryption Standard (DES) decryption. After any required decryption processes, data is bus mastered into CPU memory.

Note that not all data is encrypted by the sender. Such data can bypass the circuitry for DES decryption.. It is also possible to take selected data directly from the error correction circuitry and bus master it into memory.

Digital Data Signal Path

The signal path that receives digital data is similar to the existing audio-video path, but it must meet the extra requirement that the digital data signal path must be able to demultiplex a packet stream into one or more substreams. In other words, it must be able to separate several combined data streams. During this demultiplexing process, the path must be able to filter out unwanted packets based on a field in the packet header.

For a more complete description of the data receiver and of required decryption functionality, see the MSBDN Receiver section of the Broadcast Architecture Device-Driver Kit (DDK), part of the Windows 98 DDK.


Receiver Card Requirements

The receiver card's interface with the computer should:

  • Provide a mechanism for moving data into the computer and for specifying the destination for that data in computer memory, preferably through bus mastering.
  • Control the tuner and retrieve tuner information.
  • Control decoding of video, audio, and other data.
  • Control the different Viterbi or other decoding rates used by the digital broadcast network.
  • Control what packet identifiers (PIDs) are received and what data is routed to the computer.
  • Retrieve status information about errors and control error correction.
  • Satisfy the requirements for receiving MSBDN packets, which can require additional hardware beyond that required for audio and video. For more information on receiving MSBDN packets, see the MSBDN Receiver section of the Broadcast Architecture Device-Driver Kit (DDK), part of the Windows 98 DDK.
  • Support of at least five PIDs simultaneously. Support of eight is recommended.
  • Perform one of the two following tasks:
    • Present an advancing 27 megahertz register, a register containing the last-received system clock reference (SCR) or other reference time stamp, and a register containing the value of the 27 megahertz register when the last SCR was received.
    • Generate an interrupt immediately upon receipt of each SCR and have that SCR read through the PCI bus.
  • Perform PCI bus mastering with support for scatter/gather memory access and unaligned, odd-byte memory transfers. This requirement includes support for time-critical MPEG packets of 127 bytes and less.

The following illustration shows the receiver card's internal and external data flow. In this illustration, bps is bits per second, QPSK is Quadrature Phase Shift Keying (a method of encoding digital data in an analog signal), DEMOD is demodulator, DES is Data Encryption Standard, and Mbps is megabits per second.


Other Networks

In the future, cards very similar to the broadcast receiver card will probably be built for the cable, digital video disk, Asymmetrical Digital Subscriber Line (ADSL), and Multichannel Multipoint Distributed System (MMDS) environments. Because these network cards will receive broadcast data rather than individually targeted data, and because they have no back-channel requirement, they will require minimal support from a network head end.


MPEG Decoding and Video Display

The following sections describe the functionality of an MPEG decoder circuit and a video crossbar circuit, and the requirements they must meet to support Broadcast Architecture:

  • MPEG Decoder Functionality
  • MPEG Decoder Requirements
  • MPEG Decoder Recommended Configuration
  • MPEG Decoder Interface
  • Analog Audio and Video Interconnections
  • Integration Possibilities

The components described in these sections are part of a video system that includes standard video cards and sound cards. For functionality recommendations for the standard video card for Broadcast Architecture, see Video Card Recommendations. For functionality recommendations for the standard sound card for Broadcast Architecture, see Sound Card Functionality.


MPEG Decoder Functionality

The MPEG decoder is a video and audio decoder capable of handling MPEG-2 main profile and main level data rates (15 megabits per second). The decoder combines MPEG video with standard computer video for display on a super Video Graphics Array (SVGA) monitor. The MPEG decoder has 2 megabytes (MB) RAM for SVGA, including the frame buffer, and another 2 MB RAM for the MPEG decoder itself.

The computer supporting the decoder should also offer a television tuner and base-band, S-video inputs. It should also offer outputs for routing NTSC and PAL signals to and from VCRs, laser disk players, and other video sources. In addition, the computer must provide encoder and decoder circuitry. This circuitry converts NTSC or PAL input signals into digital data in the video frame buffer and converts decoded MPEG video to NTSC or PAL output signals.

The decoder computer must provide separate audio and video outputs that carry audio and video from video sources, as opposed to computer-generated music and sound effects. These separate outputs are provided so that video and its associated audio can be recorded without recording computer-generated music and sound effects. Associated circuitry provides recording control features that can be activated and deactivated under software control. This recording control includes Macrovision encoding of NTSC video generated directly from the MPEG decoder.

The video card portion of the MPEG decoder must meet the criteria of the Plug and Play Framework architecture that is part of the Microsoft® Windows® 95 operating system. Plug and Play provides specific methods for extending the VGA register set and requirements for the appearance of expanded video-card resources on the system bus. For more information on Plug and Play, see Plug and Play Specifications.

The following diagram shows a video system that includes an MPEG decoder. In this illustration, Comp is composite; SVHS is super VHS; IIC is Inter-Integrated Circuit; SVGA is super Video Graphics Array; DAC is digital to analog converter; PCM is Pulse Code Modulated digital input; FIFO is first in, first out; MB is megabytes; K is kilobytes; and VRAM is video RAM.


MPEG Decoder Requirements

The video card for the MPEG decoder must have the following features:

  • Super Video Graphics Array (SVGA) card capable of at least 800 x 600 x 8 bits per pixel, with a 60 hertz refresh rate.
  • Support for high-speed, two-dimensional graphics acceleration, preferably with support for three-dimensional bitmaps and MPEG textured polygons.
  • MPEG-2 decoder chip set, capable of a speed of 15 megabits per second and a screen resolution of 720 x 480 x YUV 4:2:2.
  • Data transfer using bus mastering from memory to the MPEG decoder, at up to 2 megabytes per second in speed. Such transfer must include support for unaligned, odd byte transfer and scatter/gather memory access.
  • Capture and display of each 720 x 240 video field stretched vertically to 720 x 80 without decimation.
  • Broadcast cable television tuner that supports NTSC or PAL signals.
  • Composite super VHS (SVHS) – type chip that decodes NTSC or PAL to YUV, with an interface to the SVGA chip set.
  • Composite SVHS-type chip that encodes data to NTSC or PAL, with a direct interface from the MPEG decoder.
  • Audio and video crossbar switching chips for interconnecting composite and SVHS inputs and outputs.
  • SVGA format that supports capture of YUV frame buffers for prioritized overlay and scaling with horizontal and vertical interpolation.
  • Merging of YUV video frames and SVGA video frames in the digital to analog converter (DAC) using chroma and color keying.
  • Controllable Macrovision video encoding of all composite video signals that are output.
  • Decoding of vertical blanking interval (VBI) data for NTSC format, including decoding of such information as closed captioning, from all composite inputs.
  • Encoding of NTSC VBI data (such as closed captioning or time codes) on all composite outputs.
  • Full driver support for the Microsoft® Windows® 98 operating system, including display driver and MPEG minidriver support.
  • Support for the output of audio from video sources to the line input of standard audio cards.


MPEG Decoder Recommended Configuration

The recommended video card for the MPEG decoder has the features listed in MPEG Decoder Requirements, plus:

  • Super Video Graphics Array (VGA) card capable of at least 800 x 600 x 24 bits per pixel with a 60 hertz refresh rate
  • Hardware acceleration compatible with the Microsoft® Direct3D® application programming interface (API)
  • Broadcast cable television tuner that supports NTSC, PAL, and SECAM in foreign and domestic stereo versions
  • Multiple composite and S-video jacks
  • Optional decoding of arbitrary vertical blanking interval (VBI) data for NTSC, such as Intercast, from all composite inputs


MPEG Decoder Interface

The interface between the video card for the MPEG decoder and the computer must have the following features:

  • Conformation to the Plug and Play specification as a PCI multiple-function device, providing separate spaces for super Video Graphics Array (SVGA), MPEG, and tuner functions
  • PCI bus mastering of audio and video MPEG data
  • Support for unaligned, odd byte transfers and scatter/gather memory access
  • Data buffering control, and provision of status information about data buffering
  • MPEG video decoding control, and provision of status information about MPEG video decoding
  • MPEG audio decoding control, and provision of status information about MPEG audio decoding
  • Cable television tuner control, and provision of status information about the cable television tuner
  • Control of and provision of status information about base-band video encoding and decoding
  • Control of and provision of status information about audio and video signal paths
  • Closed captioning input and output to audio and video signal paths


Analog Audio and Video Interconnections

If a video card supports analog connections, it should allocate connections of input sources to output sinks. Actual device connections vary somewhat based on consumer equipment. However, some connections of inputs to outputs are fixed, in that they interconnect specific devices, such as computer encoders to decoders. There are many possible input sources and output sinks for analog connections, such as a VCR for playing, a VCR for recording, a laser disk player, a camcorder, a game console box, a cable box, a cassette tape deck, and an FM audio tuner.

The following table shows suggested allocations of input lines to output lines for video and matches video input sources and output sinks with typical uses.


Integration Possibilities

Some of the possible audio and video card configurations:

  • Super Video Graphics Array (SVGA) card capable of PCI bus mastering, with an integrated MPEG-2 audio and video decoder, audio-video switching, and an ISA audio adapter compatible with SoundBlaster
  • SVGA card capable of PCI bus mastering, with an integrated MPEG-2 audio and video decoder, a SoundBlaster chip set, and audio-video switching

Note Either of these configurations works, but they have significant tradeoff issues in terms of the number of cards and the use of standardized cards. In general, it is better to have fewer cards and to use more standard cards.


Sound Card

The following sections describe the functionality of a sound card and the requirements it must meet to support Broadcast Architecture:

  • Sound Card Functionality
  • Sound Card Requirements
  • Sound Card Recommended Features


Sound Card Functionality

Sound components can be laid out on a separate sound card or integrated elsewhere. If sound is laid out on a separate card, the television and MPEG sound from the video card must be connected to the sound card's line-in port, and this sound must be controlled with the standard mixer interface in Microsoft® Windows® operating systems. The video card selects the television-related sound that is heard by users, and the mixer controls the television volume.

For game support on a broadcast client, sound components compatible with SoundBlaster that provide wave table synthesis are recommended. The sound components must be capable of a signal-to-noise ratio of 90 decibels, to maintain the audio quality of the digital broadcast network. It must be possible to use the sound-card circuitry independent of the digital broadcast audio output — for example, when the user tape-records a program while playing a video game.

Although sound and video display components can be laid out on separate cards, achieving the highest possible sound quality usually requires a digital connection between the video display card and the sound card.

For compatibility with digital video disk (DVD) audio, an audio decoder with compression to the AC-3 algorithm is recommended.


Sound Card Requirements

The sound card must have the following features:

  • Stereo
  • SoundBlaster compatibility
  • Signal-to-noise ratio of 90 decibels
  • Ability to satisfy the sound requirements of broadcast networks, including digital broadcast networks
  • Ability to mix audio from the computer, the current video source, and reference CD-ROMs


Sound Card Recommended Features

The recommended sound card for the MPEG decoder has the features listed in Sound Card Requirements, plus:

  • Wave-table synthesis
  • Separate mixer volume controls for tuner and MPEG audio output
  • Support for audio compressed to the AC-3 algorithm


Monitor

The following sections describe the attributes a monitor must possess and the requirements it must meet to support Broadcast Architecture:

  • Monitor Functionality
  • Monitor Requirements
  • Recommended Features for the Monitor

For information about video cards for Broadcast Architecture, see Video Card Recommendations


Monitor Functionality

Monitors for a broadcast client should have the following key attributes:

  • Support for the minimum resolution, currently 640 x 480. However, 800 x 600 resolution is recommended. Typical satellite digital broadcasters transmit main level and main profile MPEG-2 — the middle level of the five possible levels of MPEG-2 encoding for video data. That transmission level translates into 720 x 480 x 30 frames per second for NTSC. For PAL, this level translates into 720 x 576 x 25 frames per second. As a result of this transmission type, display decimation occurs at 640 x 480 resolution, which is why 800 x 600 resolution is strongly recommended.
  • Support for color gamma suitable for display of television and computer data. Diverting an MPEG stream to a computer monitor can cause color problems. These problems occur because the MPEG stream is encoded into an abstract color space, then decoded and sent to a computer monitor with a different, possibly greater color gamma than an NTSC display device.
  • Picture tube that is ideal for both computers and televisions. Such a picture tube has high luminance, analog super Video Graphics Array (SVGA) inputs, medium phosphor persistence, and a progressive scan of 60 hertz.
  • Good corner convergence.
  • Large screen size. For an optimal viewing experience, it is recommended that OEMs build large-screen monitors for Broadcast Architecture, 31 or 33 inches in size measured on the diagonal. However, the broadcast functionality works on any size computer monitor, leaving the ultimate configuration up to the OEMs.
  • Refresh rate of 60 hertz, or an integral multiple of 60 hertz, for any mode in which video is displayed. Most source video, such as NTSC or MPEG-2 video and film, is created or adjusted through temporal rescaling at a 3:2 ratio. This adjustment is performed expressly for 60 hertz television monitors. Further rescaling to other refresh rates, such as 72 hertz, introduces unacceptable motion artifacts, such as nonlinear screen motion. By using a refresh rate of 60 hertz or a multiple thereof, the monitor can be balanced with the monitor phosphor.

    For a flicker-free viewing experience, a medium-persistence phosphor should be used instead of a short-persistence phosphor. If the refresh rate is fixed at 120 hertz, the standard computer-monitor phosphors can be used.


Monitor Requirements

The monitor must have the following features:

  • 27-inch analog monitor that supports super Video Graphics Array (SVGA).
  • Minimum of 640 x 480 resolution, although 800 x 600 resolution is strongly recommended, with a refresh rate of 60 hertz.
  • Digitally controlled geometry: skew, rotate, pincushion, size, position.
  • Support for the Standard DDC2B VGA Monitor Identification Protocol.
  • Television-level brightness and phosphor luminance.
  • Maximum 0.75-millimeter dot pitch for true 800 x 600 resolution at a monitor size of 27 inches. Proportionally higher dot pitch can be provided in larger monitors.
  • Medium-persistence phosphors, optimized for 60 hertz with no noticeable flicker.
  • Compliance with Energy Star power savings standard.


Recommended Features for the Monitor

The recommended monitor has the features listed in Monitor Requirements, plus:

  • Front panel digital controls for contrast, brightness, and degauss.
  • Black packaging in styled plastic, suitable for consumer electronics.
  • 31-inch or larger analog monitor that supports super Video Graphics Array (SVGA). Such 31-inch monitors are often labeled at 33 inches.
  • Brightness and contrast controls revealed through a driver with a remote-control user interface, rather than through dials on the monitor case.
  • Host control of the monitor by using video cards and drivers compatible with Display Data Channel (DDC) requirements.
  • Adjustable color level appropriate to computer and video applications.
  • Ability to select between power at 120 volts alternating current (VAC) and 60 hertz and power at 240 VAC and 50 hertz.


Input Devices

For Broadcast Architecture, user input devices such as keyboards and mice change to accommodate their use in a living room setting. For example, keyboards can be used from the lap or a coffee table. Pointing devices can be hand-held, because a flat surface might not be available. Users can expect to use a remote control for channel surfing and other control of entertainment systems.

For further information on input devices suitable for Broadcast Architecture, see the following sections:

  • Connection to the Computer
  • Pointing Device/Remote Control
  • Keyboard
  • New Windows Keys


Connection to the Computer

In Broadcast Architecture, one receiver for all remote controls connects to the computer through the keyboard, mouse, and possibly joystick ports. Alternatively, the receiver can use a driver supplied by its hardware vendor that emulates these ports. This design allows each remote device to send data to each computer port. For example, a remote control might act as a mouse but might also send special keyboard scan codes. (For more information on these codes, see New Windows Keys.)

The following illustration shows the relationship between the remote controls, the receiver, and the computer.


Pointing Device/Remote Control

This section describes the functionality of a remote control and the requirements it must meet to support Broadcast Architecture.

Functionality for the Pointing Device/Remote Control

The integration of the pointing device and remote control are necessary so broadcast client users can navigate within computer applications, television programs, and television applications.

Consumers expect the pointing device/remote control to be very durable, with a long battery life. The type of pointing device used can be a directional keypad, a touch pad, a trackball, or some other device with similar functionality. The device must be hand-held. It can resemble a standard television remote control, with the addition of special keys to handle tasks for television and computer applications. For more information on these keys, see New Windows Keys.

Requirements for the Pointing Device/Remote Control

The pointing device/remote control must have the following features:

  • Mouse compatibility.
  • Long battery life.
  • Numeric keys. Touch tone labeling of numeric keys, as used on telephones, is suggested.
  • Television-related keys.
  • Navigation keys.
  • Compatibility with Simply Interactive PC (SIPC) remote-control guidelines, as described in SIPC Remote Control Design Guide.


Keyboard

This section describes the functionality of a keyboard and the requirements it must meet to support Broadcast Architecture.

Keyboard Functionality

The broadcast client keyboard has the same functionality as a standard computer keyboard, with some additional support for special keys. For more information on these keys, see New Windows Keys.

Consumers expect the keyboard to be very durable, with a long battery life. The keyboard must be capable of use from the lap or a coffee table. It can possibly be integrated with a pointing device. If the keyboard is so integrated, radio frequency and infrared create one-way signals to the computer. Therefore, status lights cannot be controlled on the keyboard.

Keyboard Requirements

The keyboard must:

  • Be wireless
  • Have a long battery life
  • Support Windows keys
  • Support television-related keys
  • Optionally, have an integrated pointing device


New Windows Keys

In Broadcast Architecture, keyboards and possibly other input devices have the following additional keys defined by Microsoft and implemented on the Microsoft® Natural® keyboard:

  • Windows (left)
  • Windows (right)
  • Application


Modem

The following sections describe the functionality of a modem and the requirements it must meet to support Broadcast Architecture:

  • Modem Functionality
  • Modem Requirements
  • Modem Recommendations


Modem Functionality

The Broadcast Architecture modem is a standard computer-compatible modem. Broadcast Architecture uses a modem for the following purposes:

  • To communicate billing information to service providers
  • To supply an interactive back channel
  • To provide dial-up connectivity for user applications, such as online services


Modem Requirements

At a minimum, the modem must support the following:

  • The Microsoft® Windows® 98 operating system, including Telephony Application Programming Interface (TAPI) and communications under the Microsoft® Win32® API. Most modems are compatible with Windows 98.

    A modem is a device used for data or fax transmission. In Windows 98, such a modem uses TAPI functions for call control and a combination of Win32 communications and Windows Sockets (WinSock) for data transactions.

    If Windows 98 does not support a modem, or the modem is not directly compatible with a supported model, the modem manufacturer must supply a driver for the modem. This driver must supply the Service Provider Interface (SPI) functions called by TAPI. However, from a practical standpoint, such drivers are rarely required. Most commercially available modems comply with Windows 98, because almost all comply closely with the international standards to use the UNIMODEM service provider included in Windows 98.

  • Dial-up to the billing center for the broadcast network. The modem must be able to communicate with the network billing center.
  • Dial-up connection by the user to online services and Internet service providers, such as the Microsoft® MSN™ online service. Communications speed of 9600 baud or higher is strongly recommended.

The modem must also provide the following capabilities as minimum requirements.

Modem Operation Modes

  • V.22 operation at 1200 baud
  • V.22 bis operation at 2400 baud
  • V.32 operation at 9600 baud

Modem Protocol

  • V.42 or V.42 bis

Modem Command Set

  • TIA-602 (Hayes compatible)

Connectors

The connection to the modem from the telephone line must be a standard RJ-11 jack.


Modem Recommendations

These optional features, although not required for modem operation, enhance the modem's value and customer satisfaction:

  • VoiceView technical support. This feature permits a voice call to be suspended while modem data exchanges take place. Generally, the primary users of this feature are telephone support personnel who want to interrogate or alter a customer's computer during a support call. Microsoft® Technical Support provides hardware and software tools to enable this feature for support of products for the Microsoft® Windows® 95 and Windows 98 operating systems.
  • Capability to send and receive faxes. If the modem has this feature, it should possess at least class 1 fax capability, and it should be able to originate and receive group 3 fax calls.
  • Packaging within the computer. While an external modem fulfills the minimum requirements for Broadcast Architecture, use of an internally mounted modem with an ISA bus simplifies user installation.


Related Hardware Information

This following sections describe additional recommendations for and information about support for Broadcast Architecture:

  • Video Card Recommendations
  • Displaying Interleaved Video on Progressive Monitors
  • Plug and Play Specifications


Video Card Recommendations

The following features are recommended for video cards supporting Broadcast Architecture on computers running the Microsoft® Windows® 98 operating system:

  • The standard Video Graphics Array (VGA) page frame and input/output (I/O) address resources should be static (that is, they cannot be relocated). The VGA basic input/output system (BIOS), if it exists separately, has the base address fixed at C000h.
  • A linear frame buffer should be used. It must be possible to relocate this buffer above the 16 megabyte boundary by using software, where applicable.
  • The card BIOS should meet the Display Data Channel 1(DDC1) host requirements documented in the Video Electronics Standards Association (VESA) DDC standard.
  • The video card ROM or virtual display driver should support the VESA BIOS extensions for power management (that is, the VESA BIOS Extensions/Power Management Standard).
  • Color ordering should be blue-green-red, with red as the high byte in displays supporting 16 bits per pixel and 24 bits per pixel. This ordering takes advantage of Windows 98 graphics capabilities.
  • The VGA BIOS, if it exists separately, should be configurable to two addresses at a minimum.
  • Any 24-bit or higher-bit displays should support downloadable entries in random access memory digital-to-analog converter (RAMDAC) format. Such support allows gamma correction in hardware.
  • The card should connect to a high-speed expansion bus, such as a PCI bus.
  • The card should be capable of supporting a monitor resolution of at least 800 x 600 by 8 bits per pixel.
  • The VGA video plane should support color keying.
  • If interrupt request 2 (IRQ2) is supported for VGA compatibility, it should be inactive when the computer is turned on. The computer should not claim IRQ2 as a static resource.
  • If extended display resources are used, the card should at a minimum be able to map the I/O addresses to seven locations and to disable them. However, this functionality is not necessary if the extended resource addresses are aliases of the standard VGA addresses.
  • A software-tunable crystal should be used, so that the 27-megahertz clock driving the MPEG chip can match the 27-megahertz clock from the broadcaster. Software drivers adjust the MPEG chip's frequency to match the rate captured by the broadcast receiver card. The range and number of steps for tunability are based on crystal accuracy and the requirements for NTSC color signals.
  • Both super Video Graphics Array (SVGA) and MPEG video clocks should be based on the same tunable crystal. This functionality prevents skipped or doubled frames due to slight differences in frequency between two different crystals.
  • For improved picture quality, the card should support horizontal and vertical interpolation as specified for Comité Consultatif International des Radiocommunications (CCIR) 601 video, 720 x 480 x YUV 4:2:2 screen resolution at 60 hertz.

For more detailed information about these features, refer to Hardware Design Guide for Microsoft® Windows® 95, available from Microsoft Press®.

Another important point to note is that both the MPEG decoder and the SVGA should be running at the same 60 frames per second to avoid beat frequency artifacts. One solution is to have the MPEG decoder and the SVGA share a single clock crystal tunable to a voltage-controlled crystal oscillator (VCXO). This crystal is run through a phased lock loop to generate both the 27 megahertz decoder clock and the SVGA pixel clocks. This clock tuning is necessary to synchronize the clocks to the MPEG encoder's time base of 60 hertz.


Displaying Interleaved Video on Progressive Monitors

The recommended way of deinterlacing and displaying NTSC video, or NTSC video encoded to MPEG, is to show each 720 x 240 x YUV field at 60 hertz on the SVGA screen. This display uses vertical and horizontal interpolation to get at least a full-frame image, that is a 720 x 480 x YUV image.

In this display, the alternating odd and even fields should be shown such that the odd fields are offset by one scan line from the even fields after scaling. Every other field is offset to get rid of image jitter when switching from one field to another. Cropping the extra top and bottom line of the offset fields is also recommended. This sequential display of offset odd and even fields on a 60-hertz (Hz), progressive scan SVGA monitor, running at 800 x 600 or greater resolution, simulates the way video fields appear on a traditional television screen that employs interlacing.

Each field is captured in the display buffer as a 720 x 240 x YUV, 2-byte video plane. The digital to analog converter (DAC) should perform interpolation. To do so, in the DAC a line store buffer that has first in, first out (FIFO) format is loaded. This buffer interpolates the lines of a field as the field is being output. Each video plane requires 345,600 bytes; two planes require 675 kilobytes of video memory.

Double buffering is required to prevent the user from seeing incomplete images, which occurs with a single buffer being updated as it is being output. The double buffers are swapped at the start of the vertical blanking interval (VBI) if and only if a new buffer has been filled with YUV data.

The fields are offset by one scan line, and the "extra" line on each field should be cropped. This cropping is performed because the extra line is only shown at 30 hertz, whereas the rest of the lines are refreshed at 60 hertz. The monitor should be run at 800 x 600 resolution at 60 hertz. This functionality means the fields are often stretched to fill the full display area but are sometimes shrunk, such as when video is displayed in a window.

Note that if a single horizontal line appears on only one field of the display surface, it flickers. All televisions have this problem with NTSC fields. The interlaced approach, though it produces this flicker, avoids various unpleasant artifacts such as feathering, tearing, and odd-field discarding.


Plug and Play Specifications

Plug and Play technology makes it possible for computer hardware and attached devices work together automatically. With Plug and Play, a user can simply attach a new device and begin working without restarting the computer, even while the computer is running. Plug and Play technology is implemented in hardware, in operating systems, and in support software such as drivers and basic input/output systems (BIOS).

With Plug and Play technology, users can easily add new capabilities to their computers, such as sound or fax, without concerning themselves with technical details or problems. For users of mobile computers who frequently change configurations with docking stations and have intermittent network connections and so on, Plug and Play technology easily manages their changing hardware configurations. For all users, Plug and Play reduces the time wasted on technical problems and increases productivity and satisfaction with computers.

A variety of Plug and Play technologies currently exist, including BIOS, ISA, small computer system interface (SCSI), integrated drive electronics (IDE) CD-ROM, LPT, Component Object Model (COM), Personal Computer Memory Card International Association (PCMCIA), and Plug and Play drivers. Specifications are available for many of these technologies. However, in a nutshell, each hardware device supporting Plug and Play must:

  • Be uniquely identifiable.
  • State the services it provides and the resources it requires.
  • Identify the driver that supports it.
  • Allow itself to be configured by software.

For Broadcast Architecture, there are several hardware units that can reside on a video card, receiver card, or motherboard. Cards can also combine one or more functions usually provided by separate units. For example, a video card may expose separate functions for super Video Graphics Array (SVGA), MPEG-2, and video tuning.

Cards that include one or more functions should identify themselves as multiple-function cards. This identification allows device drivers to be created for a single subfunction independent of location, rather than a monolithic driver being created for each card.

Separate functional components that should support Plug and Play include but are not limited to:

  • Broadcast receiver card
  • Microsoft Broadcast Data Network (MSBDN) decryptor
  • Video display
  • MPEG decoder
  • Analog tuner
  • Infrared remote control

Detailed Plug and Play information can be found on the Internet on the File Transfer Protocol (FTP) server ftp.microsoft.com in the directory developr/drg/plug-and-play, and in CompuServe's PLUGPLAY forum.


WebTV for Windows

Microsoft® WebTV® for Windows® is the user interface for Broadcast Architecture. It hosts several controls such as Microsoft® Internet Explorer and the Microsoft® ActiveX® control for video (the Video control). WebTV for Windows uses these controls to present data such as live video, Program Guide information, and enhancements. You can expand WebTV for Windows functionality by writing custom controls that interact with WebTV for Windows.

For more information, see the following topics:

  • About WebTV for Windows, which describes WebTV for Windows and the interfaces it exposes.
  • Using WebTV for Windows, which explains how to use the interfaces exposed by WebTV for Windows.
  • WebTV for Windows Reference, which provides detailed reference information.


About WebTV for Windows

Microsoft® WebTV® for Windows®, the Broadcast Architecture user interface, hosts an instance of Internet Explorer so as to display pages in Hypertext Markup Language (HTML). These pages contain further controls that provide such functionality as displaying video or pulling Program Guide information from the Guide database.

WebTV for Windows provides two main interfaces that enable your application to interact with it:

  • ITVViewer, the primary dispatch interface that exposes methods to programmatically control WebTV for Windows. For example, your application can use the ITVViewer::Tune method to tune WebTV for Windows to a new channel.
  • ITVControl, a notification interface that your application can implement and register with WebTV for Windows in order to receive event notifications, such as when WebTV for Windows tunes to a new channel.

In addition, Broadcast Architecture defines interfaces for objects that wrap episode or channel records in the Guide database. If you pass an object that wraps a Guide database record to WebTV for Windows, that object must implement one of the following interfaces:

  • IEPGItem, an abstract interface for an object that wraps a record in the Guide database. The IEPGEpisode interface inherits from IEPGItem.
  • IEPGEpisode, an interface for an object that wraps an episode record in the Guide database.

As an example of when your application needs to implement these interfaces, suppose you want to set a show reminder using the ITVViewer::SetReminder method. SetReminder takes an episode object as an input parameter. In this case, you must define, create, and initialize an episode object that implements the IEPGEpisode interface before you pass that episode object to SetReminder.

WebTV for Windows also includes a helper application, Tvwakeup.exe. For more information, see WebTV for Windows Helper Application.


WebTV for Windows Helper Application

Tvwakeup.exe is a helper application for WebTV for Windows. It runs in the background, handling keystrokes and remote control input used to launch WebTV for Windows. In addition, it responds to power management events and can be used to launch record reminder helper applications.

TVWakeup Launching WebTV for Windows from the Keyboard or a Remote Control

TVWakeup enables users to start WebTV for Windows from the keyboard or by using a remote control. To do this, TVWakeup runs in the background, listening for specific keys. If these are not handled by an application, TVWakeup handles them. The keystrokes that TVWakeup handles are Guide, Mute, TV, VolumeDown, and VolumeUp.

You can configure the keystrokes that TVWakeup.exe handles by changing the registry values set under the HKLM\Software\Microsoft\TV Services\Explorer\RemoteKeys\WakeupKeys registry key.

TVWakeup Handling Power Management Events

In addition to handling keyboard and remote control input, the copy of TVWakeup that runs in the background also handles power management events to ensure that television audio does not come on while the system is sleeping.

To prevent sound from coming on when the system is suspended or user is not present, Tvwakeup.exe mutes the master volume when it receives a QuerySuspend event as part of a WM_POWERBROADCAST message. When Tvwakeup.exe receives a OnSuspendFailed, SuspendCritical, or SuspendResume event, it resets the master volume to its original, pre-suspend, value.

As a side-effect, any program that needs to play sound while the system is in Resume Automatic state or when the user is not present, must explicitly un-mute the master volume.

To locate more information about WM_POWERBROADCAST messages and Advanced Configuration and Power Interface (ACPI), see Further Information on Television Services for the Client.

TVWakeup Launching WebTV for Windows from a Record Reminder Task

TVWakeup also serves as a helper application to launch WebTV for Windows when a show reminder runs. It is necessary to use TVWakeup to launch WebTV for Windows because the Task Scheduler will not let the system sleep while any process it has started is still running. To enable the system to go back to sleep after a show has finished recording, the Task Scheduler launches a copy of TVWakeup. TVWakeup starts WebTV for Windows, passes it any command-line parameters that TVWakeup received from the Task Scheduler. The copy of TVWakeup then exits, enabling the system to sleep once the recording is finished.

You can specify a custom helper application to use for record reminders instead of TVwakeup. To do this, set the path and filename of the helper application in the registry value, HKLM\Software\Microsoft\TVServices\Explorer\"HelperApp".


Using WebTV for Windows

You can take advantage of the technology behind Microsoft® WebTV® for Windows® by writing custom World Wide Web controls that are displayed by and interact with WebTV for Windows. You can also write a stand-alone application that either controls or monitors WebTV for Windows, or both.

If your application monitors WebTV for Windows, you must ensure that an instance of WebTV for Windows is running when your application starts. You must do so because your application cannot create a new instance of WebTV for Windows but instead must obtain a reference to a running instance. For more information on how to do this, see Getting a Pointer to WebTV for Windows.

Once your application has connected to WebTV for Windows, it can directly control WebTV for Windows using the methods of the ITVViewer interface. Your application can also register a sink for the ITVControl interface that enables your application to receive event notifications, such as when WebTV for Windows tunes to a new channel.

For details about working with WebTV for Windows, see the following topics:

  • Tuning WebTV for Windows
  • Using ITVViewer to Schedule a Show Reminder
  • Changing the Display Mode for WebTV for Windows
  • Registering an ITVControl Sink
  • Running WebTV for Windows from the Command Line

The Broadcast Architecture material includes a sample MFC application, Tvxsamp.exe, which demonstrates how to connect to and control WebTV for Windows. To locate Tvxsamp.exe, see Broadcast Architecture Sample Applications.

For additional information on the tasks involved in using WebTV for Windows with custom controls, see Creating Controls for WebTV for Windows.


Getting a Pointer to WebTV for Windows

Before your application can register a ITVControl notification sink or use the methods exposed by ITVViewer, it must first obtain a reference to the WebTV for Windows object. Your application cannot create a new instance of WebTV for Windows, so instead it must get a reference to a running instance by calling the GetActiveObject Automation function. To locate more information on GetActiveObject, see Further Information on Television Services for the Client.

Typically, your application gets this reference to WebTV for Windows during its initialization. Getting a WebTV for Windows reference at initialization ensures that WebTV for Windows is available before your application attempts to use it.

The following code obtains a reference to WebTV for Windows:

IUnknown *punk = NULL;
ITVViewer *ptvx = NULL;

//Get a reference to WebTV for Windows
GetActiveObject(CLSID_TVViewer, NULL, &punk);

// Check whether a reference to WebTV for Windows was returned
if (punk != NULL)
{
  'Get a reference to the ITVViewer interface
  punk->QueryInterface(IID_ITVViewer, (void **)&ptvx);

  'Release the WebTV for Windows object
  punk->Release();
}


Tuning WebTV for Windows

Once your application has a reference to WebTV for Windows, as discussed in Getting a Pointer to WebTV for Windows, it can call the ITVViewer::Tune method to cause WebTV for Windows to display a new channel.

The following line of code tunes WebTV for Windows to the specified channel and tuning space. In this example, the audio and video subchannel values are each specified as –1, which causes WebTV for Windows to use default values.

TVX->Tune(iTuningSpace, iChannel,-1,-1,NULL);

The ITVViewer interface offers two other tuning-related methods, ITVViewer::GetCurrentTuningInfo and ITVViewer::GetPreviousTuningInfo. GetCurrentTuningInfo returns information about the channel WebTV for Windows is currently tuned to, and GetPreviousTuningInfo returns information about the channel tuned to just previously.

The following example uses GetPreviousTuningInfo and Tune methods to implement a back button, which when clicked tunes WebTV for Windows to the previous channel.

void CMyApp::BackButton()
{
  long lTuningSpacePrev;
  long lChannelNumberPrev;
  long lAudioStreamPrev;
  long lVideoStreamPrev;
  CComBSTR bstrIPAddressPrev;

  TVX->GetPreviousTuningInfo(&lTuningSpacePrev, &lChannelNumberPrev,
            &lVideoStreamPrev, &lAudioStreamPrev, &bstrIPAddressPrev);

  TVX->Tune(lTuningSpacePrev, lChannelNumberPrev,
            lVideoStreamPrev, lAudioStreamPrev, bstrIPAddressPrev);
}


Using ITVViewer to Schedule a Show Reminder

Your application can create a show reminder in the Task Scheduler in the Microsoft® Windows® 98 operating system by calling the ITVViewer::SetReminder method. Calling SetReminder provides your application the same functionality that WebTV for Windows uses to set a show reminder.

There are three advantages to calling SetReminder, instead of using the alternative procedure described in Using IScheduledItems to Schedule a Show Reminder:

  • SetReminder causes WebTV for Windows to display a Set Reminder dialog box to the user. The user can use this dialog to edit the reminder, for example to make it run daily or weekly, change the start time, change it remind to record, and so on.
  • Reminders set using SetReminder can be viewed and administered from the WebTV for Windows user interface. In contrast, reminders set using IScheduledItems cannot be viewed in WebTV for Windows unless they meet the standards specified in Setting a Reminder That Appears in WebTV for Windows.
  • SetReminder automatically builds the show reference and adds the correct path for WebTV for Windows to the scheduled task. If you use IScheduledItems, your application must compute these values.
To set a show reminder using ITVViewer
  1. Obtain a pointer to an ITVViewer interface by getting a reference to an active instance of WebTV for Windows.
  2. Create an EPGEpisode object and set its values. For more information on doing so, see the IEPGEpisode interface topic.
  3. Call the ITVViewer::SetReminder method to set a reminder in the Task Scheduler.

Your application can delete a show reminder by using the ITVViewer::DeleteReminder method. For more information on the tasks involved in creating show reminders, see Scheduling Show Reminders.


Changing the Display Mode for WebTV for Windows

WebTV for Windows has two display modes, television and desktop. Television mode displays WebTV for Windows full-screen. Desktop mode displays WebTV for Windows as an application in a window.

Once your application has connected to WebTV for Windows, as described in Getting a Pointer to WebTV for Windows, you can call ITVViewer::SetTVMode to change the display mode from desktop to television or from television to desktop. The other display-related method WebTV for Windows provides is ITVViewer::IsTVMode, which returns a Boolean value indicating whether WebTV for Windows is currently displaying full-screen.

The following example combines these methods to implement an event handler for a button that toggles WebTV for Windows between full-screen and desktop display.

void CTVXSamp::ClickToggleModeButton()
{
  /* Check whether WebTV for Windows currently displays full-screen */
  if (TVX->IsTVMode())
  {
    /* If so, change to desktop mode */
    TVX->SetTVMode(false);
  }else{
    /* Otherwise, set WebTV for Windows to full-screen mode */
    TVX->SetTVMode(true);
  }
}


Registering an ITVControl Sink

To receive event notifications from WebTV for Windows, your application must first implement the ITVControl interface. Then, when your application runs, it must obtain a reference to WebTV for Windows, as described in Getting a Pointer to WebTV for Windows. After obtaining this reference, your application then registers its implementation of ITVControl as a notification sink.

Note Currently, WebTV for Windows only sends notifications to applications running in the same process as WebTV for Windows. An example of such an application is a Microsoft® ActiveX® control or component called from an enhancement page that is currently being displayed by WebTV for Windows.

This process is demonstrated in the following example. Note that m_xTVControl is a member variable implementation of ITVControl.

IUnknown *punk = NULL;
ITVViewer *ptvx = NULL;
HRESULT hr;
LPCONNECTIONPOINTCONTAINER pcpc = NULL;

//Get the ITVViewer interface
GetActiveObject(CLSID_TVViewer, NULL, &punk);

//If the interface is not found, return VARIANT_FALSE
if (punk == NULL)
  return VARIANT_FALSE;

punk->QueryInterface(IID_ITVViewer, (void **)&pvtx);
punk->Release();

//Get the IID_TVControl connection point
ptvx->QueryInterface(IID_IConnectionPointContainer, (void**)&pcpc);
if (pcpc == NULL)
{
  ptvx->Release();
  ptvx = NULL;
  return VARIANT_FALSE;
}

pcpc->FindConnectionPoint(IID_ITVControl, &pcpTVControl);
pcpc->Release();
if (pcpTVControl == NULL)
{
  ptvx->Release();
  ptvx = NULL;
  return VARIANT_FALSE;
}

//Ask the connection point to advise on m_xTVControl
hr = pcpTVControl->Advise(&m_xTVControl, &dwTVControl);
if (FAILED(hr))
{
  pcpTVControl->Release();
  pcpTVControl = NULL;
  ptvx->Release();
  ptvx = NULL;
  return VARIANT_FALSE;
}

ptvx->Release();
return VARIANT_TRUE;


Running WebTV for Windows from the Command Line

Typically you do not run WebTV for Windows from the command line. Instead you use the user interface built into WebTV for Windows and Windows 98. However, WebTV for Windows does support command-line arguments. You can use this syntax to run WebTV for Windows from the command-line or to create applications that control WebTV for Windows by sending command lines to the shell.

For more information, see the following topics:

  • Starting WebTV for Windows from the Command Line
  • Tuning WebTV for Windows from the Command Line
  • Toggling the Display Mode from the Command Line
  • Displaying the Program Guide from the Command Line
  • Displaying a Reminder from the Command Line
  • Displaying a Record Reminder from the Command Line


Starting WebTV for Windows from the Command Line

The following command line syntax starts WebTV for Windows. If WebTV for Windows is already running, this command does nothing.

You can also specify the channel that WebTV for Windows tunes to when it starts; for more information, see Tuning WebTV for Windows from the Command Line.

path Tvx.exe

where path is the path to the WebTV for Windows directory, typically C:\Program Files\TV Viewer. The location of this directory is stored in the ProductDir value under this registry key:

HKLM\Software\Microsoft\TV Services

If you are running the command line from the WebTV for Windows directory, you do not need to specify the path.

Examples

Both of the following command lines start WebTV for Windows. Note that the second example assumes that you are running the command line from the WebTV for Windows directory.

C:\Program Files\TV Viewer\Tvx.exe
Tvx.exe


Tuning WebTV for Windows from the Command Line

The following command line syntax tunes WebTV for Windows to the specified channel. If WebTV for Windows is not currently running this command line also starts WebTV for Windows.

<path>Tvx.exe tv:[//] <tuning_identifier>

The double back slash (//) before the tuning identifier is optional.

Where

<path>
The path to the WebTV for Windows directory, typically "C:\Program Files\TV Viewer". The location of this directory is stored in the ProductDir value under this registry key:

HKLM\Software\Microsoft\TV Services

If you are running the command line from the WebTV for Windows directory, you do not need to specify the path.

<tuning_identifer>
Specifies the channel or station to which WebTV for Windows should tune. This can be specified either by the channel number, the network call letters, or the station call letters.

Examples

The following three command lines all tune WebTV for Windows to channel 32. Note that the last two examples assume that you are running the command line from the WebTV for Windows directory.

C:\Program Files\TV Viewer\Tvx.exe tv:32
Tvx.exe tv:32
Tvx.exe tv://32

The next two command lines tune WebTV for Windows to the local station, KZZZ. The channel number associated with that station will vary in different broadcast areas.

Tvx.exe tv:KZZZ
Tvx.exe tv://KZZZ

The next two command lines tune WebTV for Windows to the national network station, MSNBC. The channel number associated with that station will vary in different broadcast areas.

Tvx.exe tv:MSNBC
Tvx.exe tv://MSNBC


Displaying the Program Guide from the Command Line

The following command line syntax causes WebTV for Windows to display the program guide. If WebTV for Windows is not currently running this command line also starts WebTV for Windows.

<path>Tvx.exe -g

Where

<path>
The path to the WebTV for Windows directory, typically "C:\Program Files\TV Viewer". The location of this directory is stored in the ProductDir value under this registry key:

HKLM\Software\Microsoft\TV Services

If you are running the command line from the WebTV for Windows directory, you do not need to specify the path.

Examples

The following line causes WebTV for Windows to display the Program Guide.

C:\Program Files\TV Viewer\Tvx.exe -g


Toggling the Display Mode from the Command Line

The following command line syntax toggles WebTV for Windows between windowed and full-screen display. If WebTV for Windows is not currently running, this command line also starts WebTV for Windows.

<path>Tvx.exe -t

Where

<path>
The path to the WebTV for Windows directory, typically "C:\Program Files\TV Viewer". The location of this directory is stored in the ProductDir value under this registry key:

HKLM\Software\Microsoft\TV Services

If you are running the command line from the WebTV for Windows directory, you do not need to specify the path.

Examples

The following line toggles the WebTV for Windows display mode. If WebTV for Windows is displaying as a windowed application, the command causes it to display full-screen, and vice versa.

C:\Program Files\TV Viewer\Tvx.exe -t


Displaying a Reminder from the Command Line

The following command line syntax causes WebTV for Windows to display a show reminder dialog box for the specified episode. If WebTV for Windows is not currently running, this command starts WebTV for Windows.

<path>Tvx.exe /b "<show_reference>" /u "<user_name>" /a "tvviewer!Remind!<duration>!"

Where

<path>
The path to the WebTV for Windows directory, typically "C:\Program Files\TV Viewer". The location of this directory is stored in the ProductDir value under this registry key:

HKLM\Software\Microsoft\TV Services

If you are running the command line from the WebTV for Windows directory, you do not need to specify the path.

<show_reference>
The show reference of the episode for which the reminder is set. For more information, see Show Reference Format. If the show reference is invalid, or the date specified in the show reference string is not the current date, WebTV for Windows does not display the reminder. If the show reference is valid, but is missing some pieces of information, WebTV for Windows attempts to fill in the missing information by matching the show reference to an episode in the Guide database.
<user_name>
The name of the user setting the reminder. For version 1.0 of Broadcast Architecture this is typically "GuestUser".
<duration>
The duration of the show, in minutes.

Note The Task Scheduler uses this command-line syntax when it calls WebTV for Windows to display a show reminder. For more information, see Show Reminder Format. To locate more information about the Task Scheduler feature of Windows 98, see Further General Information.

Examples

The following command line causes WebTV for Windows to display a show reminder for the show titled Time & Again.

C:\Program Files\TV Viewer\Tvx.exe /b "1997/11/4!0/0/0!23:30!
0!0!0!0!0!0!0!0!''!'MSNBC'!'Cable'!15!'Time & Again'"
/u "GuestUser" /a "tvviewer!Remind!30!"


Displaying a Record Reminder from the Command Line

The following command line syntax causes WebTV for Windows to display a record reminder dialog box for the specified episode and to tune to the specified channel when the episode starts. If WebTV for Windows is not currently running, this command starts WebTV for Windows.

<path>Tvx.exe /b "<show_reference>" /u "<user_name>" /a "tvviewer!Record!<duration>!"

Where

<path>
The path to the WebTV for Windows directory, typically "C:\Program Files\TV Viewer". The location of this directory is stored in the ProductDir value under this registry key:

HKLM\Software\Microsoft\TV Services

If you are running the command line from the WebTV for Windows directory, you do not need to specify the path.

<show_reference>
The show reference of the episode for which the reminder is set. For more information, see Show Reference Format. If the show reference is invalid, or the date specified in the show reference string is not the current date, WebTV for Windows does not display the reminder. If the show reference is valid, but is missing some pieces of information, WebTV for Windows attempts to fill in the missing information by matching the show reference to an episode in the Guide database.
<user_name>
The name of the user setting the reminder. For version 1.0 of Broadcast Architecture this is typically "GuestUser".
<duration>
The duration of the show, in minutes.

Note The Task Scheduler uses this command-line syntax when it calls WebTV for Windows to display a record reminder. For more information, see Show Reminder Format. To locate more information about the Task Scheduler feature of Windows 98, see Further General Information.

Examples

The following command line causes WebTV for Windows to display a record reminder for the show titled Time & Again.

C:\Program Files\TV Viewer\Tvx.exe /b "1997/11/4!0/0/0!23:30!
0!0!0!0!0!0!0!0!''!'MSNBC'!'Cable'!15!'Time & Again'"
/u "GuestUser" /a "tvviewer!Record!30!"


WebTV for Windows Reference

Microsoft® WebTV® for Windows® provides two dispatch interfaces, using which your application can interact with WebTV for Windows. Declared in Tvdisp.odl, these interfaces are:

  • ITVViewer, the primary dispatch interface that exposes methods that enable you to programmatically control WebTV for Windows. For example, using the ITVViewer::Tune method you can tune WebTV for Windows to a new channel.
  • ITVControl, a notification interface that you can implement in your control and register with WebTV for Windows in order to receive event notifications.

In addition, Broadcast Architecture defines the following interfaces that wrap items in the Guide database. Your application is responsible for declaring and implementing these interfaces in objects that it creates and passes to WebTV for Windows. These interfaces are:

  • IEPGItem, which is an abstract interface definition for an object that wraps Guide database information.
  • IEPGEpisode, which is an interface for an object that wraps the field data of an episode in the Guide database.

Registry Entries for WebTV for Windows lists the registry entries used by WebTV for Windows.


Registry Entries for WebTV for Windows

WebTV for Windows uses the following registry entries to store information. These values are stored in subkeys of this registry key:

HKLM\Software\Microsoft\TV Services\Explorer\

Name | Data type | Description
StartRecordingApp | String | Path and filename of an application. WebTV for Windows starts this application when recording starts. For a description of the command-line send to this application, see Setting a Record Reminder.
EndRecordingApp | String | Path and filename of an application. WebTV for Windows starts this application when recording ends. For a description of the command-line send to this application, see Setting a Record Reminder.
ClosedCaption | DWORD | Indicates whether closed captioning is enabled. If this value is 1, WebTV for Windows displays close captions. If this value is 0, it does not.
DistanceViewing | Binary | Indicates whether distance viewing is enabled. If this value is 0, WebTV for Windows is configured for viewing on a desktop system. If this value is 1, WebTV for Windows is configured for distance viewing. When WebTV for Windows is configured for distance viewing, another registry entry, NTSC is added.
Enhancements | DWORD | Indicates whether enhancements are enabled. If this value is 1, WebTV for Windows displays enhancements. If this value is 0, it does not.
EPGChannel | Binary | Indicates the broadcast channel on which WebTV for Windows displays the Program Guide.
NTSC | Binary | Indicates the viewing platform used for distance viewing. If this value is 1, WebTV for Windows is configured for a standard television. If this value is 0, WebTV for Windows is configured for a large screen monitor. This value is not used if DistanceViewing is zero.
OutputDevice | String | String value that indicates the name of an output device. If this value is present WebTV for Windows attempts to find the device and set full-screen video output to it. This video output is in addition to the WebTV for Windows display of video on the screen. This registry value can be used to set video output to a device such as a VCR. For example, if a VCR is installed with a device name of "AuxOut", setting OutputDevice to "AuxOut" would cause WebTV for Windows to send video output to the VCR.
HelperApp | String | Optional entry that contains the path and filename of a helper application that launches WebTV for Windows when a record reminder runs. If this value is not set, the system uses C:\Program Files\TV Viewer\TVWakeup.exe.


ITVViewer

The ITVViewer interface provides methods that your application can use to programmatically control an instance of WebTV for Windows.

When to Implement

You do not need to implement this interface. It is implemented by WebTV for Windows as the primary dispatch interface.

When to Use

Your application can use this interface to call methods that programmatically control an instance of WebTV for Windows.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces
AddRef | Increments reference count
Release | Decrements reference count

ITVViewer | Description
SetTVMode | Sets WebTV for Windows to either television or desktop display mode.
IsTVMode | Returns a value indicating the display mode that WebTV for Windows is currently using.
IsChannelBarUp | Returns a value indicating whether the TV banner is currently displayed.
IsModalDialogUp | Returns a value indicating whether a modal dialog box is currently displayed.
IsLoaderActive | Returns a value indicating whether a Guide database loader is running.
GlobalStartTime | Returns the earliest start time of any episode listed in the Guide database.
GlobalEndTime | Returns latest end time of any episode listed in the Guide database.
WantKeys | Sets whether WebTV for Windows control traps keystrokes or passes them through to the focus window.
Tune | Tunes WebTV for Windows to the specified channel and tuning space.
GetCurrentTuningInfo | Returns information about the channel to which WebTV for Windows is currently tuned.
GetPreviousTuningInfo | Returns information about the last channel to which WebTV for Windows was tuned.
SetReminder | Sets a show reminder in the Task Scheduler for the specified episode.
HasReminder | Returns a value that indicates whether a reminder is set for the specified episode.
DeleteReminder | Deletes a reminder for the specified episode.
HasEnhancement | Returns a value that indicates whether the specified episode has enhancements.
IsCC | Returns a value that indicates whether the broadcast has closed captioning.

Remarks

Because WebTV for Windows does not support the IClassFactory COM interface, you cannot create a new instance of WebTV for Windows. Instead, you must acquire a pointer to a running instance. For more information on how to do this, see Getting a Pointer to WebTV for Windows.

ITVViewer is derived from the IDispatch interface. To locate more information on IDispatch, a Component Object Model (COM) interface, see Further Information on Television Services for the Client.

For more information on the methods that ITVViewer contains but that are reserved for future use, see Reserved Methods in ITVViewer.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVControl


Reserved Methods in ITVViewer

The ITVViewer interface contains the following methods that are not currently supported and that are reserved for future use:

  • ITVViewer::ChannelList
  • ITVViewer::ViewerID


ITVViewer::DeleteReminder

The DeleteReminder method deletes either a record reminder or all reminders for the specified episode, or for recurring episodes.

HRESULT DeleteReminder(
  IUnknown *pEpisode,
  VARIANT_BOOL bRecord
);

Parameters

pEpisode
Pointer to the IEPGEpisode interface for the episode.
bRecord
Boolean value that specifies whether to delete a record reminder or all reminders for the specified episode. This parameter can be one of the following values.
Value | Meaning
VARIANT_TRUE | Delete the record reminder. Each episode can have only one record reminder set.
VARIANT_FALSE | Delete all reminders. In other words, delete the record reminder and the regular reminder.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

Remarks

If the user has set a reminder for a weekly television broadcast this method deletes all of the reminders. If overlapping reminders exist, this method deletes only the first reminder for the specified episode.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::SetReminder


ITVViewer::GetCurrentTuningInfo

The GetCurrentTuningInfo method returns information about the channel to which WebTV for Windows is currently tuned.

HRESULT GetCurrentTuningInfo(
  long *lTuningSpace,
  long *lChannelNumber,
  long *IVideoStream,
  long *lAudioStream,
  BSTR *pbsIPAddress
);

Parameters

lTuningSpace
Pointer to a long that receives the tuning space identifier of the current channel.
lChannelNumber
Pointer to a long that receives the current channel number.
IVideoStream
Pointer to a long that receives the identifier of the current video stream.
lAudioStream
Pointer to a long that receives the identifier of the current audio stream.
pbsIPAddress
Pointer to a BSTR that receives the current IP address WebTV for Windows is monitoring for triggers. This address should be in the format xxx.xxx.xxx.xxx\t yyy, where xxx.xxx.xxx.xxx specifies the IP address, and yyy specifies the port. The IP address and the port values are separated by a tab character, for example 255.255.255.255\t999.

This parameter must be initialized to NULL when you pass it; otherwise, the method returns an OLE exception.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::GetPreviousTuningInfo, ITVViewer::Tune


ITVViewer::GetPreviousTuningInfo

The GetPreviousTuningInfo method returns information about the channel to which WebTV for Windows was previously tuned.

HRESULT GetPreviousTuningInfo(
  long *lTuningSpace,
  long *lChannelNumber,
  long *IVideoStream,
  long *lAudioStream,
  BSTR *pbsIPAddress
);

Parameters

lTuningSpace
Pointer to a long that receives the tuning space identifier of the previous channel.
lChannelNumber
Pointer to a long that receive the channel number of the previous channel.
IVideoStream
Pointer to a long that receives the identifier of the previous video stream.
lAudioStream
Pointer to a long that receives the identifier of the previous audio stream.
psbIPAddress
Pointer to a BSTR that receives the IP address on which triggers were sent for the previous channel. This address should in the format xxx.xxx.xxx.xxx\t yyy, where xxx.xxx.xxx.xxx specifies the IP address, and yyy specifies the port. The IP address and the port values are separated by a tab character, for example 255.255.255.255\t999.

This parameter must be initialized to NULL when you pass it to the method; otherwise. the method returns an OLE exception.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

Remarks

This method only returns information about the single channel tuned to just previous to the current channel. It cannot be used to retrieve information about channels tuned to before that.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::GetCurrentTuningInfo, ITVViewer::Tune


ITVViewer::GlobalEndTime

The GlobalEndTime method retrieves the date and time of the latest end time of any episode in the Guide database.

HRESULT GlobalEndTime(
  DATE *pdate
);

Parameters

pdate
Pointer to a DATE structure that receives the latest end time.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::GlobalStartTime


ITVViewer::GlobalStartTime

The GlobalStartTime method retrieves the date and time of the earliest start time of any episode in the Guide database.

HRESULT GlobalStartTime(
  DATE *pdate
);

Parameters

pdate
Pointer to a DATE structure to receive the global start time.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::GlobalEndTime


ITVViewer::HasEnhancement

The HasEnhancement method checks the specified episode to see whether it has enhancements.

HRESULT HasEnhancement(
  IUnknown *pEpisode
  VARIANT_BOOL *bEnhanced
);

Parameters

pEpisode
Pointer to the IEPGEpisode interface of the episode.
bEnhanced
Pointer to a boolean variable that receives the enhancement information. This can be one of the following values.
Value | Meaning
VARIANT_TRUE | The episode has enhancements.
VARIANT_FALSE | The episode does not have enhancements.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::HasReminder, IEPGEpisode


ITVViewer::HasReminder

The HasReminder method returns a value specifying whether a reminder is set for the specified episode.

HRESULT HasReminder(
  IUnknown *pEpisode,
  VARIANT_BOOL bRecord
  VARIANT_BOOL *bReminder
);

Parameters

pEpisode
Pointer to the IEPGEpisode interface of the episode. Your application must implement an episode object that supports IEPGEpisode. Your application initializes the object's properties with the episode data.
bRecord
Boolean value that indicates the type of reminder to look for. This can be one of the following values.
Value | Meaning
VARIANT_TRUE | A reminder to record the show.
VARIANT_FALSE | A reminder to watch the show.

bReminder
Pointer to a boolean variable that receives the reminder information. This can be one of the following values.
Value | Meaning
VARIANT_TRUE | A reminder is set for the episode.
VARIANT_FALSE | No reminder is set for the episode.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::HasEnhancement, IEPGEpisode


ITVViewer::IsCC

The IsCC method returns a value that indicates closed captioning is enabled.

HRESULT HasEnhancement(
  VARIANT_BOOL *pbCC
);

Parameters

pbCC
Pointer to a boolean variable that receives the closed captioning information. This can be one of the following values.
Value | Meaning
VARIANT_TRUE | Closed captioning is enabled..
VARIANT_FALSE | Closed captioning is disabled.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::IsChannelBarUp, ITVViewer::IsLoaderActive, ITVViewer::IsModalDialogUp, ITVViewer::IsTVMode, ITVControl::GetCC


ITVViewer::IsChannelBarUp

The IsChannelBarUp method returns a value that specifies whether the WebTV for Windows menu bar is currently displayed.

HRESULT IsChannelBarUp(
  VARIANT_BOOL *pfBarUp
);

Parameters

pfBarUp
Pointer to a boolean variable that receives the TV banner information. This is the banner that appears at the top of WebTV for Windows. This can be one of the following values.
Value | Meaning
VARIANT_TRUE | The TV banner is currently displayed.
VARIANT_FALSE | The TV banner is hidden.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::IsCC, ITVViewer::IsLoaderActive, ITVViewer::IsModalDialogUp, ITVViewer::IsTVMode


ITVViewer::IsLoaderActive

The IsLoaderActive method returns a value indicating whether a Guide database loader application is running.

HRESULT IsLoaderActive(
  VARIANT_BOOL *pfLoaderActive
);

Parameters

pfLoaderActive
Pointer to a boolean variable that receives the loader activity information. This can be one of the following values.
Value | Meaning
VARIANT_TRUE | A Guide database loader is running.
VARIANT_FALSE | No Guide database loader components are running.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::IsCC, ITVViewer::IsChannelBarUp, ITVViewer::IsModalDialogUp, ITVViewer::IsTVMode


ITVViewer::IsModalDialogUp

The IsModalDialogUp method returns a value specifying whether a modal dialog box is currently displayed.

HRESULT IsModalDialogUp(
  VARIANT_BOOL *pfModalUp
);

Parameters

pfModalUp
Pointer to a boolean variable that receives the information on dialog box display. This can be one of the following values.
Value | Meaning
VARIANT_TRUE | A modal dialog box is currently displayed.
VARIANT_FALSE | No modal dialog boxes are currently displayed.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::IsCC, ITVViewer::IsChannelBarUp, ITVViewer::IsLoaderActive, ITVViewer::IsTVMode


ITVViewer::IsTVMode

The IsTVMode method returns a value specifying whether WebTV for Windows currently displays in television or desktop mode.

HRESULT IsTVMode(
  VARIANT_BOOL *pfTVmode
);

Parameters

pfTVmode
Pointer to a boolean variable that receives the television mode information. This can be one of the following values.
Value | Meaning
VARIANT_TRUE | WebTV for Windows is currently displaying in TV, or full-screen, mode.
VARIANT_FALSE | WebTV for Windows is currently displayed in desktop, or window, mode.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::IsCC, ITVViewer::IsChannelBarUp, ITVViewer::IsLoaderActive, ITVViewer::IsModalDialogUp, ITVViewer::SetTVMode


ITVViewer::SetReminder

The SetReminder method sets a reminder for the specified episode. The reminder is set as a task in the Task Scheduler.

HRESULT SetReminder(
  IUnknown *pEpisode,
  VARIANT_BOOL bRecord
);

Parameters

pEpisode
Pointer to an IEPGEpisode interface. Your application must implement an episode object that supports IEPGEpisode. Your application initializes the object's properties with data that reflects the episode to schedule.
bRecord
Boolean value that specifies whether the reminder should be a record reminder. This can be one of the following values.
Value | Meaning
VARIANT_TRUE | Set a reminder to record a broadcast.
VARIANT_FALSE | Set a reminder to watch a broadcast.

Remarks

If the reminder is a record reminder, you should use the Task Scheduler to set the TASK_FLAG_SYSTEM_REQUIRED flag for the reminder. This causes WebTV for Windows to tune to the channel even if the system is sleeping. Otherwise, if the system is sleeping, WebTV for Windows will not wake up to run the record reminder.

In addition, if the record reminder has an application associated with it that automates tuning the VCR this application should be specified in the StartRecordingApp and/or EndRecordingApp values under this registry key:

HKLM\Software\Microsoft\TV Services\Explorer\

The TASK_FLAG_SYSTEM_REQUIRED flag should not be set for standard show reminders. Version 1.0 of Broadcast Architecture does not handle show reminders that go off while the system is sleeping.

For more information see Setting a Show Reminder and Setting a Record Reminder.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::DeleteReminder, Setting a Show Reminder, Setting a Record Reminder.


ITVViewer::SetTVMode

The SetTVMode method displays WebTV for Windows in the specified mode, either television or desktop.

HRESULT SetTVMode(
  VARIANT_BOOL fTVMode
);

Parameters

fTVMode
Boolean value that indicates the mode. This can be one of the following values.
Value | Meaning
VARIANT_TRUE | Television mode. The control displays full-screen.
VARIANT_FALSE | Desktop mode. The control displays in a desktop window.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::IsTVMode


ITVViewer::Tune

The Tune method tunes the WebTV for Windows display to the specified channel.

HRESULT Tune(
  long lTuningSpace,
  long lChannelNumber,
  long lVideoStream,
  long lAudioStream,
  BSTR bsIPStream
);

Parameters

lTuningSpace
Tuning space of the input. Typically, each input device uses a separate tuning space.
lChannelNumber
Channel number.
lVideoStream
Video input stream. If you pass – 1, WebTV for Windows uses the default video stream as defined by the broadcast content provider. To access alternate video streams, pass the video stream identifier specified by the content provider.
lAudioStream
Audio input stream. A single video input stream may have several audio streams associated with it. If you pass in a value of – 1, WebTV for Windows uses the default audio stream, as defined by the broadcast content provider.

This functionality is useful because, for example, a television station with a Hispanic audience might define a Spanish-language audio stream as the default but also define an English-language version as an alternate audio stream. To access the English-language version in this case, an application passes the audio stream identifier that the content provider specifies for that version.

bsIPStream
String that contains information about the IP stream used by triggers. This string must be in the format "xxx.xxx.xxx.xxx yyy.yyy.yyy.yyy:zzz preloadURL&overlayCSS", where xxx.xxx.xxx.xxx specifies the netcard address, yyy.yyy.yyy.yyy specifies the announcement IP address, zzz specifies the announcement port, preloadURL specifies the preload URL and overlayCSS specifies the overlay style sheet. For example: "255.255.255.255 123.25.433.1:1701 basepage.htm&basestyle.css"

The preloadURL and overlayCSS parameters are optional, and can be left out of the string. For example, "255.255.255.255 123.25.433.1:1701".

If no trigger stream exists, this value is set to NULL.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.

See Also

ITVViewer::GetCurrentTuningInfo, ITVViewer::GetPreviousTuningInfo, ITVControl::Tune


ITVViewer::WantKeys

The WantKeys method sets whether WebTV for Windows traps keystrokes or passes them to the window with focus.

HRESULT WantKeys(
  int nKeys
);

Parameters

nKeys
A flag that specifies which type of key events WebTV for Windows passes to the focus window. This can be a combination of the following values.
Value | Meaning
keNumKeys | WebTV for Windows passes number key (0-9) events to the focus window.
kePageKeys | WebTV for Windows passes page key (PageUp/PageDown) events to the focus window.
keNoKeys | WebTV for Windows traps both page and number key events.
keChannelKeys | WebTV for Windows passes channel key events to the focus window.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

Remarks

The default behavior is for WebTV for Windows to trap number keys and use them as input to change the channels.

The nKeys flags may be ORed together. For example, the following call to WantKeys causes WebTV for Windows to pass both number keys and PageUp/PageDown keys to the focus window.

WantKeys ( keNumKeys | kePageKeys );

Because WantKeys causes WebTV for Windows to send key events to the focus window, a control should ensure that it has focus before it calls this method. Otherwise, the key events will be sent to the focus application, not the control, possibly resulting in unpredictable behavior.

The WebTV for Windows behavior, whether it traps or forwards key events, is set by the most recent call to WantKeys. Furthermore, the key event behavior is set for all controls on the broadcast client. In other words, you cannot cause WebTV for Windows to forward key events to some controls and not others. For example, if control control A calls WantKeys, setting nKeys to keNumKeys, and then control B calls WantKeys, setting nKeys to keNoKeys, WebTV for Windows will use the most recent key event setting, keNoKeys, and neither control will receive key events.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: Included as a resource in tvx.exe.
Unicode: Yes.


ITVControl

The ITVControl interface is a sink that enables objects to receive notifications of changes in the state of WebTV for Windows.

When to Implement

Implement ITVControl if you are developing a television-aware control that resides in the WebTV for Windows container, or if your control needs notification of WebTV for Windows events.

Note Currently, WebTV for Windows only sends notifications to applications running in the same process as WebTV for Windows. An example of such an application is a Microsoft® ActiveX® control or component called from an enhancement page that is currently being displayed by WebTV for Windows.

When to Use

WebTV for Windows calls the methods of ITVControl to notify registered objects of a change in the WebTV for Windows state.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces
AddRef | Increments reference count
Release | Decrements reference count

ITVControl | Description
OnIdle | Advises that idle-time processing is available.
Tune | Advises that WebTV for Windows has tuned to a new channel.
TearDown | Advises that WebTV for Windows is closing the current World Wide Web page.
SyncEvent | Advises that a sync event has occurred.
EpisodeStatusChanged | Advises that the status of an episode has changed.
PowerChange | Advises that the system power is turning on or turning off.
OnTVFocus | Advises that WebTV for Windows has gotten focus.
SetOutput | Advises that the control should set an additional output device, for example a VCR.
GetCC | Returns the closed-captioning status of the control.
SetCC | Advises that the closed-captioning status has changed in WebTV for Windows.
EnableVideo | Advises that the control that the status of the video display has changed.

Remarks

After your object has registered a sink, it should advise on the ITVControl connection point when it is user interface–activated, able to interact with the user, and revoke the connection point when it is user interface–deactivated, or hidden. In other words, the control should advise when it receives a IOleObject::DoVerb method call specifying the value OLEVERB_UIACTIVATE, OLEVERB_INPLACEACTIVATE, or OLEVERB_PRIMARY, and the control should revoke the connection point when it receives a IOleObject::DoVerb call specifying the value OLEVERB_HIDE.

To locate more information about the IOleObject interface and the DoVerb method, see Further Information on Television Services for the Client.

ITelevisionServices is derived from the IDispatch interface. To locate more information on IDispatch, a Component Object Model (COM) interface, see Further Information on Television Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: User-defined.
Unicode: Yes.

See Also

ITVViewer


ITVControl::EnableVideo

The EnableVideo method advises that the status of the video display has changed.

HRESULT EnableVideo(
  VARIANT_BOOL bEnable,
  int iReason
);

Parameters

bEnable
A boolean value that indicates whether the control should display video. If bEnable is VARIANT_TRUE, video should be enabled. If bEnable is VARIANT_FALSE, video should be disabled.
iReason
If bEnable is VARIANT_FALSE, this parameter contains a value indicating the reason that video is disabled. If bEnable is VARIANT_TRUE, this parameter is not used. The supported values are listed in the following table:
Value Description
kePrimaryMonitor Video is not supported off of the primary monitor.

This can occur in a multiple-monitor environment when the user drags the WebTV for Windows window from the primary monitor to a secondary montor. Because video is not supported on secondary monitors, it is disabled.

Return Values

WebTV for Windows ignores the value returned by this method.

Remarks

WebTV for Windows calls EnableVideo on all registered ITVControl sinks when the status of video display changes. For example, in a multiple-monitor environment if the user drags the WebTV for Windows window off of the primary monitor, video is no longer available because video is not supported on secondary monitors. In that case, WebTV for Windows calls EnableVideo(FALSE, kePrimaryMonitor) on all registered controls to inform them that video is disabled. The iReason parameter contains extended information explaining the reason that video was disabled. The control can then handle the event, presenting a message box to the user explaining why video was lost. When the WebTV for Windows window is moved back onto the primary monitor and video support is regained, WebTV for Windows calls EnableVideo( VARIANT_TRUE, 0 ) on all registered controls to advise them that video is re-enabled.

If a control registers an ITVControl sink while video is disabled, WebTV for Windows immediately sends an EnableVideo(FALSE, iReason) notification to the control. If the control does not receive this notification, it should assume that video is enabled. WebTV for Windows does not send a EnableVideo(TRUE, 0) message to newly registered controls. WebTV for Windows only calls EnableVideo(TRUE, 0) when video is re-enabled following a previous call to EnableVideo(FALSE, iReason).

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: User-defined.
Unicode: Yes.


ITVControl::EpisodeStatusChanged

The EpisodeStatusChanged method advises that the status of an episode has changed.

HRESULT EpisodeStatusChanged(
  int iChange,
  IUnknown *pEpisode
);

Parameters

iChange
Change identifier. This identifier can be one of the following values.
Value | Meaning
keReminderStatus | Specifies that a reminder has either been set or deleted for the episode.
kePurchaseStatus | Reserved.
keDSSEmailStatus | Reserved.
keEnhancementStatus | Specifies that the enhancement status has changed. Typically, this indicates that an episode or channel enhancement is now available.

pEpisode
Pointer to the IEPGEpisode interface of an EPGEpisode object that contains information about the episode whose status has changed.

Return Values

WebTV for Windows ignores the value returned by this method.

Remarks

WebTV for Windows calls this method.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGEpisode


ITVControl::GetCC

The GetCC method retrieves the closed-captioning status of the control.

HRESULT GetCC(
  VARIANT_BOOL *bCC
);

Parameters

bCC
Pointer to a boolean variable that receives the closed-captioning status of the control. This can contain one of the following values.
Value | Meaning
VARIANT_TRUE | The control is in closed-captioning mode.
VARIANT_FALSE | The control is not in closed-captioning mode.

Return Values

WebTV for Windows ignores the value returned by this method.

Remarks

WebTV for Windows calls this method.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: User-defined.
Unicode: Yes.

See Also

ITVViewer::IsCC, ITVControl::SetCC


ITVControl::OnIdle

The OnIdle method advises that idle-time processing is available.

HRESULT OnIdle(
  VARIANT_BOOL *pbIdle
);

Parameters

pbIdle
Pointer to a boolean that contains the idle information. This can contain one of the following values.
Value | Meaning
VARIANT_TRUE | The object needs additional idle processing time.
VARIANT_FALSE | The object does not additional idle processing time.

Return Values

WebTV for Windows ignores the value returned by this method.

Remarks

WebTV for Windows calls OnIdle when it receives an on idle message from the operating system. Calling OnIdle enables registered controls to perform idle-time processing.

When the operating system has idle time available, it calls the OnIdle method for the main windows of the running applications. If an application indicates it needs more idle time by setting *pbIdle to VARIANT_TRUE, the system calls the OnIdle method for that application again during the next idle loop. Otherwise, the Microsoft® Windows® 98 operating system does not call OnIdle for that application until after the application processes another normal message.

When the system calls the WebTV for Windows implementation of OnIdle, it in turn calls the ITVControl::OnIdle method implemented by any registered sinks. If your application sets *pbIdle to VARIANT_TRUE, indicating that it needs additional idle time processing, WebTV for Windows passes this value to the operating system. Passing this value causes all controls registered with WebTV for Windows to get another OnIdle call during the next system idle loop. The frequency of idle calls depends on system activity.

For more information about idle processes, see Further Information on Television Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: User-defined.
Unicode: Yes.


ITVControl::OnTVFocus

The OnTVFocus method advises that WebTV for Windows has gotten focus.

HRESULT OnTVFocus(void);

Parameters

None.

Return Values

WebTV for Windows ignores the value returned by this method.

Remarks

WebTV for Windows calls this method when it gets focus. Your control can use this method to force focus to a specific window.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: User-defined.
Unicode: Yes.


ITVControl::PowerChange

The PowerChange method advises that broadcast client is turning on or turning off.

HRESULT PowerChange(
  VARIANT_BOOL bPowerOn,
  VARIANT_BOOL bUIAllowed
);

Parameters

bPowerOn
Boolean value that specifies whether the power is turning on or off, which can be one of the following.
Value | Meaning
VARIANT_TRUE | The system power is turning on.
VARIANT_FALSE | The system power is turning off.

bUIAllowed
Boolean value that specifies whether the control can present a user interface to the viewer. For example, when power is shut off, a control might query the user whether it should save data to disk. This value can be one of the following.
Value | Meaning
VARIANT_TRUE | The control can present a user interface.
VARIANT_FALSE | The control cannot present a user interface.

Return Values

If the power is turning on, WebTV for Windows ignores the return value.

If the power is turning off, your control should return one of the following values.

Value | Meaning
S_OK | The system can power off.
S_FALSE | The system should not power off. If the bUIAllowed parameter is VARIANT_FALSE, the system does not honor the control's request for power to stay on.

Remarks

WebTV for Windows calls this method when the power status of the system changes.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: User-defined.
Unicode: Yes.


ITVControl::SetCC

The SetCC method advises that the closed-captioning status has changed in WebTV for Windows.

HRESULT SetCC(
  VARIANT_BOOL bCC
);

Parameters

bCC
Boolean value that indicates the closed captioning state, which can be one of the following.
Value | Meaning
VARIANT_TRUE | Closed captioning is turned on.
VARIANT_FALSE | Closed captioning is turned off.

Return Values

WebTV for Windows ignores the value returned by this method.

Remarks

WebTV for Windows calls this method when the closed-captioning status of WebTV for Windows changes.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: User-defined.
Unicode: Yes.

See Also

ITVViewer::IsCC, ITVControl::GetCC


ITVControl::SetOutput

The SetOutput method advises that the control should set an additional output device, for example a VCR.

HRESULT SetOutput(
  BSTR bsDeviceName
);

Parameters

bsDeviceName
Value that specifies the name of the output device to set. WebTV for Windows looks in the registry for a device that matches this name.

Return Values

WebTV for Windows ignores the value returned by this method.

Remarks

WebTV for Windows calls this method so that the control can set an additional output device, in addition to regular video. For example, WebTV for Windows can call this method to request that a control set VCR output.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: User-defined.
Unicode: Yes.


ITVControl::SyncEvent

The SyncEvent method advises that a synchronization event has occurred.

HRESULT SyncEvent(
  int iEvent,
  BSTR pParm1,
  BSTR pParm2
);

Parameters

iEvent
WebTV for Windows event that occurred, which can be any of the following.
Event | Description
keCurrentViewerChannelListChange | A current viewer's channel lineup has changed. Controls should refresh any cached channel information.
EPGLDR_ACTIVE_COMMIT_ENDING | A Guide database loader has finished committing data to the database. Controls can now access the database and should refresh any cached data.
EPGLDR_ACTIVE_COMMIT_STARTING | A Guide database loader has begun to commit changes to the database. Controls should not access the database until the keEpgLdrActiveCommitEnding event is sent.
EPGLDR_ENDING | A Guide database loader has stopped running.
EPGLDR_PASSIVE_COMMIT_ENDING | A Guide database loader has finished committing data to the database. Controls can now access the database but do not need to refresh any cached data.
EPGLDR_PASSIVE_COMMIT_STARTING | A Guide database loader has begun to commit data to the database. Controls should not access the database until the keEpgLdrPassiveCommitEnding event is sent.
EPGLDR_STARTING | A Guide database loader has begun running. Controls can still access data in the database.
keSysTimeChange | The system time has been updated.
keTimeRangeChange The range of time displayed in the electronic program guide has changed outside of a loader update operation.

Controls that cache program guide information should refresh their data when they receive this event. Note that this event is not sent as part of a loader update operation. Controls that receive a loader update event should not wait for a keTimeRangeChange event to refresh their data.
keViewerChange | Reserved.
keViewerLogin | Reserved.

Note Note that the loader events, those that start with EPGLDR_ are defined in Epgldrx.h.

pParm1
New viewer name, if a keViewerChange event has been sent. Other events do not use this parameter.
pParm2
New viewer password, if a keViewerChange event has been sent. Other events do not use this parameter.

Return Values

WebTV for Windows ignores the value returned by this method.

Remarks

WebTV for Windows calls this method when a WebTV for Windows event occurs, as described in the table preceding.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: User-defined.
Unicode: Yes.


ITVControl::TearDown

The TearDown method advises that WebTV for Windows is closing the current Web page.

HRESULT Teardown(void);

Parameters

None.

Return Values

WebTV for Windows ignores the value returned by this method.

Remarks

This method is called by WebTV for Windows before it navigates to a new HTML page. Calling TearDown enables your control to clean up or persistently store its state before the Web page is closed.

WebTV for Windows displays Web pages using the browser component of Microsoft® Internet Explorer. WebTV for Windows calls TearDown before it calls the browser to navigate to a new Web page. Note that WebTV for Windows waits for registered applications to return a value. Thus, your control should return a value promptly, so as not to delay WebTV for Windows in navigating to the new page.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: User-defined.
Unicode: Yes.


ITVControl::Tune

The Tune method advises that WebTV for Windows has tuned to a new channel.

HRESULT Tune(
  long ltsNew,
  long lcnNew,
  long IvsNew,
  long lasNew,
  BSTR bslPNew,
  long ltsPrev,
  long lcnPrev,
  long IvsPrev,
  long lasPrev,
  BSTR bslPPrev
);

Parameters

ltsNew
Tuning space of the new channel.
lcnNew
Channel number of the new channel.
IvsNew
Video subchannel of the new channel. A value of – 1 indicates the default video subchannel, as defined by the broadcast content provider.
lasNew
Audio subchannel of the new channel. A value of – 1 indicates the default audio subchannel, as defined by the broadcast content provider.
bslPNew
String that contains information about the IP stream used by triggers on the new channel. This string must be in the format "xxx.xxx.xxx.xxx yyy.yyy.yyy.yyy:zzz preloadURL&overlayCSS", where xxx.xxx.xxx.xxx specifies the netcard address, yyy.yyy.yyy.yyy specifies the announcement IP address, zzz specifies the announcement port, preloadURL specifies the preload URL and overlayCSS specifies the overlay style sheet. For example: "255.255.255.255 123.25.433.1:1701 basepage.htm&basestyle.css"

The preloadURL and overlayCSS parameters are optional, and can be left out of the string. For example, "255.255.255.255 123.25.433.1:1701".

If no trigger stream exists, this value is set to NULL.

ltsPrev
Tuning space of the previous channel.
lcnPrev
Channel number of the previous channel.
IvsPrev
Video subchannel of the previous channel. A value of – 1 indicates the default video subchannel, as defined by the broadcast content provider.
lasPrev
Audio subchannel of the previous channel. A value of – 1 indicates the default audio subchannel, as defined by the broadcast content provider.
bslPPrev
String that contains information about the IP stream used by triggers on teh previous channel. The string is formatted as described in bsIPNew.

If no trigger stream exists, this value is set to NULL.

Return Values

WebTV for Windows ignores the value returned by this method.

Remarks

WebTV for Windows calls this method when tuning information changes. This method is also called when an object first registers an ITVControl sink with WebTV for Windows.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tvdisp.odl.
Import Library: User-defined.
Unicode: Yes.

See Also

ITVViewer::Tune


IEPGItem

The IEPGItem interface provides methods to retrieve Program Guide data from an object.

When to Implement

Implement IEPGItem in objects that wrap Guide database records. These objects are required as input parameters during calls to methods such as ITVViewer::SetReminder

When to Use

You can call the methods of IEPGItem to retrieve field data from the object.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces
AddRef | Increments reference count
Release | Decrements reference count

IEPGItem | Description
TuningInfo | Gets the tuning space identifier and channel.
StartTime | Gets the starting time.
EndTime | Gets the ending time.
Length | Gets the length of the item, in minutes.
OnNow | Returns a value indicating whether the item is being broadcast now. In other words, this method indicates whether the current system time is later than the item's starting time and earlier than the item's ending time.
Title | Gets the title.
BodyText | Gets the description.
PreviewGraphic | Gets the file name of the preview graphic.
NumIcons | Returns the total number of icons.
GetIcon | Gets the file name of the specified icon.
NumOptions | Returns the total number of options.
OptionPrompt | Gets the option prompt.
GetOption | Gets the specified option.

Remarks

IEPGItem is an abstract interface is inherited by objects that wrap records stored in the Guide database. The IEPGEpisode interface inherits from IEPGItem.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

ITVViewer::DeleteReminder, ITVViewer::HasEnhancement, ITVViewer::HasReminder, ITVViewer::SetReminder, ITVControl::EpisodeStatusChanged


IEPGItem::BodyText

The BodyText method gets the description of the item. Typically, the description text retrieved by BodyText is the as stored in the Guide database.

HRESULT BodyText (
  BSTR* pstrBodyText
);

Parameters

pstrBodyText
Pointer to a BSTR that receives the item description.

Remarks

The subject of the description depends on the object implementating IEPGItem. For example, in an episode object, one that implements IEPGEpisode, the BodyText method retreives a description of the episode.

Typically, the description text for an episode object is the same text stored in the Guide database. For an object that correponds to an episode in the Guide database, the description text is stored in the E Description field of the Episode table.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGItem::Title


IEPGItem::EndTime

The EndTime method gets the ending time of the item.

HRESULT EndTime(
  DATE* pEndTime
);

Parameters

pEndTime
Pointer to a DATE structure that receives the date and time the item ends.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGItem::Length, IEPGItem::StartTime


IEPGItem::GetIcon

The GetIcon method retrieves the file name of the specified icon associated with the item.

HRESULT GetIcon (
  long iIconNumber,
  BSTR* pstrIconName
);

Parameters

iIconNumber
Zero-based identifier of the icon. This value cannot be greater than the value returned by the IEPGItem::NumIcons method – 1.
pstrIconName
Pointer to a BSTR that receives the file name of the icon identified by the iIconNumber parameter.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

Remarks

Icons of the type retrieved by GetIcon represent additional information about the broadcast, such as its rating and pay-per-view status and whether it has closed captioning.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGItem::NumIcons


IEPGItem::GetOption

The GetOption method retrieves the specified option, or command, from the item.

HRESULT GetOption (
  long iOptionNumber,
  long* plID,
  BSTR* pstrText
);

Parameters

iOptionNumber
A long that specifies the zero-based identifier of the option to retrieve. This value cannot be greater than IEPGItem::NumOptions – 1.
plID
Pointer to a long that receives the interface identifier (IID) of the option specified by the iOptionNumber parameter.
pstrText
Pointer to a BSTR that receives the name of the command. This name is the same text as displayed on the option buttons in the Program Guide, such as Watch, Remind, or Other Times.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGItem::NumOptions, IEPGItem::OptionPrompt


IEPGItem::Length

The Length method returns the length, in minutes, of the item.

HRESULT Length (
  long* pLength
);

Parameters

pLength
Pointer to a long that receives the length of the item, in minutes.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGItem::EndTime, IEPGItem::StartTime


IEPGItem::NumIcons

The NumIcons method counts the icons associated with the item.

HRESULT NumIcons (
  long* pNumIcon
);

Parameters

pNumIcon
Pointer to a long that receives the total number of icons.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

Remarks

Icons of the type counted by NumIcons represent additional information about the broadcast, such as its rating and pay-per-view status and whether it has closed captioning.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGItem::GetIcon


IEPGItem::NumOptions

The NumOptions method counts the number of commands that can run on an item.

HRESULT NumOptions (
  long* pNumOptions
);

Parameters

pNumOptions
Pointer to a long that receives the total number of options.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

Remarks

The available options for a broadcast vary over time. For example, you can watch an episode that is on now, but you can only set a reminder for one that is on later.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGItem::GetOption, IEPGItem::OptionPrompt


IEPGItem::OnNow

The OnNow method returns a Boolean specifying whether the item is currently being broadcast.

HRESULT OnNow (
  VARIANT_BOOL* pOnNow
);

Parameters

pOnNow
Pointer to a boolean that indicates whether this item is currently being broadcast. If the received value is VARIANT_TRUE, the item is currently being broadcast. If the value is VARIANT_FALSE, it is not.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.


IEPGItem::OptionPrompt

The OptionPrompt method retrieves a string that explains the options available.

HRESULT OptionPrompt (
  BSTR* pstrPrompt
);

Parameters

pstrPrompt
Pointer to a BSTR that receives the option prompt message.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGItem::GetOption, IEPGItem::NumOptions


IEPGItem::PreviewGraphic

The PreviewGraphic method gets the file name of a graphic to display when the item is not currently being broadcast.

HRESULT PreviewGraphic (
  BSTR* pstrPreviewGraphic
);

Parameters

pstrPreviewGraphic
Pointer to a BSTR that receives the file name. If no preview graphic exists, the method returns a NULL BSTR.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

Remarks

For example, a preview graphic could be displayed as a placeholder for live video from a channel that is currently off the air.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.


IEPGItem::StartTime

The StartTime method gets the starting time of the item.

HRESULT StartTime(
  DATE* pStartTime
);

Parameters

pStartTime
Pointer to a DATE structure that receives the date and time the item starts.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGItem::EndTime, IEPGItem::Length,


IEPGItem::Title

The Title method gets the title of the item.

HRESULT Title (
  BSTR* pstrTitle
);

Parameters

pstrTitle
Pointer to a BSTR that receives the title.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGItem::BodyText


IEPGItem::TuningInfo

The TuningInfo method gets tuning information associated with the item.

HRESULT TuningInfo (
  long* plTuningSpace,
  long* plChannelNumber
);

Parameters

plTuningSpace
Pointer to a long that receives the tuning space identifier.
plChannelNumber
Pointer to a long that receives the channel number.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.


IEPGEpisode

The IEPGEpisode interface enables applications such as WebTV for Windows to retrieve data from an episode object.

When to Implement

Implement IEPGEpisode in objects that wrap episode records in the Guide database.

When to Use

You can call the methods of IEPGEpisode to retrieve episode field data from the object.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces
AddRef | Increments reference count
Release | Decrements reference count

IEPGEpisode | Description
TimeSlotID | Gets the time-slot identifier. This value maps to the starting and ending time of the episode.
ChannelID | Gets the channel identifier.
EpisodeID | Gets the episode identifier.
PayPerView | Retrieves a Boolean value indicating whether the episode is pay-per-view.
RatingID | Gets the rating identifier.
CallLetters | Retrieves the call letters of the station.
IsRemindItem | Returns a value indicating whether a show reminder is set for the episode.
IsRecordItem | Returns a value indicating whether a record reminder is set for the episode.
Repetition | Counts the number of times that the episode appears in the Guide database.
RemindRecordIdx | Returns an index into the cache of show reminders in WebTV for Windows. This method is only valid for episodes for which the IsRemindItem or IsRecordItem method returns VARIANT_TRUE.
IsContinuous | Returns a value indicating whether the episode is continuous, in other words whether there is a single on-going episode for the channel.
IsOnLater | Returns a value indicating whether the episode is on later.
IsOnSoon | Returns a value indicating whether the episode is on within the next five minutes.
ThemeID | Gets the episode's theme identifier.
AbbreviatedTitle | Gets the abbreviated version of the episode title.
HasEnhancement | Gets a value indicating whether the episode has enhancements.
Layout | Gets the enhancement layout information.

Remarks

The IEPGEpisode interface enables applications such as WebTV for Windows to retrieve data from an episode object. An episode object is one that wraps the data of an episode record in the Guide database. IEPGEpisode inherits from the IEPGItem interface. IEPGItem must be implemented in episode objects passed to WebTV for Windows.

WebTV for Windows creates its own episode objects and initializes them with data from the Guide database. For example, WebTV for Windows can query the Guide database to open a recordset of all the episodes that have "great" in the title. For each record in the recordset, WebTV for Windows creates an episode object, initializing its values to the record's field values.

Pointers to IEPGEpisode interfaces are passed as parameters to the ITVViewer::SetReminder and ITVViewer::HasEnhancement methods. To use these methods, your application must implement an episode object that supports IEPGEpisode.

WebTV for Windows returns an IEPGEpisode pointer when it calls the ITVControl::EpisodeStatusChanged method.

For more information on the methods that IEPGEpisode contains but that are reserved for future use, see Reserved Methods in IEPGEpisode.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGItem


Reserved Methods in IEPGEpisode

The IEPGEpisode interface contains the following methods that are not currently supported and that are reserved for future use:

  • IEPGEpisode::IsListGuideItem
  • IEPGEpisode::IsPurchasable
  • IEPGEpisode::IsPurchaseItem
  • IEPGEpisode::PPVCanBeCancelled
  • IEPGEpisode::PPVTapeCost
  • IEPGEpisode::PPVTokenAddress
  • IEPGEpisode::PPVViewCost
  • IEPGEpisode::PurchaseIdx


IEPGEpisode::AbbreviatedTitle

The AbbreviatedTitle method gets the short version of the episode title.

HRESULT AbbreviatedTitle(
  BSTR* pstrAbbrevTitle
);

Parameters

pstrAbbrevTitle
Pointer to a BSTR that receives the abbreviated title.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

Remarks

The abbreviated title contains the content-provider's recommended abbreviation of the episode title. The abbreviated version of the title should be used in user interfaces where there is insufficient space to display the full title. For example, "InterNight" might have an abbreviated title of "INight".

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.


IEPGEpisode::CallLetters

The CallLetters method gets the call letters associated with the episode. This information corresponds to the S Call Letters field in the Guide database.

HRESULT CallLetters(
  BSTR* ppszCallLetters
);

Parameters

ppszCallLetters
Pointer to a BSTR that receives the call letters.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.


IEPGEpisode::ChannelID

The ChannelID method retrieves the channel identifier of the episode. This information corresponds to the TS Channel ID field in the Guide database.

HRESULT ChannelID(
  long* lChannelID
);

Parameters

lChannelID
Pointer to a long that receives the channel identifier.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.


IEPGEpisode::EpisodeID

The EpisodeID method retrieves the identifier of the episode. This information corresponds to the TS Episode ID field in the Guide database.

HRESULT EpisodeID(
  long* lEpisodeID
);

Parameters

lEpisodeID
Pointer to a long that receives the episode identifier.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.


IEPGEpisode::HasEnhancement

The HasEnhancement method gets a value indicating whether the episode has enhancements. If the episode has enhancements, this method retrieves identifiers specifying the enhancement.

HRESULT HasEnhancement(
  VARIANT_BOOL *pf,
  long * lTSEnhMappingID,
  long * lEpiEnhMappingID
);

Parameters

pf
Pointer to a boolean value that receives VARIANT_TRUE if the episode has enhancements, or VARIANT_FALSE otherwise.
lTSEnhMappingID
Pointer to a long that receives the time slot enhancement mapping identifier. This value is only set if the episode has enhancements.
lEpiEnhMappingID
Pointer to a long that receives the episode enhancement mapping identifier. This value is only set if the episode has enhancements.

Remarks

You can pass in NULL for either or both of the enhancement identifiers. In this case, HasEnhancement will still return a value that indicates whether the episode has enhancements, however it does not get values for the identifiers. The following code is an example of this usage:

pEPGEpisode->HasEnhancement(&fHasEnh, NULL, NULL)

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGEpisode::Layout


IEPGEpisode::IsContinuous

The IsContinuous method returns a value that indicates whether the episode is continuous.

HRESULT IsContinuous(
  VARIANT_BOOL * pf
);

Parameters

pf
Pointer to a variable that receives VARIANT_TRUE if the episode is continuous, and VARIANT_FALSE otherwise.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

Remarks

If an episode is continuous, it means there is a single on-going episode for the channel broadcasting that episode. For example, the Program Guide channel broadcasts one continuous episode.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGEpisode::IsOnLater, IEPGEpisode::IsOnSoon


IEPGEpisode::IsOnLater

The IsOnLater method returns a value indicating whether the episode is on later.

HRESULT IsOnLater(
  VARIANT_BOOL * pf
);

Parameters

pf
Pointer to a variable that receives VARIANT_TRUE if the episode is on later, and VARIANT_FALSE otherwise.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGEpisode::IsContinuous, IEPGEpisode::IsOnSoon


IEPGEpisode::IsOnSoon

The IsOnSoon method returns a value that indicates whether the episode will be broadcast in the next five minutes.

HRESULT IsOnSoon(
  VARIANT_BOOL * pf
);

Parameters

pf
Pointer to a variable that receives VARIANT_TRUE if the episode will be broadcast in the next five minutes, and VARIANT_FALSE otherwise.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGEpisode::IsContinuous, IEPGEpisode::IsOnLater


IEPGEpisode::IsRecordItem

The IsRecordItem method returns a value indicating whether the episode is a record item.

HRESULT IsRecordItem(
  VARIANT_BOOL * pf
);

Parameters

pf
Pointer to a variable that receives VARIANT_TRUE if a record reminder is set for the episode, and VARIANT_FALSE otherwise.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

Remarks

WebTV for Windows sets record items. Some record items, typically episodes that are for display purposes only, do not have a valid time slot associated with them — in other words, their TS Time Slot ID field equals zero. If the time slot identifier is zero, but IsRecordItem returns S_OK, this indicates that a record reminder is set but that there are no shows matching this record reminder in the Program Guide.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGEpisode::IsRemindItem, IEPGEpisode::RemindRecordIdx, IEPGEpisode::Repetition


IEPGEpisode::IsRemindItem

The IsRemindItem method returns a value indicating whether the episode is a remind item.

HRESULT IsRemindItem(
  VARIANT_BOOL * pf
);

Parameters

pf
Pointer to a variable that receives VARIANT_TRUE if a reminder is set for the episode, and VARIANT_FALSE otherwise.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

Remarks

Remind items are set by WebTV for Windows. Some remind items, typically episodes that are for display purposes only, do not have a valid time slot associated with them — in other words, their TS Time Slot ID fields equal zero. If the time slot identifier is zero, but IsRemindItem returns S_OK, this indicates that a reminder is set but that there are no shows matching this reminder in the Program Guide.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGEpisode::IsRecordItem, IEPGEpisode::RemindRecordIdx, IEPGEpisode::Repetition


IEPGEpisode::Layout

The Layout method returns additional information about the episode's enhancement.

HRESULT Layout (
  long lEnhMappingID,
  BSTR * EnhTitle,
  BSTR * EnhLayout,
  BSTR * EnhAddress
);

Parameters

lEnhMappingID
Long that contains the enhancement mapping identifier. This corresponds to either the lTSEnhMappingID or lEpiEnhMappingID value returned by the IEPGEpisode::HasEnhancement method.
EnhTitle
Pointer to a string that receives the title of the interactive show.
EnhLayout
Pointer to a string that receives the starting or default HTML layout page for the enhancement.
EnhAddress
Pointer to a string that recieves the enhancement IP address. Triggers for the enhancement will be sent to this address.

Remarks

This method is only valid for episodes that have enhancements. To test whether an episode has enhancements, call IEPGEpisode::HasEnhancement.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGEpisode::HasEnhancement


IEPGEpisode::PayPerView

The PayPerView method returns a value indicating whether the episode is a pay-per-view episode. This information corresponds to the TS Pay Per View field in the Guide database.

HRESULT PayPerView (
  VARIANT_BOOL * pf
);

Parameters

pf
Pointer to a variable that receives VARIANT_TRUE if the episode is a pay-per-view episode, and VARIANT_FALSE otherwise.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.


IEPGEpisode::RatingID

The RatingID method gets the rating identifier associated with the episode. This information corresponds to the E Rating ID field in the Guide database.

HRESULT RatingID(
  long* lRatingID
);

Parameters

lRatingID
Pointer to a long that receives the rating identifier.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.


IEPGEpisode::RemindRecordIdx

The RemindRecordldx method returns an index into the cache of show reminders in WebTV for Windows. This method is only valid for episodes for which the IEPGEpisode::IsRemindItem or IEPGEpisode::IsRecordItem method returns VARIANT_TRUE.

HRESULT RemindRecordIdx(
  long* idxRR
);

Parameters

idxRR
Pointer to a long that receives the index value. If the episode is not a record or a remind item, this value is –1.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGEpisode::IsRemindItem, IEPGEpisode::IsRecordItem, IEPGEpisode::Repetition


IEPGEpisode::Repetition

The Repetition method returns a value indicating the frequency, or type, of the reminder. This method is only valid for episodes for which the IsRemindItem or IsRecordItem method returns VARIANT_TRUE.

HRESULT Repetition(
  int* iRep
);

Parameters

iRep
Pointer to an int that receives the repetition type flag. This flag can be one of the following named values.
Value | Meaning
REMIND_DAILY | The reminder repeats each day.
REMIND_NONE | The reminder doesn't occur. This value may indicate that the episode does not have a show or record reminder set.
REMIND_ONCE | The reminder occurs once.
REMIND_WEEKDAYS | The reminder repeats each weekday.
REMIND_WEEKLY | The reminder repeats every week.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.

See Also

IEPGEpisode::IsRemindItem, IEPGEpisode::IsRecordItem, IEPGEpisode::RemindRecordIdx


IEPGEpisode::ThemeID

The ThemeID method retrieves the theme identifier of the episode. This information corresponds to the T Theme ID field in the Guide database.

HRESULT ThemeID(
  long* lThemeID
);

Parameters

lThemeID
Pointer to a long that receives the theme identifier.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.


IEPGEpisode::TimeSlotID

The TimeSlotID method retrieves the time slot identifier of the episode. This information corresponds to the TS Time Slot ID field in the Guide database.

HRESULT TimeSlotID(
  long* lTimeSlotID
);

Parameters

lTimeSlotID
Pointer to a long that receives the time slot identifier.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds it returns S_OK. Otherwise it returns an error code. For specific error code values see Winerror.h.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Import Library: User-defined.
Unicode: Yes.


Television System Services

The object library for Television System Services (TSS), Tssadmin.dll, provides television-related utility methods for Broadcast Architecture, as well as a television-related collection. Using the TSS object library, you can:

  • Retrieve information about the Broadcast Architecture installation.
  • Create and parse show references.
  • Generate a query from a show reference that returns a list of all episodes that match the show reference.
  • Load enhancement information into the Guide database.
  • Set and delete show reminders.

For more information on using this library, see About Television System Services and Using Television System Services.


About Television System Services

The TSS object library, Tssadmin.dll, provides a variety of television-related utility methods, as well as a television-related collection. The following topics group these items by related functionality:

  • About the Property Methods describes the methods used to return information about the current TSS installation.
  • About the Enhancement Loader Methods describes the methods that load and manipulate enhancement information in the Guide database.
  • About the Show Reference Methods describes the methods that create and parse show references.
  • About the Scheduled Items Collection describes the collection of show reminders.

For reference information on the interfaces that provide these methods, see the topics on the ITelevisionServices and IScheduledItems interfaces. For more information on the methods that TSS contains but that are reserved for future use, see Reserved Methods in ITelevisionServices.


About the Property Methods

The methods described in this topic retrieve information about the properties of the current TSS installation. The property methods are as follows:

  • ITelevisionServices::get_SystemFile
  • ITelevisionServices::get_DatabaseFile
  • ITelevisionServices::get_ScheduledItems
  • ITelevisionServices::get_ClipboardFormat
  • ITelevisionServices::get_ClipboardFormatName

To retrieve the paths and names of the Microsoft® Access files where Broadcast Architecture stores security information, your application uses the ITelevisionServices::get_SystemFile and ITelevisionServices::get_DatabaseFile methods.

The ITelevisionServices::get_ScheduledItems method retrieves a collection of all currently scheduled show reminders. A show reminder reminds the user when a specific show is about to begin. Broadcast Architecture defines a show reminder as a special type of task in the Task Scheduler component of the Microsoft® Windows® 98 operating system. For more information about the collection get_ScheduledItems retrieves, see About the Scheduled Items Collection.

The remaining property methods retrieve information about the clipboard format used for show references. When Broadcast Architecture is installed, it saves information about this new clipboard format in the registry. If your application has information on the show-reference clipboard format, your application can use the clipboard to cut and paste show references. The TSS object library provides two methods, ITelevisionServices::get_ClipboardFormat and ITelevisionServices::get_ClipboardFormatName, that you can use to retrieve the identifier and name of the show-reference clipboard format.

For more information on working with the property methods, see the following topics:

  • Getting Information About Broadcast Architecture Using TSS
  • Getting Scheduled Reminders
  • Using IScheduledItems to Schedule a Show Reminder


About the Enhancement Loader Methods

The TSS object library, Tssadmin.dll, provides methods that you can use to load enhancement information into the Guide database and to manipulate that information. The enhancement loader methods are as follows:

  • ITelevisionServices::LoadEnhancement
  • ITelevisionServices::LoadEnhancementsFromFile
  • ITelevisionServices::DeleteEnhancementFromID
  • ITelevisionServices::DeleteOldEnhancements
  • ITelevisionServices::RemapEnhancements

The ITelevisionServices::LoadEnhancement and LoadEnhancementsFromFile methods are used to load information about enhancements into the Guide database. This information includes, for example, the file name and location of the starting page of the enhancement. Storing this information in the database enables Microsoft WebTV for Windows to query the database to locate the enhancement files associated with a particular show.

The ITelevisionServices::LoadEnhancement and LoadEnhancementsFromFile methods only store information. They do not download the Web files that constitute an enhancement page. Enhancement files can be loaded into the user's computer in ways such as:

  • Through digital data transmission means such as Internet channel broadcasting or encoding in the vertical blanking interval (VBI)
  • User-initiated downloads such as from a Web page.
  • As part of loading current Program Guide information into the Guide database

Once the enhancement pages are downloaded onto the user's computer, information about them needs to be loaded into the Guide database. Doing this enables Microsoft® WebTV® for Windows® to locate and display the enhancement pages. If enhancement files are loaded onto the user's computer during an update of the Guide database, the Loadstub component of Broadcast Architecture loads information about enhancement files into the database. Loadstub does this by calling LoadEnhancementsFromFile. For more information about working with Loadstub, see Updating the Guide Database.

If enhancement files are loaded onto the user's computer through information encoded in the VBI, the broadcaster must also transmit an announcement trigger to load information about the enhancements into the Guide database. Otherwise, WebTV for Windows does not have the information that the show is interactive. The enhancement filter on the broadcast client receives this announcement and calls LoadEnhancement to load this information into the Guide database. For more information about announcements, see Announcements Overview.

If your application loads enhancement files onto users' computers without using Loadstub or the enhancement filter, it must load information about the enhancements into the Guide database by calling either the LoadEnhancementsFromFile or the LoadEnhancement method.

TSS also provides the method ITelevisionServices::DeleteEnhancementFromID, which enables components such as Announcement Listener to delete enhancement data from the Guide database. Typically, your application does not need to call this method. Instead, enhancement information is automatically deleted from the Guide database after the information expires. Obsolete enhancement data is periodically removed from the Guide database by Loadstub.

To enable such cleanup, you must set an expiration date and time for any enhancement data that you load. You specify the enhancement data's expiration date and time in the dateExpire parameter of LoadEnhancement or in the Expiration Date column of the text file read by LoadEnhancementsFromFile.

In addition to Loadstub's periodic deletion of expired enhancement data, your application can explicitly remove expired enhancement data by calling the ITelevisionServices::DeleteOldEnhancements method. Note that because Loadstub automatically deletes obsolete enhancement data, your application typically will not call DeleteOldEnhancements explicitly.

The ITelevisionServices::RemapEnhancements method maps enhancements to the shows or episodes they enhance.

For more information about using the enhancement methods, see Loading Enhancement Information. For general information about enhancements, see Video Enhancements.


About the Show Reference Methods

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:

  • ITelevisionServices::MakeLocalBroadcastSchedule
  • ITelevisionServices::MakeRemoteBroadcastSchedule
  • ITelevisionServices::SplitBroadcastSchedule
  • ITelevisionServices::SplitSimpleBroadcastSchedule
  • ITelevisionServices::ResolveBroadcast
  • ITelevisionServices::ResolveBroadcastInclusively
  • ITelevisionServices::ResolveScheduledReminders
  • ITelevisionServices::TuningSpaceNameFromNumber
  • ITelevisionServices::TuningSpaceNumberFromName

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:

  • Creating a Show Reference
  • Parsing a Show Reference
  • Resolving a Show Reference
  • Mapping a Tuning Space Name to an Identifier


About the Scheduled Items Collection

A show reminder is a task in Task Scheduler, a component of the Microsoft® Windows® 98 operating system. A show reminder task runs just before a show starts and displays a message informing the user the show is about to begin. For a list of the currently set reminders, your application retrieves a reference to a collection of ScheduledItems objects by using the ITelevisionServices::get_ScheduledItems method.

Once your application has a reference to this collection, it can use the methods of the IScheduledItems interface to set, delete, or enumerate the scheduled shows. For more information on doing so, see Using IScheduledItems to Schedule a Show Reminder. Using IScheduledItems is simpler for applications that do not connect to WebTV for Windows.

However, show reminders set using IScheduledItems do not appear in the WebTV for Windows user interface. In other words, users cannot search for or set IScheduledItems reminders using the WebTV for Windows search page. To create scheduled reminders that users can view and access from WebTV for Windows, you must use the ITVViewer::SetReminder method. For more information, see Using ITVViewer to Schedule a Show Reminder.


Using Television System Services

The TSS object library, Tssadmin.dll, provides a variety of utility methods for Broadcast Architecture–aware applications. The following topics describe how to use the different areas of functionality provided by these methods:

  • Getting Information About Broadcast Architecture Using TSS
  • Loading Enhancement Information
  • Creating a Show Reference
  • Parsing a Show Reference
  • Resolving a Show Reference
  • Mapping a Tuning Space Name to an Identifier
  • Getting Scheduled Reminders
  • Using IScheduledItems to Schedule a Show Reminder


Getting Information About Broadcast Architecture Using TSS

The TSS object library provides methods that you can use to acquire information about the current Broadcast Architecture installation.

To get the path and name of the system workgroup information file that is used for TSS database security, your application calls the ITelevisionServices::get_SystemFile method. With this information, your application can set the system database of the Microsoft® Jet database engine. The path and file name of the Guide database can be retrieved by calling the ITelevisionServices::get_DatabaseFile method. With this information, your application can open the Guide database. To locate more information on working with Jet databases, see Further Information on Television Services for the Client.

Broadcast Architecture saves information about a new clipboard format for show references in the registry. The TSS object library provides methods to retrieve information about this format. With this information, your applications can cut and paste show references using the clipboard. To retrieve the clipboard format identifier, your application calls the ITelevisionServices::get_ClipboardFormat method. To retrieve the clipboard format name, your application calls ITelevisionServices::get_ClipboardFormatName.


Loading Enhancement Information

When Microsoft® WebTV® for Windows® displays an interactive show, it looks up information about the show's enhancements in the Guide database. The type of data that WebTV for Windows looks up is such information as the name and location of the starting enhancement page. In order for an interactive show to display properly, this information must be loaded into the Guide database before the show is broadcast.

The ITelevisionServices interface provides two methods that you can use to load enhancement information into the Guide database, ITelevisionServices::LoadEnhancement and ITelevisionServices::LoadEnhancementsFromFile.

LoadEnhancement loads information about a single enhancement into the database, as specified by parameters passed in the method call. For example, an application that downloads a set of enhancement files to the user's computer can call LoadEnhancement to store information about those files in the Guide database. Once this information is stored, WebTV for Windows can locate and properly display the enhancements with the appropriate show.

If your application loads information about multiple enhancements into the Guide database, it can use LoadEnhancementsFromFile. This method loads information about the multiple enhancements listed in the text file the method call points to. LoadEnhancementsFromFile uses the Installable Sequential Access Module (ISAM), part of the Microsoft® Jet database installation, to parse this text file. Because this is the case, you must include a Schema.ini file in the same directory as the text file LoadEnhancementsFromFile points to. For examples of valid Schema.ini files, see the Remarks section for LoadEnhancementsFromFile.

Both LoadEnhancement and LoadEnhancementsFromFile programmatically determine whether an enhancement applies to a channel or to a specific episode. If the show reference parameter contains an episode title, the method sets the indicated enhancement to apply to the specified episode or episodes.

If the show reference parameter does not contain an episode title, the enhancement is assumed to be a channel enhancement. In this case, LoadEnhancement or LoadEnhancementsFromFile searches the tuning space for the union of station, network, and channel specified in the bstrShowReference or Show Reference parameter of the method used. The method then sets the enhancement to apply to all channel records that match this union.

Your application can use a third method, ITelevisionServices::DeleteEnhancementFromID, to remove enhancement information from the Guide database. You can, for example, use DeleteEnhancementFromID in a trigger event handler that responds to a delete-enhancement event sent by the broadcast content provider. Such a handler deletes the specified enhancement information from the database. However, this method is not often used. Typically, enhancements are deleted automatically when they expire by internal components of Broadcast Architecture.

To explicitly specify that expired enhancement data be deleted from the Guide database, your application can call the ITelevisionServices::DeleteOldEnhancements method.


Creating a Show Reference

To create a show reference from episode data, your application can use either the ITelevisionServices::MakeLocalBroadcastSchedule or ITelevisionServices::MakeRemoteBroadcastSchedule method. With the first method, your application must pass in local broadcast information, including the channel number, local station, and tuning space. With the second, your application can create a show reference that substitutes wildcard values for these entries. Substituting wildcard values causes applications with WebTV for Windows–like functionality to search the Guide database for a matching episode or episodes using only the episode title, network, and show time.

MakeRemoteBroadcastSchedule is useful when you do not know which broadcast area might be local. For example, you can access a Web application from any broadcast area. If your Web application does not have information on and cannot calculate the user's broadcast area, it should call MakeRemoteBroadcastSchedule.

Note that you can achieve the same effect by calling MakeLocalBroadcastSchedule and passing in wildcard values for the Channel, Station, and TuningSpace parameters.

For more information on working with show references, see Show Reference Format and Resolving a Show Reference.


Parsing a Show Reference

A show reference is composed of several fields that contain information about an episode or episodes of a show. Your application can access the episode information, for example the episode title, by parsing the show reference. To do this, you can use either the ITelevisionServices::SplitBroadcastSchedule or ITelevisionServices::SplitSimpleBroadcastSchedule method. Both methods split a show reference into its constituent fields. However, the first method returns the trigger information, time and date information, or both as a pointer to a ITaskTrigger interface, and the second returns time and date information only in a DATE variable and no trigger information.

If you are using the Microsoft® Visual Basic® development system to write your application, you should use SplitSimpleBroadcastSchedule instead of SplitBroadcastSchedule. Although SplitSimpleBroadcastSchedule returns less information about the show reference, it is preferred for Visual Basic applications, which cannot access ITaskTrigger.

For more information on show reference fields, see Show Reference Format. To locate more information about ITaskTrigger, see Further Information on Television Services for the Client.


Resolving a Show Reference

You can use the ITelevisionServices::ResolveBroadcast method to generate a Guide database query that lists all the episodes that match a show reference. Doing so is useful, for example, if your application needs to resolve a reference created with ITelevisionServices::MakeRemoteBroadcastSchedule to the correct local broadcast information.

To generate a query that lists all episodes that have started before and ended after a particular time, your application can call the ITelevisionServices::ResolveBroadcastInclusively method.

For more information on working with show references, see Show Reference Format and Creating a Show Reference.


Mapping a Tuning Space Name to an Identifier

A tuning space enables a broadcast client to resolve overlapping channel numbers used by multiple broadcast sources. For example, suppose a computer has both an analog television tuner and a satellite tuner card installed. If the two broadcast systems each have a channel 1, a conflict occurs. To prevent such conflicts, Broadcast Architecture defines each input source as a separate tuning space, assigning it a unique identifier.

Each tuning space has both a unique numerical identifier, and a human-readable name such as analog tuner, cable, or satellite.

You can use methods of the TSS object library to map a tuning space identifier to its user-readable name and vice versa. For example, if your application needs to present a list of tuning spaces to users, it can look up the tuning spaces in the Guide database and then map each tuning space to a human-readable name. Conversely, when a user selects a tuning space, your application needs to map the tuning space name to its identifier before your application can tune to a channel in that space.

To map an identifier to the tuning space name, your application calls the ITelevisionServices::TuningSpaceNameFromNumber method. To map a name to its corresponding identifier, your application calls the ITelevisionServices::TuningSpaceNumberFromName method.

For more information on resolving channel overlap, see Overlapping Channels.


Getting Scheduled Reminders

Your application can use the TSS object library to retrieve a collection or enumeration of all currently scheduled show reminders, or a list of the reminders set. Your application can then set, edit, and delete the scheduled reminders.

To access all scheduled reminders, your application calls the ITelevisionServices::get_ScheduledItems method. Doing so populates and returns a collection of ScheduledItems objects, each one corresponding to a scheduled reminder. Your application can then set, edit, and delete reminders using the methods of the IScheduledItems interface.

To retrieve a list of the scheduled reminders set, your application calls the ITelevisionServices::ResolveScheduledReminders method. Doing so generates a Data Access Objects (DAO) QueryDef query, which you can then run on the Guide database to generate the list of reminders set.To locate more information on DAO, see Further General Information.


Using IScheduledItems to Schedule a Show Reminder

As described in Scheduling Show Reminders, Broadcast Architecture provides two ways to programmatically schedule show reminders. The first process is described in Using ITVViewer to Schedule a Show Reminder. You can also create a show reminder by using the IScheduledItems interface.

Using IScheduledItems is better for applications that do not connect to WebTV for Windows. For example, an enhancement that is a Microsoft® ActiveX® control or Java applet on a World Wide Web page can schedule a reminder for its show by using IScheduledItems. IScheduledItems is much simpler to start, load, and release than the ITVViewer interface. For more information on connecting to WebTV for Windows, see Connecting to WebTV for Windows.

However, reminders set using IScheduledItems are not always visible in the WebTV for Windows user interface. In other words, they do not automatically appear in the MyReminders list in the search page for WebTV for Windows. In order for a TSS-set reminder to be visible in WebTV for Windows, it must meet certain standards. Setting a Reminder That Appears in WebTV for Windows specifies these standards.

If a reminder set using IScheduledItems does not appear in the WebTV for Windows reminders list, users are unable to delete the reminder using WebTV for Windows. In this case, your application should set an expiration date and time for such a reminder by creating a TASK_TRIGGER structure and specifying values for the wEndYear, wEndMonth, and wEndDay members. Alternatively, you can provide an application that the user can use to delete the reminder. To locate more information about TASK_TRIGGER, see Further Information on Television Services for the Client.

Although users cannot view a reminder set with the IScheduledItems::Add or IScheduledItems::AddFromQuery method from the WebTV for Windows search page, your application can still use WebTV for Windows to display that reminder to the user when it runs. To do so, simply specify WebTV for Windows (Tvx.exe) as the reminder application when you set the show reminder.

Before your application sets a reminder, it must gather information about that reminder. This information is passed to parameters of Add or AddFromQuery. The method used then formats this information in show reminder format and schedules the reminder with the Task Scheduler, part of the Microsoft® Windows® 98 operating system.

To gather information for show reminder parameters
  1. Create a show reference by passing the episode information to either the ITelevisionServices::MakeLocalBroadcastSchedule or ITelevisionServices::MakeRemoteBroadcastSchedule method.
  2. If you know the duration of the episode in minutes, add this information to the MoreRemindAppParameters string for the show reminder, later to be passed to the Add method in the Parameters parameter. If you do not know the episode duration, specify MoreRemindAppParameters as

    "Flag!Type!"

    where

    Flag
    Indicates whether to display this reminder in the WebTV for Windows reminders list. If the flag is set to tvviewer, and the reminder meets the standards specified in Setting a Reminder That Appears in WebTV for Windows, WebTV for Windows displays the reminder in its list. Otherwise, it does not.
    Type
    Indicates the type of reminder set, either Remind or Record.

    For example, specify MoreRemindAppParameters as "tvviewer!Remind!" or "tvviewer!Record!"

    For more information, see Show Reminder Format, Setting a Show Reminder and Setting a Record Reminder.

  3. If WebTV for Windows is to display the reminder, specify the string RemindApp as

    Path Tvx.exe

    where Path is the path to Tvx.exe. Your application later passes this information to Add in the Directory parameter. Your application can retrieve the path by calling the ITelevisionServices::get_DatabaseFile method to locate the Guide database, installed in the same directory as Tvx.exe.

    If a custom reminder application is to display the reminder, specify RemindApp as the application's working directory and name.

    Record reminders should not specify Tvx.exe as the application to display the reminder. Instead, such reminders should use a custom reminder application or Tvwakeup.exe. For more information, see Show Reminder Applications.

  4. Determine the number of minutes before the scheduled show that the reminder should be displayed, later to be passed to Add in the AdvanceMinutes parameter.
  5. Schedule the show reminder by calling Add.

When the reminder runs, the application or component that you specified in the show reminder parameters, usually WebTV for Windows, displays to the user a notification that the show about to be on. The details of the show reminder specified when setting the reminder are passed to the reminder application as command-line arguments. These arguments are passed at the point when the reminder application runs the reminder. For more information about show reminder details, see Show Reminder Format.

The reminder application should use the ITelevisionServices::ResolveBroadcast method to resolve the passed-in show reference to a television episode.

For more information on working with show reminders, see Scheduling Show Reminders.


Television System Services Reference

The primary Automation class in Television System Services (TSS), Tssadmin.dll, is ITelevisionServices, derived from the IDispatch interface. For error handling, ITelevisionServices supports the IErrorInfo Automation interface. To locate more information on IDispatch and IErrorInfo, see Further Information on Television Services for the Client.

TSS also provides the IScheduledItems interface, which contains methods that you can use to set, edit, or delete show reminders.


ITelevisionServices

The ITelevisionServices interface provides the following methods to enable your application to retrieve read-only properties associated with this interface. For information on reserved methods, see Reserved Methods in ITelevisionServices.

When to Implement

You do not need to implement this interface. It is implemented in the Tssadmin.dll library.

When to Use

Call the methods of ITelevisionServices to access utilities related to TSS.

Methods in Vtable Order

IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

ITelevisionServices methods | Description
get_SystemFile | Retrieves the name of the Microsoft® Jet database .mdw file used by TSS. This property is read-only.
get_DatabaseFile | Retrieves the name of the Jet .mdb file that is the Guide database. This property is read-only.
get_ScheduledItems | Retrieves a IScheduledItems collection that contains all the show reminders currently active in the system. This property is read-only.
ResolveBroadcast | Creates a DAO QueryDef query that represents the specified show reference. If a start time is specified in the show reference, the ResolveBroadcast method returns all matching episodes that start at that time.
SplitBroadcastSchedule | Parses a show reference into its constituent parts.
SplitSimpleBroadcastSchedule | Performs the same function as the SplitBroadcastSchedule method, except that time and date information is returned as a Date variable.
MakeLocalBroadcastSchedule | Returns a correctly formatted show reference.
MakeRemoteBroadcastSchedule | Provides a wrapper for the MakeLocalBroadcastSchedule method that substitutes wildcard values for computer- or locality-specific parameters.
TuningSpaceNameFromNumber | Maps the numeric identifier of a tuning space in the Guide database to a user-readable string, such as "Broadcast" or "Cable."
TuningSpaceNumberFromName | Maps a user-readable string denoting a tuning space, such as "Cable" or "Broadcast," to the numeric identifier for that tuning space in the Guide database.
ResolveScheduledReminders | Creates a DAO QueryDef that represents the television shows that match the currently scheduled show reminders.
LoadEnhancement | Loads data about an enhancement into the Guide database.
LoadEnhancementsFromFile | Loads data about multiple enhancements into the Guide database.
DeleteEnhancementFromID | Deletes data about an enhancement from the Guide database.
DeleteOldEnhancements | Deletes expired enhancement information from the Guide database.
RemapEnhancements | Maps enhancement information in the Guide database to the corresponding channels and episodes.
get_ClipboardFormat | Returns the identifier for the clipboard format for show references.
get_ClipboardFormatName | Returns the registered name of the clipboard format for show references.
ResolveBroadcastInclusively | Creates a DAO QueryDef that represents the specified show reference. If a start time is specified in the show reference, the ResolveBroadcastInclusively method returns all matching episodes started before or ending after that time.

Remarks

ITelevisionServices is derived from the IDispatch interface. To locate more information on IDispatch, a COM interface, see Further Information on Television Services for the Client. To locate more information on Microsoft® Win32® API functions called by ITelevisionServices methods, see Further General Information.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

IScheduledItems


Reserved Methods in ITelevisionServices

The object library for Television System Services (TSS), Tssadmin.dll, contains the following methods that are not currently supported and that are reserved for future use:

  • ITelevisionServices::CreateUser
  • ITelevisionServices::DeleteUser
  • ITelevisionServices::RestrictionQueryName


ITelevisionServices::DeleteEnhancementFromID

The DeleteEnhancementFromID method deletes the specified enhancement record from the Guide database. This method does not delete the enhancement files associated with the specified record.

HRESULT DeleteEnhancementFromID(
  Workspace *piDAOWorkspace,
  BSTR bstrEnhancementID
);

Parameters

piDAOWorkspace
Pointer to a DAO workspace. This workspace can be either preexisting or newly created.
bstrEnhancementID
GUID for the enhancement.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

Remarks

In order to use the DeleteEnhancementFromID method to remove enhancement data from the Guide database, you must know the GUID of the enhancement. Typically, DeleteEnhancementFromID is only called by the application that originally loaded the enhancement data.

For example, a broadcast content provider might send a deletion announcement that causes the enhancement filter to remove enhancement data from the Guide database. In this case, a list of that provider's enhancement identifiers is maintained at the head end and the appropriate identifier is sent with the deletion announcement.

It is not necessary to use DeleteEnhancementFromID to delete obsolete enhancement data from the database. This deletion is done periodically by Loadstub. To enable automatic deletion of enhancement data, your application must set an expiration date and time for the enhancement data at the time that it loads the data into the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::DeleteOldEnhancements, ITelevisionServices::LoadEnhancement, ITelevisionServices::LoadEnhancementsFromFile, ITelevisionServices::RemapEnhancements


ITelevisionServices::DeleteOldEnhancements

The DeleteOldEnhancements method deletes expired enhancement data from the Guide database. This method does not delete the enhancement files associated with the specified record.

HRESULT DeleteEnhancementFromID(
  Workspace *piDAOWorkspace,
);

Parameters

piDAOWorkspace
Pointer to a DAO workspace. This workspace can be either preexisting or newly created.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

Remarks

Expired enhancements are those that have an expiration date and time that is earlier than the current date and time. The EN Expired Date field in the Guide database specifies this expiration date and time. Enhancement data's expiration date and time are set when the data is loaded into the Guide database, typically by using either the ITelevisionServices::LoadEnhancement or ITelevisionServices::LoadEnhancementsFromFile method.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::DeleteEnhancementFromID, ITelevisionServices::LoadEnhancement, ITelevisionServices::LoadEnhancementsFromFile


ITelevisionServices::get_ClipboardFormat

The get_ClipboardFormat method returns the registration identifier of the clipboard format for show references.

HRESULT get_ClipboardFormat(
  long * plRetVal  // out
);

Parameters

plRetVal
Pointer to a long value that identifies the registered clipboard format for show references.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h header file. To locate more information about Winerror.h, see Further Information on Television Services for the Client.

Remarks

The registration identifier is the value returned by the Win32 RegisterClipboardFormat function when the show reference format is entered in the registry.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::get_ClipboardFormatName


ITelevisionServices::get_ClipboardFormatName

The get_ClipboardFormatName method returns the name under which the clipboard format for show references has been entered in the registry.

HRESULT get_ClipboardFormatName(
  BSTR  * pbstrName      // out
);

Parameters

pbstrName
Pointer to a string containing the name under which the clipboard format for show references is registered.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h header file. To locate more information about Winerror.h, see Further Information on Television Services for the Client.

Remarks

To enter the clipboard format for show references in the registry, your application uses the Win32 RegisterClipboardFormat function.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::get_ClipboardFormat


ITelevisionServices::get_DatabaseFile

The get_DatabaseFile method retrieves a read-only value that specifies the name of the Microsoft® Jet database .mdb file that is the Guide database.

HRESULT get_DatabaseFile(
  BSTR *pbstrRetVal
);

Parameters

pbstrRetVal
Pointer to a BSTR that receives the file name.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h header file. To locate more information about Winerror.h, see Further Information on Television Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::get_SystemFile


ITelevisionServices::get_ScheduledItems

The get_ScheduledItems method returns a read-only ScheduledItems collection that contains all the show reminders currently active in Broadcast Architecture.

HRESULT get_ScheduledItems(
  IScheduledItems **ppScheduledRet
);

Parameters

ppScheduledRet
Pointer to a pointer to the ScheduledItems collection that contains all of the current show reminders.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

IScheduledItems


ITelevisionServices::get_SystemFile

The get_SystemFile method retrieves a read-only value that specifies the name of the Microsoft® Jet database .mdw file used by TSS.

HRESULT get_SystemFile(
  BSTR *pbstrRetVal
);

Parameters

pbstrRetVal
Pointer to a BSTR that receives the file name.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

Remarks

Applications that use TSS must open the TSS system database using the .mdw file specified by get_SystemFile, not the default .mdw file recorded in the registry. Applications do so by setting the SystemDB property of the DAO database engine to the specified .mdw file before opening the database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::get_DatabaseFile


ITelevisionServices::LoadEnhancement

The LoadEnhancement method loads a single enhancement into the Guide database.

HRESULT LoadEnhancement(
  Workspace *piDAOWorkspace,
  BSTR bstrEnhancementID,
  BSTR bstrShowReference,
  BSTR bstrTitle,
  BSTR bstrPreloadURL,
  BSTR bstrAddress,
  DATE dateExpire,
  DWORD dwFlags
);

Parameters

piDAOWorkspace
Pointer to a DAO workspace. This workspace can be either preexisting or newly created.
bstrEnhancementID
GUID for the enhancement. If your application specifies the bstrEnhancementID parameter as an empty string (""), LoadEnhancement automatically generates a GUID for the enhancement. Your application should only specify an empty string if it has no need to further reference the enhancement being loaded.
bstrShowReference
Show reference of the broadcast to which the enhancement applies. Your application can create a show reference by calling either the ITelevisionServices::MakeLocalBroadcastSchedule or ITelevisionServices::MakeRemoteBroadcastSchedule method.

If the bstrShowReference parameter contains an episode title, the enhancement is treated as an episode enhancement and set for only the episode or episodes specified.

If bstrShowReference contains an empty episode title (""), the enhancement is treated as a channel enhancement. In this case, LoadEnhancement searches the tuning space for the union of the station, network, and channel parameters specified in bstrShowReference. The method then sets an enhancement for all matching channel records.

The following is an example of a episode show reference:

"1997/7/29!26673/7175/9690!0:30!0!0!0!0!9690!9690!4096!7040!''!'MSNBC'!3!54!InterNight".

For further description of show reference syntax, see Show Reference Format.

bstrTitle
Title of the enhancement. Microsoft® WebTV® for Windows® displays this value when an episode has more than one enhancement available. When a user clicks the enhancement icon in the TV banner at the top of the screen, WebTV for Windows displays a list of the enhancement titles, from which the user can select the enhancement to display. For example: InterNight Interactive
bstrPreloadURL
URL of the HTML file that contains the starting enhancement page. If your application does not specify a complete path, such as C:\MyEnhance\, the URL is resolved relative to C:\Program Files\TV Viewer\Layouts.

For example, if you specify "TVShow\TVShow.htm" for the bstrPreloadURL parameter, the URL resolves to "C:\Program Files\TV Viewer\Layouts\TVShow\TVShow.htm".

bstrAddress
String that specifies the address for the network interface card, the multicast address, and multicast port information used to connect to the enhancement stream. This string must have the following format:

"NIC_address\t multicast_address\t multicast_port"

For example:

"125.125.125.125\t225.225.225.255\t10024"
dateExpire
Date and time at which the enhancement expires. All enhancements should have an expiration date and time. This functionality enables Loadstub to delete obsolete enhancement data from the Guide database.
dwFlags
DWORD that indicates additional behavior for LoadEnhancement. The following table lists and describes the possible flags this DWORD can contain.
Value | Meaning
LE_DONTOVERWRITE | If this flag is set, and the enhancement data already exists in the database, LoadEnhancement does not reload the data. The value of bstrEnhancementID is used to determine whether the data is already loaded in the database.
LE_LOUD | If this flag is set, LoadEnhancement sends an operating-system broadcast message to inform applications that use this data that the data has changed. Otherwise, LoadEnhancement does not send a message.
LE_UPDATEADDRESSFIELD | If this flag is set, LoadEnhancement updates the address data for this record in the Guide database.
LE_UPDATEDATEFIELD | If this flag is set, LoadEnhancement updates the time and date data for this record in the Guide database.
LE_UPDATEFIELDS | If this flag is set, LoadEnhancement updates the data for this record in the Guide database, replacing the values of all non-NULL parameters.
LE_UPDATEPRELOADURLFIELD | If this flag is set, LoadEnhancement updates the URL of the starting enhancement page for this record in the Guide database.
LE_UPDATESHOWREFFIELD | If this flag is set, LoadEnhancement updates the show reference data for this record in the Guide database.
LE_UPDATETITLEFIELD | If this flag is set, LoadEnhancement updates the title data for this record in the Guide database.

Remarks

Note that even when the LE_LOUD flag is set in the dwFlags parameter, WebTV for Windows is notified only if the loaded enhancement matches the next episode listed in the Guide database. For example, if an enhancement for a December show is loaded in October, the enhancement is saved in the database, but WebTV for Windows is not notified. This is because the December episode is not yet listed in the Guide database as occurring next.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::DeleteEnhancementFromID, ITelevisionServices::DeleteOldEnhancements, ITelevisionServices::LoadEnhancementsFromFile, ITelevisionServices::RemapEnhancements


ITelevisionServices::LoadEnhancementsFromFile

The LoadEnhancementsFromFile method loads the enhancements listed in a text file into the Guide database.

HRESULT LoadEnhancementsFromFile(
  Workspace *piDAOWorkspace,
  BSTR bstrEnhancementsFile
);

Parameters

piDAOWorkspace
Pointer to a DAO workspace. This workspace can be either preexisting or newly created.
bstrEnhancementsFile
Name of the comma- or tab-delimited text file that lists the enhancements. Because this file is parsed using ISAM, part of the Jet installation, it cannot deviate from the following format:
GUID Title Show Reference Preload URL Address Expiration Date

where each column contains the following data:

GUID
GUID for the enhancement. If your application specifies the GUID field as an empty string (""), LoadEnhancementsFromFile automatically generates a GUID for the enhancement. Your application should only specify an empty string if it has no need to further reference the enhancement being loaded.
Title
Title of the enhancement. WebTV for Windows displays this value when an episode has more than one enhancement available. When a user clicks the enhancement icon in the TV banner at the top of the screen, WebTV for Windows displays a list of the enhancement titles, from which the user can select the enhancement to display. For example: InterNight Interactive
Show Reference
Show reference for the broadcast that the enhancement applies to. Your application can obtain a show reference by calling either the ITelevisionServices::MakeLocalBroadcastSchedule or ITelevisionServices::MakeRemoteBroadcastSchedule method.

If the Show Reference field contains an episode title, the enhancement is treated as an episode enhancement and is set for only the episode or episodes specified.

If Show Reference contains an empty episode title (""), the enhancement is treated as a channel enhancement. In this case, LoadEnhancementsFromFile searches the tuning space for the union of the station, network, and channel parameters specified in Show Reference. The method then sets an enhancement for all matching channel records. For example:

"1997/7/29!26673/7175/9690!0:30!0!0!0!0!9690!9690!4096!7040!''!'MSNBC'!3!54!InterNight".

For further description of show reference syntax, see Show Reference Format.

Preload URL
URL of the HTML file that contains the starting enhancement page. If your application does not specify a complete path, such as C:\MyEnhance\, the URL is resolved relative to C:\Program Files\TV Viewer\Layouts.

For example, if you specify "TVShow\TVShow.htm" for the PreloadURL parameter, the URL resolves to "C:\Program Files\TV Viewer\Layouts\TVShow\TVShow.htm".

Address
String that specifies the address for the network interface card, the multicast address, and multicast port information used to connect to the enhancement stream. This string must have the following format: "NIC_address\t multicast_address\t multicast_port". For example:
"125.125.125.125\t225.225.225.255\t10024"
Expiration Date
Date and time at which the enhancement expires. All enhancements should have an expiration date and time. This functionality enables Loadstub to delete obsolete enhancement data from the Guide database.

To locate more information about the Jet ISAM, see Further Information on Television Services for the Client.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. For more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

Remarks

In addition to requiring you to create an enhancement text file with the proper format, ISAM also requires you to include a schema file in the same directory as that text file. The schema file must be named Schema.ini and specify the name of the text file in its first line, enclosed in brackets ([ ]).

For example, if your application should load E:\Windows\Attach.txt, you must create a file named Schema.ini in the E:\Windows directory, with [Attach.txt] as the first line in the Schema.ini.

The following schema file is valid for comma-delimited files. Replace Attachments.txt with the name of your enhancement text file.

----------Schema.ini-----------
[Attachments.txt]
Format=CSVDelimited
ColNameHeader=False
CharacterSet=ANSI
Col1=ID Text
Col2=Title Text
Col3="Show Reference" Text
Col4="Preload URL" Text
Col5=Address Text
Col6="Expiration Date" DateTime

The following schema file is valid for tab-delimited files. Replace Attachments.txt with the name of your enhancement text file.

-------Schema.ini--------
[Attachments.txt]
Format=TabDelimited
ColNameHeader=False
CharacterSet=ANSI
Col1=ID Text
Col2=Title Text
Col3="Show Reference" Text
Col4="Preload URL" Text
Col5=Address Text
Col6="Expiration Date" DateTime

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::DeleteEnhancementFromID, ITelevisionServices::DeleteOldEnhancements, ITelevisionServices::LoadEnhancement, ITelevisionServices::RemapEnhancements


ITelevisionServices::MakeLocalBroadcastSchedule

The MakeLocalBroadcastSchedule method returns a correctly formatted show reference.

HRESULT MakeLocalBroadcastSchedule(
  BSTR  EpisodeTitle,  // in
  short  Channel,      // in
  BSTR  Network,       // in
  BSTR  Station,       // in
  long  TuningSpace,  // in
  VARIANT  Time,       // in
  BSTR  *pbstrRetVal   // out
);

Parameters

EpisodeTitle
Title for the show reference.
Channel
Channel for the show reference. To specify any channel, set this parameter to the wildcard value of –1.
Network
Network for the show reference.
Station
Station for the show reference. To specify any station, set this parameter to the wildcard value of NULL.
TuningSpace
Tuning space for the show reference. To specify any tuning space, set this parameter to the wildcard value of –1.
Time
Date and time for the show reference. The Time parameter is a VARIANT that can contain either a DATE value or a pointer to an ITaskTrigger interface. The former can be used from the Microsoft® Visual Basic® development system; the latter permits ambiguous dates and times, which can be resolved to repeating show schedules.

You can create a show reference with an ambiguous date or time by passing a pointer to an ITaskTrigger interface in which the date or time member of the TASK_TRIGGER structure, or both, are set to –1. For more information on working with ambiguous dates and times, see Ambiguous Triggers. To locate more information about ITaskTrigger and TASK_TRIGGER, see Further Information on Television Services for the Client.

The DATE data type does not support ambiguous date or time values.

pbstrRetVal
Address where this method returns a properly formatted show reference.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h header file. To locate more information about Winerror.h, see Further Information on Television Services for the Client.

Remarks

The data passed in the parameters of the MakeLocalBroadcastSchedule method contains all the information necessary for making a correctly formatted show reference.

MakeLocalBroadcastSchedule does not perform any validation of the existence of the show or shows specified or more than rudimentary validation of its arguments.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::MakeRemoteBroadcastSchedule, ITelevisionServices::SplitBroadcastSchedule, ITelevisionServices::SplitSimpleBroadcastSchedule


ITelevisionServices::MakeRemoteBroadcastSchedule

The MakeRemoteBroadcastSchedule method is a wrapper for the ITelevisionServices::MakeLocalBroadcastSchedule method that substitutes wildcard values for computer- or locality-specific members.

HRESULT MakeRemoteBroadcastSchedule(
  BSTR  EpisodeTitle,  // in
  BSTR  Network,       // in
  VARIANT  Time,       // in
  BSTR  *pbstrRetVal   // out
);

Parameters

EpisodeTitle
Title for the show reference.
Network
Network for the show reference.
Time
Date and time for the show reference. The Time parameter is a VARIANT that can contain either a DATE value or a pointer to an ITaskTrigger interface. The former can be used from Visual Basic; the latter permits ambiguous dates and times, which can be resolved to repeating show schedules.

You can create a show reference with an ambiguous date or time by passing a pointer to an ITaskTrigger interface in which the date or time member of the TASK_TRIGGER structure, or both, are set to –1. For more information on working with ambiguous dates and times, see Ambiguous Triggers. To locate more information about ITaskTrigger and TASK_TRIGGER, see Further Information on Television Services for the Client.

The DATE data type does not support ambiguous date or time values.

pbstrRetVal
Address where this method returns a properly formatted show reference.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h header file. To locate more information about Winerror.h, see Further Information on Television Services for the Client.

Remarks

The MakeRemoteBroadcastSchedule method does not perform any validation of the existence of the show or shows specified or more than rudimentary validation of its arguments.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::MakeLocalBroadcastSchedule, ITelevisionServices::SplitBroadcastSchedule, ITelevisionServices::SplitSimpleBroadcastSchedule


ITelevisionServices::RemapEnhancements

The RemapEnhancements method maps enhancements loaded in the Guide database to their corresponding channels and episodes.

HRESULT RemapEnhancements(
  Workspace *piDAOWorkspace,
);

Parameters

piDAOWorkspace
Pointer to a DAO workspace. This workspace can be either preexisting or newly created.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

Remarks

The RemapEnhancements method sets the appropriate values for the Enhancement Mapping ID field of the Channel and Episode tables in the Guide database. Loadstub automatically calls RemapEnhancements whenever new Program Guide data is loaded into the Guide database. In most cases, your application never needs to call this method explicitly.

As an example of the use of RemapEnhancements, suppose a content provider transmits enhancement data for a future episode. The enhancement filter stores the enhancement data in the Episode Enhancements table of the Guide database, even though the corresponding episode data is not yet loaded in the database. However, when episode data is loaded, the new episodes are not already matched to the previously loaded enhancement data. In other words, the new episodes' E Enhancement Mapping ID fields are blank. To correct this, Loadstub calls RemapEnhancements to map the preexisting enhancements with the new episodes.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::DeleteEnhancementFromID, ITelevisionServices::DeleteOldEnhancements, ITelevisionServices::LoadEnhancement, ITelevisionServices::LoadEnhancementsFromFile


ITelevisionServices::ResolveBroadcast

The ResolveBroadcast method creates a DAO QueryDef query that represents the specified show reference. If a start time is specified in the show reference, ResolveBroadcast returns all episodes that start at that time.

HRESULT ResolveBroadcast(
  BSTR  Workspace,     // in
  BSTR  QueryName,     // in
  BSTR  ShowReference  // in
);

Parameters

Workspace
Name of the DAO workspace in which to create the query. This workspace can be either preexisting or newly created.
QueryName
Name of the new query.
ShowReference
Show reference used to generate the query. If the ShowReference parameter is unambiguous, the query generated represents a single episode. If ShowReference is ambiguous, it can represent multiple or repeating broadcasts. For example, to generate a query that returns each weekly episode of a show you can specify the time and channel of that show, leaving the date ambiguous.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

Remarks

The ResolveBroadcast method's functionality differs from that of the ITelevisionServices::ResolveBroadcastInclusively method, which returns matching episodes that start before or end after the specified start time.

If a QueryDef of the same name already exists, calling ResolveBroadcast deletes it.

ResolveBroadcast can return an error in which the QueryDef has an empty result set. Such an error occurs if the ShowReference specified does not match anything in the Guide database and does not cause another type of error.

The application that calls ResolveBroadcast must delete the QueryDef object after use.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::ResolveBroadcastInclusively, ITelevisionServices::ResolveScheduledReminders


ITelevisionServices::ResolveBroadcastInclusively

The ResolveBroadcastInclusively method creates a DAO QueryDef definition that represents the specified show reference. If a start time is specified in the show reference, ResolveBroadcastInclusively returns all matching episodes that start before or end after that time.

HRESULT ResolveBroadcastInclusively(
  BSTR  Workspace,     // in
  BSTR  QueryName,     // in
  BSTR  ShowReference  // in
);

Parameters

Workspace
Name of the DAO workspace in which to create the query. This workspace can be either preexisting or newly created.
QueryName
Name of the new query.
ShowReference
Show reference used to generate the query. If the ShowReference parameter is unambiguous, the query generated represents a single episode. If ShowReference is ambiguous, it can represent multiple or repeating broadcasts. For example, to generate a query that returns each weekly episode of a show you can specify the time and channel of that show, leaving the date ambiguous.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

Remarks

The ResolveBroadcastInclusively method's functionality differs from that of the ITelevisionServices::ResolveBroadcast method, which returns matching episodes that start at the specified start time. As an example of ResolveBroadcastInclusively functionality, if the start time specified in the show reference is 11:15 A.M., ResolveBroadcastInclusively creates a QueryDef that returns shows that start any time before and end any time after 11:15 A.M.

If a QueryDef of the same name already exists, calling ResolveBroadcastInclusively deletes it.

ResolveBroadcastInclusively can return an error in which the QueryDef has an empty result set. Such an error occurs if the ShowReference specified does not match anything in the database and does not cause another type of error.

The application that calls ResolveBroadcast must delete the QueryDef object after use.

ResolveBroadcastInclusively ignores the show reference's end time value.

ResolveBroadcastInclusively is called internally by the enhancement filter.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::ResolveBroadcast, ITelevisionServices::ResolveScheduledReminders


ITelevisionServices::ResolveScheduledReminders

The ResolveScheduledReminders method creates a DAO QueryDef query that represents the television shows that match the scheduled show reminders.

HRESULT ResolveScheduledReminders(
  BSTR  Workspace,  // in
  BSTR  QueryName,  // in
  BSTR  Reserved    // in
);

Parameters

Workspace
Name of the DAO workspace in which to create the query. This workspace can be either preexisting or newly created.
QueryName
Name of the new query.
Reserved
Reserved; should be an empty string.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

Remarks

The application that calls the ResolveScheduledReminders method must delete the QueryDef object after use.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::ResolveBroadcast, ITelevisionServices::ResolveBroadcastInclusively


ITelevisionServices::SplitBroadcastSchedule

The SplitBroadcastSchedule method parses a show reference into its constituent parts.

HRESULT SplitBroadcastSchedule(
  BSTR  ShowReference,     // in
  BSTR * EpisodeTitle,     // out
  short *  Channel,        // out
  BSTR * Network,          // out
  BSTR * Station,          // out
  long *  TuningSpace,     // out
  IUnknown ** TaskTrigger  // out
);

Parameters

ShowReference
Show reference to parse.
EpisodeTitle
Pointer to a BSTR where this method returns the title for the show reference.
Channel
Pointer to a short where this method returns the channel for the show reference.
Network
Pointer to a BSTR where this method returns the network for the show reference.
Station
Pointer to a BSTR where this method returns the station for the show reference.
TuningSpace
Pointer to a long where this method returns the tuning space for the show reference.
TaskTrigger
Pointer to a pointer to an ITaskTrigger interface where this method returns the date and time information for the show reference. To locate more information about ITaskTrigger, see Further Information on Television Services for the Client.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h header file. To locate more information about Winerror.h, see Further Information on Television Services for the Client.

Remarks

The SplitBroadcastSchedule method returns an error if the syntax of the show reference string is faulty.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::MakeLocalBroadcastSchedule, ITelevisionServices::MakeRemoteBroadcastSchedule, ITelevisionServices::SplitSimpleBroadcastSchedule


ITelevisionServices::SplitSimpleBroadcastSchedule

The SplitSimpleBroadcastSchedule method parses a show reference into its constituent parts. This method performs the same function as the SplitBroadcastSchedule method, except that the date and time information is returned as a DATE variable.

HRESULT SplitSimpleBroadcastSchedule(
  BSTR  ShowReference,  // in
  BSTR * EpisodeTitle,  // out
  short *  Channel,     // out
  BSTR * Network,       // out
  BSTR * Station,       // out
  long *  TuningSpace,  // out
  DATE * Time           // out
);

Parameters

ShowReference
Show reference to parse.
EpisodeTitle
Pointer to a BSTR where this method returns the title for the show reference.
Channel
Pointer to a short where this method returns the channel for the show reference.
Network
Pointer to a BSTR where this method returns the network for the show reference.
Station
Pointer to a BSTR where this method returns the station for the show reference.
TuningSpace
Pointer to a long where this method returns the tuning space for the show reference.
Time
Pointer to a DATE where this method returns the date and time information for the show reference.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h header file. To locate more information about Winerror.h, see Further Information on Television Services for the Client.

Remarks

The SplitSimpleBroadcastSchedule method is provided for programmers working in Visual Basic, which cannot manipulate objects with the ITaskTrigger interface returned by SplitBroadcastSchedule. SplitSimpleBroadcastSchedule returns an error if the syntax of the show reference string is faulty.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::MakeLocalBroadcastSchedule, ITelevisionServices::MakeRemoteBroadcastSchedule, ITelevisionServices::SplitBroadcastSchedule


ITelevisionServices::TuningSpaceNameFromNumber

The TuningSpaceNameFromNumber method maps the numeric identifier of a tuning space in the Guide database to a user-readable string, for example "Cable" or "Broadcast."

HRESULT TuningSpaceNameFromNumber(
  long  TuningID,     // in
  BSTR * pbstrRetVal  // out
);

Parameters

TuningID
Numeric identifier of the tuning space.
pbstrRetVal
Address where this method returns the string that contains the tuning-space name.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::TuningSpaceNumberFromName


ITelevisionServices::TuningSpaceNumberFromName

The TuningSpaceNumberFromName method maps a user-readable string naming a tuning space (for example, "Cable" or "Broadcast") to the numeric identifier for that tuning space in the Guide database.

HRESULT TuningSpaceNumberFromName(
  BSTR  Name,      // in
  long * plRetVal  // out
);

Parameters

Name
Name for the tuning space in the Guide database.
plRetVal
Address where this method returns the numeric identifier for the tuning space.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. For more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices::TuningSpaceNameFromNumber


IScheduledItems

The methods of the IScheduledItems interface manipulate the ScheduledItems collection, which enumerates the currently scheduled show reminders. For more information on working with show reminders, see Show Reminders.

When to Implement

You do not need to implement this interface. It is implemented in the Tssadmin.dll library.

When to Use

Call the methods of IScheduledItems to retrieve, delete, or set show reminders.

Methods in Vtable Order

IUnknown methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IScheduledItems methods | Description
Item | Returns for a show reminder the specified show reference, the application to start, the working directory, the interval before the show that advance notification should occur, and any optional command-line parameters.
get_Count | Returns the number of currently scheduled reminders in the collection.
Add | Schedules one or more broadcasts.
Remove | Deletes a scheduled show reminder.
AddFromQuery | Schedules reminders for all of the television shows in the result set of the specified query definition.
get__NewEnum | Returns an reference to an enumerator that iterates through a list of the scheduled reminders.

Remarks

The ScheduledItems collection is part of the Television System Services (TSS) object library, Tssadmin.dll. ScheduledItems contains the scheduled show reminders. IScheduledItems has the usual methods of a collection interface: get_Count, get__NewEnum, and Item. The indices into the collection are strings that are the file names of tasks in Task Scheduler, a component of the Microsoft® Windows® 98 operating system. TSS uses Task Scheduler for all scheduling. Your application obtains a reference to the ScheduledItems collection by using the ITelevisionServices::get_ScheduledItems method.

IScheduledItems is derived from the IDispatch interface. To locate more information on IDispatch, a COM interface, see Further Information on Television Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

ITelevisionServices


IScheduledItems::Add

The Add method schedules one or more show reminders.

HRESULT Add(
  BSTR  Workspace,      // in
  BSTR  ShowReference,  // in
  BSTR  Application,    // in
  BSTR  Directory,      // in
  long  AdvanceMinutes, // in
  BSTR  Parameters,     // in
  VARIANT * pSafeArray  // out
);

Parameters

Workspace
Name of a DAO workspace. This workspace can be either preexisting or newly created.
ShowReference
Show reference. Your application can create a show reference by calling either the ITelevisionServices::MakeLocalBroadcastSchedule or ITelevisionServices::MakeRemoteBroadcastSchedule method.
Application
Name and path of the application that displays the reminder to the user when the scheduled show is on. Typically, WebTV for Windows is used to display reminders, and this value is set to C:\Program Files\TV Viewer\Tvx.exe.

Your application can get the path to the broadcast client's installation of WebTV for Windows by calling ITelevisionServices::get_DatabaseFile and stripping Tss.mdb off the end of the returned string. This path is also stored in this registry entry:

HKLM\Software\Microsoft\TV Services\ProductDir

Directory
Name of the working directory that contains the reminder application.
AdvanceMinutes
Interval, in minutes, before the show's start that the reminder should occur.
Parameters
Additional command-line arguments for the application specified by the Application parameter. The format and number of these arguments depend on the application referred to by Application. Parameters is passed to Application as command-line arguments.

For example, if you are using a custom application to display the reminder to the user, and this application has three styles of reminder dialog boxes, Parameters could be used to specify the reminder style.

For a list of the parameters used with the WebTV for Windows reminder application, Tvx.exe, see the description of WebTVforWindowsParameters in Show Reminder Format.

pSafeArray
Pointer to a VARIANT that receives an IEnumVARIANT interface that enumerates the string indices of the scheduled show reminders. To locate more information on working with IEnumVARIANT, see Further Information on Television Services for the Client.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

Remarks

If the time and date specified in the ShowReference parameter are unambiguous, the IScheduledItems::Add method schedules a single show reminder.

Ambiguous show references can represent multiple or repeating broadcasts. For example, if you want to schedule a reminder for each weekly episode of a show, you can specify the time and channel of that show, leaving the date ambiguous. The show reference then applies to all weekly episodes. In contrast, an unambiguous show reminder specifies the date and thus applies to only a single episode.

If the specified show reference is ambiguous, Add uses the ITelevisionServices::ResolveBroadcast method to produce a query that matches ShowReference, in other words a query for all episodes that fit the ambiguous date or channel value. For example, if the show reference specified channel 27 at 5 P.M. on Fridays, leaving the date ambiguous, the generated query returns a listing of each episode in the Guide database whose channel and time parameters match those specified. Once the query is run, Add calls the IScheduledItems::AddFromQuery method to schedule all of the rows returned by the query.

Reminders set using Add are not automatically visible in the WebTV for Windows user interface. In order for a TSS-set reminder to be visible in WebTV for Windows, it must meet certain standards. Setting a Reminder That Appears in WebTV for Windows specifies these standards.

If the reminder to add is a record reminder, your application should use the Task Scheduler component of Window 98 to set the TASK_FLAG_SYSTEM_REQUIRED flag for the reminder. Doing so causes WebTV for Windows to tune to the specified channel even if the system is suspended. Otherwise, if the system is suspended WebTV for Windows does not run the record reminder.

In addition, if the record reminder has an application associated with it that automates tuning a VCR to a specified channel, this application should be specified in the registry value StartRecordingApp, EndRecordingApp, or both. You specify these values under the following registry key:

HKLM\Software\Microsoft\TV Services\Explorer\

TASK_FLAG_SYSTEM_REQUIRED should not be set for standard show reminders. Version 1.0 of Broadcast Architecture does not handle show reminders that occur while the operating system is suspended.

For more information, see Setting a Show Reminder and Setting a Record Reminder.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

IScheduledItems::AddFromQuery, IScheduledItems::Remove, ITelevisionServices::ResolveBroadcast


IScheduledItems::AddFromQuery

The AddFromQuery method schedules reminders for all the television shows in the result set of a DAO QueryDef query.

HRESULT AddFromQuery(
  BSTR  Workspace,      // in
  BSTR  QueryName,      // in
  BSTR  Application,    // in
  BSTR  Directory,      // in
  long  AdvanceMinutes, // in
  BSTR  Parameters,     // in
  VARIANT * pSafeArray  // out
);

Parameters

Workspace
Name of the DAO workspace. This workspace can be either preexisting or newly created.
QueryName
Name of the QueryDef definition. To create a QueryDef from a show reference, your application uses the ITelevisionServices::ResolveBroadcast method.
Application
Name and path of the application that displays the reminder to the user when the scheduled show is on. Typically, WebTV for Windows is used to display reminders, and this value is set to C:\Program Files\TV Viewer\Tvx.exe.

Your application can get the path to the broadcast client's installation of WebTV for Windows by calling ITelevisionServices::get_DatabaseFile and stripping Tss.mdb off the end of the returned string. This path is also stored in this registry entry:

HKLM\Software\Microsoft\TV Services\ProductDir

Directory
Name of the working directory that contains the reminder application.
AdvanceMinutes
Interval, in minutes, before the show's start that the reminder should occur.
Parameters
Additional command-line arguments for the application specified by the Application parameter. The format and number of these arguments depend on the application referred to by Application. Parameters is passed to Application as command-line arguments.

For example, if you are using a custom application to display the reminder to the user, and this application has three styles of reminder dialog boxes, Parameters could be used to specify the reminder style.

For a list of the parameters used with the WebTV for Windows reminder application, Tvx.exe, see the description of WebTVforWindowsParameters in Show Reminder Format.

pSafeArray
Pointer to a VARIANT that receives an IEnumVARIANT interface that enumerates the string indices of the scheduled show reminders. To locate more information on working with IEnumVARIANT, see Further Information on Television Services for the Client.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

Remarks

The AddFromQuery method iterates through the result set of the defined query, composing a show reference for each row and scheduling a reminder for that show reference. Typically, you use the queries created by ITelevisionServices::ResolveBroadcast as the QueryName parameter for AddFromQuery.

Reminders set using AddFromQuery are not automatically visible in the WebTV for Windows user interface. In order for a TSS-set reminder to be visible in WebTV for Windows, it must meet certain standards. Setting a Reminder That Appears in WebTV for Windows specifies these standards.

To locate more information on the SAFEARRAY data type, see Further Information on Television Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

IScheduledItems::Add, IScheduledItems::Remove, ITelevisionServices::ResolveBroadcast


IScheduledItems::get__NewEnum

The get__NewEnum method returns an reference to an enumerator that iterates through a list of the scheduled show reminders.

HRESULT get__NewEnum(
  IUnknown ** ppUnk  // out
);

Parameters

ppUnk
Reference to an enumerator that iterates through the scheduled reminders. The returned object implements the VARIANT enumerator interface, IEnumVARIANT. To locate more information about enumerating collections using IEnumVARIANT, see Further Information on Television Services for the Client.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

IScheduledItems::get_Count, IScheduledItems::Item


IScheduledItems::get_Count

The get_Count method returns the number of currently scheduled show reminders in the ScheduledItems collection.

HRESULT get_Count(
  long * plRetVal  // out
);

Parameters

plRetVal
Pointer to a long that receives the number of reminders.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

IScheduledItems::get__NewEnum, IScheduledItems::Item


IScheduledItems::Item

The Item method returns for a show reminder the show reference, the application to start, the working directory, the interval before the show that advance notification should occur, and any optional command-line parameters.

HRESULT Item(
  BSTR  Index,           // in
  BSTR * User,           // out
  BSTR * ShowReference,  // out
  BSTR * Application,    // out
  BSTR * Directory,      // out
  long * AdvanceMinutes,  // out
  BSTR * Parameters,     // out
  VARIANT * Task         // out
);

Parameters

Index
Index of the show reminder for which to retrieve information.
User
Pointer to a BSTR that receives the name of the owner of the DAO workspace used to schedule the reminder.
ShowReference
Pointer to a BSTR where this method returns the show reference string. For more information about the format of this string, see Show Reference Format.
Application
Pointer to a BSTR that receives the name and path of the application used to display the reminder to the user. Typically, WebTV for Windows is used to display reminders, and this value is set to C:\Program Files\TV Viewer\Tvx.exe.

Your application can get the path to the broadcast client's installation of WebTV for Windows by calling ITelevisionServices::get_DatabaseFile and stripping Tss.mdb off the end of the returned string. This path is also stored in this registry entry:

HKLM\Software\Microsoft\TV Services\ProductDir

Directory
Pointer to a BSTR that receives the working directory that contains the reminder application.
AdvanceMinutes
Pointer to a long that receives the interval, in minutes, before the show's start that the reminder should be displayed.
Parameters
Additional command-line arguments for the application specified by the Application parameter. The format and number of these arguments depend on the application referred to by Application. Parameters is passed to Application as command-line arguments.

For example, if you are using a custom application to display the reminder to the user, and this application has three styles of reminder dialog boxes, Parameters could be used to specify the reminder style.

For a list of the parameters used with the WebTV for Windows reminder application, Tvx.exe, see the description of WebTVforWindowsParameters in Show Reminder Format.

Task
Address where this method returns a VARIANT data type containing an Task object, from which you can obtain the TaskTrigger object. The TaskTrigger object contains additional information about when and how the scheduled reminder will run. To locate more information about TaskTrigger and its interface ITaskTrigger, see Further Information on Television Services for the Client.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

Remarks

The Task parameter is returned as a VARIANT instead of as a Task object to enable Visual Basic programmers to safely use the IScheduledItems::Item method. Visual Basic cannot access the ITask interface; if Item did not return the Task object as a VARIANT, Visual Basic programmers could not correctly release the object.

If you are programming in C++, simply cast the VARIANT to an ITask interface variable.

If you are programming in Visual Basic, you should create a variable of type Variant and pass it as the Task parameter. Do not use this variable after you call Item. When the variable goes out of scope, Visual Basic releases the Task object it references. It is recommended that you declare the Variant variable as local in a function that calls the Item method. Such a declaration causes the Task object to be released quickly.

To locate more information on ITask and VARIANT, see Further Information on Television Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

IScheduledItems::get__NewEnum, IScheduledItems::get_Count


IScheduledItems::Remove

The Remove method deletes a scheduled show reminder from a ScheduledItems collection.

HRESULT Remove(
  BSTR  Index  // in
);

Parameters

Index
Index of the show reminder to delete.

Return Values

Returns an HRESULT indicating success or failure. If the method succeeds, it returns S_OK. Otherwise, it returns an error code. For specific error codes, see the Winerror.h and Dbdaoerr.h header files. To locate more information about Winerror.h and Dbdaoerr.h, see Further Information on Television Services for the Client.

Remarks

Your application can obtain the index for a scheduled show reminder from the enumerator method IScheduledItems::get__NewEnum, or as a return value from the IScheduledItems::Add or IScheduledItems::AddFromQuery method.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in tssadmin.odl.
Import Library: Included as a resource in tssadmin.dll.
Unicode: Yes.

See Also

IScheduledItems::Add, IScheduledItems::AddFromQuery, IScheduledItems::get__NewEnum


Show References

A show reference is a formatted string that contains information about a broadcast episode such as the show time, channel, and network. You can use a show reference to specify a particular episode or episodes.

For more information, see About Show References.


About Show References

To support the programmatic exchange of references to television shows, Television System Services (TSS) has a data format to specify television shows, called a show reference. Show references are strings that you can use to specify a single broadcast of a show, recurring broadcasts, or a time and a channel that can be matched to a broadcast at a later time.

You create a show reference by calling either the ITelevisionServices::MakeLocalBroadcastSchedule or ITelevisionServices::MakeRemoteBroadcastSchedule method of the ITelevisionServices interface, passing a task trigger object. To create a show reference for a recurring broadcast, you must pass an ambiguous trigger to the ITelevisionServices methods.

For more information, see following topics:

  • Show Reference Format
  • Ambiguous Triggers

Note The description of the show reference format is for debugging purposes only. This format may change in future versions of Broadcast Architecture. Developers should compose and parse show references using the methods of the ITelevisionServices interface.


Show Reference Format

A show reference is a null-terminated ASCII string containing fields delimited by exclamation marks ( ! ). Numerical fields are spelled out in ASCII digits.

The syntax of a show reference string is as follows:

yyyy/mm/dd!yyyy/mm/dd!hh:MM!du!in!fl!type!w!w!w!w!'network'!'station'!
'TuningSpace'!channel!'title'

The following table describes the placeholders in show reference syntax. All times are specified in coordinated universal time (UTC) in a 24-hour clock.

Placeholder | Description
yyyy | The year. If this field contains the five digits 65535, it means any year. The first yyyy field in the syntax is for the start date; the second is for the end date.
mm | The month. If this field contains the digits 65535, it means any month. The first mm field is for the start date; the second is for the end date.
dd | The day of the month. If this field contains the digits 65535, it means any day. The first dd field is for the start date; the second is for the end date.
network | The network affiliate of the station. This affiliate can be the same as the station in some cases. In other situations, a national network is the affiliate for a local station.
hh | The hour portion of the time at which the show begins. If this field contains the digits 65535, it means any hour of the day.
MM | The minute portion of the time at which the show begins. If this field contains the digits 65535, it means any minute of the hour.
du | The duration of the show in minutes. This value is valid only if the TASK_TRIGGER_FLAG_KILL_AT_DURATION_END flag is set in the fl parameter of the show reference.
in | The interval at which to run the show reminder. Because a typical show reminder only runs once, this value is usually zero.
fl | Flags for interpretation of the preceding dates. These flags are the same as the ones in the TASK_TRIGGER structure of the Task Scheduler : TASK_TRIGGER_FLAG_HAS_END_DATE, TASK_TRIGGER_FLAG_KILL_AT_DURATION_END, and TASK_TRIGGER_FLAG_DISABLED.
type | This parameter is set as the TriggerType member of the TASK_TRIGGER structure. It takes a TASK_TRIGGER_TYPE data type. To locate more information on TASK_TRIGGER, see Further Information on Television Services for the Client.
w | This parameter is set as the Type member of the TASK_TRIGGER structure. It takes a TRIGGER_TYPE_UNION data type.
station | The station's call letters, for example KZZZ. This field can be empty.
TuningSpace | A string that contains the name of the source, or tuning space, of the broadcast. An empty string ('') in this field means any source. Tuning space names are strings, such as 'Cable', that represent a tunable video source, for example, cable, satellite broadcast, or terrestrial analog broadcast. Tuning space names are stored as named values under the registry key \HKLM\Software\Microsoft\TVServices\Tuning Spaces\TuningSpaceNumber where TuningSpaceNumber indicates the numerical identifier of the tuning space.
channel | An integer denoting the channel in the tuning space. If this field contains –1 (minus one), it means any channel.
title | The title of the television show. This title must not contain double quotation marks ( " ). The title field can be a limited regular expression with the syntax and semantics defined in Structured Query Language (SQL). Thus, "*" means any title, "*News*" means any title with "News" in it, and so on. An empty string, two single quotation marks ( '' ), indicates any show. To locate more information on SQL, see Further General Information.

Note This description of the show reference format is for debugging purposes only. This format may change in future versions of Broadcast Architecture. Developers should compose and parse show references using the MakeLocalBroadcastSchedule and MakeRemoteBroadcastSchedule methods of the ITelevisionServices interface.

Examples

The following are examples of valid show references.

1998/3/13!0/0/0!23:35!0!0!0!0!0!0!0!0!''!'MSNBC'!'Cable'!4!'Time & Again'

1998/4/22!73/1/0!2:0!0!0!0!0!0!0!0!0!''!'MSNBC'!'Cable'!38!'InterNight'


Ambiguous Triggers

The Broadcast Architecture supports a custom implementation of the ITaskTrigger interface of Internet Client that enables an application to create ambiguous task trigger objects. An ambiguous trigger is one where the date or time parameters, or both, are not known at the time of the trigger's creation. You can also use the Broadcast Architecture implementation of ITaskTrigger to create a trigger where the time and date are fully specified.

You can use ambiguous triggers to represent a range of shows. For example, if a show appears every weeknight at 7 p.m., you can create a date-ambiguous trigger that represents all episodes of the show. For information on how to do this, see Creating an Ambiguous Trigger.

Once an ambiguous trigger is created, it can be passed to either the ITelevisionServices::MakeLocalBroadcastSchedule or ITelevisionServices::MakeRemoteBroadcastSchedule method to create a show reference that represents multiple episodes. You can then schedule a show reminder for each episode by calling the IScheduledItems::Add method and passing this multiepisode show reference.

The Broadcast Architecture implementation of ITaskTrigger implements both the ITaskTrigger::SetTrigger and the ITaskTrigger::GetTrigger methods. These are functionally equivalent to the methods implemented by the Task Scheduler. They differ only in that they support ambiguous triggers.

However, the Broadcast Architecture implementation does not support the ITaskTrigger::GetTriggerString method. Calling this method produces an error.

To locate more information about ITaskTrigger, see Further Information on Television Services for the Client.


Creating an Ambiguous Trigger

To create an ambiguous trigger, first create a TASK_TRIGGER structure and set the ambiguous time or date members to –1. Then set this structure to a trigger object by calling the ITaskTrigger::SetTrigger method.

The following example creates an ambiguous trigger where the starting time, 7 p.m., is known but the day, month, and year are not. This trigger can be used, for example, to represent multiple episodes of a show that is broadcast every weeknight at 7 p.m.:

ITaskTrigger *pTaskTrig;
TASK_TRIGGER tt;
HRESULT hr;

memset(&tt, 0, sizeof(tt));
tt.cbTriggerSize = sizeof(TASK_TRIGGER);
tt.TriggerType = TASK_TIME_TRIGGER_ONCE;
tt.rgFlags = 0;
tt.wStartMinute = 0;
//Set the ambiguous time members
tt.wBeginYear = -1;
tt.wBeginMonth = -1;
tt.wBeginDay = -1;
//set the starting time to 7pm
tt.wStartHour = 19;

//Create an instance of a task trigger
if (FAILED(hr = CoCreateInstance(CLSID_TaskTrigger, NULL, CLSCTX_INPROC_SERVER, IID_ITaskTrigger, (LPVOID *) &pTaskTrig)))
  return hr;

//Set the ambiguous trigger in the task
if (FAILED(hr = pTaskTrigger->SetTrigger(&tt)))
{
  pTaskTrigger->Release();
  return hr;
}
else
{
  //... Additional code that uses the trigger

  pTaskTrigger->Release();
  return NOERROR;
}

You can set any number of the TASK_SCHEDULER structure members to –1. For example, you can make a trigger that is ambiguous only in the day, or the month, or the year. So, if you know that a show was on during January 1998 but don't know what day, you can set the month to 1, the year to 1998, and the day to –1.

To determine whether a trigger is ambiguous, you can call the ITaskTrigger::GetTrigger method and check whether any of the date or time members in the TASK_TRIGGER structure are set to –1.

To locate more information about TASK_TRIGGER and the ITaskTrigger interface, see Further Information on Television Services for the Client.


Show Reminders

Show reminders are Task Scheduler tasks that remind a user to watch or record a television broadcast. Show reminders are typically set by Microsoft WebTV for Windows, part of the Microsoft® Windows® 98 operating system. You can also write an application to set, modify, or delete show reminders.

For more information, see the following topics:

  • About Show Reminders, which describes show reminder functionality and the format used to schedule a reminder in the Task Scheduler.
  • Show Reminder Applications, which describes applications the Task Scheduler runs in order to display or handle a show reminder.
  • Show Reminder Format, which details the command-line format set in the Task Scheduler for show reminders.
  • Scheduling Show Reminders, which explains how to write an application that sets a show reminder.
  • IScheduledItems, which describes the ScheduledItems collection of scheduled show reminders.


About Show Reminders

Your application can schedule show reminders as tasks in the Task Scheduler. These tasks specify the application to run, typically Microsoft® WebTV® for Windows®, and command-line arguments for that application.

When the Task Scheduler runs a show reminder task, it sends these command-line parameters to the specified show reminder application. If the application is not currently running, the Task Scheduler starts it.

For more information, see Show Reminder Applications and Show Reminder Format.


Show Reminder Applications

A show reminder application is the application that handles the show reminder, typically by displaying a reminder dialog to the user and/or tuning to the channel displaying the show. This should not be confused with the application that sets a show reminder.

If you set a show reminder using WebTV for Windows, the show reminder application will be Tvx.exe for normal show reminders and Tvwakeup.exe for record reminders. The difference between these applications is that Tvx.exe, which is the executable for WebTV for Windows, simply displays a dialog box reminding the user that the show is about to begin. Tvwakeup, on the other hand, displays a reminder dialog, tunes to the show's channel unless canceled by the user, and starts any record helper applications specified in the registry.

Note Tvx.exe does not display show reminders that occur while the system is suspended. This prevents the reminder from inadvertently waking the display and audio at undesirable times, such as when the user is sleeping.

Tvwakeup.exe handles record reminders that occur while the system is suspended by tuning to the specified channel without waking the audio or video display.

In addition to using Tvx.exe or Tvwakeup.exe to display reminders, you can write a custom reminder application. For example, your custom reminder application can play music or animate the show reminder message.

Note that if you write a custom reminder application, you must also write an application to set show reminders. This is because WebTV for Windows only supports setting show reminders that specify Tvx.exe and Tvwakeup.exe as the display applications.

In addition, a custom reminder application may use command-line parameters other than those specified in Show Reminder Format. If so, the application that sets the show reminder must support the custom command-line syntax.

For information about creating custom applications to set show reminders, see Scheduling Show Reminders.


Show Reminder Format

You can use the following syntax to launch a show reminder, either from the command line or programmatically as a task in the Task Scheduler. If you use Microsoft® WebTV® for Windows® to create a show reminders, it sets the following parameters in the Run property of tasks that it schedules in the Task Scheduler. For more information, see Scheduling Show Reminders.

Show Reminder Syntax

The following shows the syntax for WebTV for Windows show reminders.

RemindApp /b ShowReference /u User /a MoreRemindAppParameters
Show Reminder Parameters

The following lists and describes the parameters used in show reminder syntax.

RemindApp
String that specifies the path and filename of reminder application on the user's machine, for example C:\Program Files\TV Viewer\Tvx.exe. When the reminder runs, the RemindApp application displays the show reminder to the user.

This application can be Tvx.exe, Tvwakeup.exe, or a custom application that you create. For more information, see Show Reminder Applications.

ShowReference
String that contains a properly formatted show reference. For more information about the show reference format, see Show References.

You can create a show reference programmatically by calling either the ITelevisionServices::MakeLocalBroadcastSchedule or ITelevisionServices::MakeRemoteBroadcastSchedule method.

User
String containing the name of the user that set the reminder.
MoreRemindAppParameters
String that contains additional parameters passed to the application that displays the show reminder. If you have written a custom show reminder application, the format can be any command-line parameters implemented in the reminder application.

If you are using Tvx.exe or Tvwakeup.exe to display the show reminder, this string should be formatted as follows:

"tvviewer!Type![ShowDuration!]"

Type
Flag value that specifies the type of reminder. The following table lists and describes the possible values for Type.
Value | Meaning
Remind | A reminder to watch a show. This flag causes WebTV for Windows to remind a viewer a show is on. The viewer can then tune manually to the show.
Record | A reminder to record a show. This flag causes WebTV for Windows to tune to a show automatically. If the viewer sets a recording device to receive output at that time, the show is recorded.

If the reminder is a record reminder, your application should use the Task Scheduler to set the TASK_FLAG_SYSTEM_REQUIRED flag for the reminder. Doing so causes WebTV for Windows to tune to the specified channel even if Broadcast Architecture is suspended. Otherwise, if the system is suspended WebTV for Windows does not run the record reminder.

In addition, if the record reminder has an application associated with it that automates tuning a VCR to a specified channel, this application should be specified in the registry value StartRecordingApp, EndRecordingApp, or both. You specify these values under the following registry key:

HKLM\Software\Microsoft\TV Services\Explorer\

TASK_FLAG_SYSTEM_REQUIRED should not be set for standard show reminders. Version 1.0 of Broadcast Architecture does not handle show reminders that occur while the operating system is suspended.

ShowDuration
Optional parameter that specifies the length of the show, in minutes.

Your application can obtain the WebTV for Windows path information programmatically by calling the ITelevisionServices::get_DatabaseFile method to find the location of the database, which is installed in the same location as the WebTV for Windows executable file, Tvx.exe. Your application must then remove the database file name from the string that the ITelevisionServices::get_DatabaseFile method returns.

Show Reminder Examples

The following are examples of show reminder strings. This is the syntax that is set in the Run parameter of the task in the Task Scheduler. You can use this same syntax to start a show reminder from the command line.

"C:\Program Files\TV Viewer\Tvx.exe" /b "1998/4/22!73/1/0
!2:0!0!0!0!0!0!0!0!0!''!'MSNBC'!'Cable'!38!'InterNight'"
/u "GuestUser" /a "tvviewer!Remind!60!"

The following show reminder uses WebTV for Windows to remind the user that the show is about to begin. When the reminder runs, WebTV for Windows displays a dialog box.

"C:\PROGRAM FILES\TV VIEWER\TVX.EXE" /b "1998/3/13!0/0/0!23:35
!0!0!0!0!0!0!0!0!''!'MSNBC'!'Cable'!3!'Time & Again'" /u "GuestUser"
/a "tvviewer!Remind!30!"

The following show reminder is identical to the one preceding, except that it has been set as a record reminder. Notice that keyword Remind has been replaced by Record and that the application used to display the reminder is Tvwakeup.exe instead of Tvx.exe.

"C:\PROGRAM FILES\TV VIEWER\TVWAKEUP.EXE" /b "1998/3/13!0/0/0!23:35
!0!0!0!0!0!0!0!0!''!'MSNBC'!'Cable'!4!'Time & Again'" /u "GuestUser"
/a "tvviewer!Record!30!"


Overview of Program Guide Services

The Program Guide provided by Broadcast Architecture displays television and supports data services that broadcast television-schedule information to the user. In addition, users can use the Program Guide to tune to a specific show in the schedule and set reminders to watch shows.

In developing Broadcast Architecture applications, you use Television System Services (TSS) to set up scheduling and control of television shows to be viewed through the Program Guide. Various broadcast client components can use TSS, including the Microsoft® ActiveX® control for video (the Video control), the Video control's underlying Microsoft® DirectShow™ filters, and the Video Access server.

The TSS application programming interface (API) is available through Automation, as methods and properties of the ITelevisionServices interface and the supporting IScheduledItems interface.

The Program Guide maintains current information about program schedules in a Microsoft® Jet database, Tss.mdb. Because broadcast schedule information constantly changes, this Guide database must acquire and update broadcast data on a regular basis. This acquisition and update is done using a loader application.

The following topics examine Program Guide services:

  • Guide Data describes the various problems involved in integrating Program Guide information from multiple networks. This section also discusses how dynamic-link libraries (DLLs) can be used to load data into the Guide database.
  • Guide Database Loaders outlines the tasks that any loader application for the Guide database must complete to operate successfully. This section also includes details about how to write a custom loader application.
  • Loadstub discusses how to work with the Loadstub component, Loadstub.exe, which starts a loader DLL.
  • Guide Data Objects covers a set of objects that applications use to retrieve or set values in the Guide database.
  • Guide Database Schema provides a detailed description of the tables and fields in the Guide database.
  • Program Guide Registry Entries defines the entries created in the operating-system registry for tuning spaces and their associated loader applications.


Guide Data

As viewers tune to various channels on various broadcast sources, they expect the Program Guide to give them current information about programs being broadcast from all sources available. Meeting this information need poses several challenges, as discussed in the following sections:

  • About Guide Data
  • Using Guide Data


About Guide Data

Guide data comes from various locations in various formats. Often, the Program Guide combines information from multiple broadcast sources, each of which has its own channel numbering scheme. For more information on working with Guide data from multiple sources, see the following topics:

  • Multiple Data Sources, which describes possible sources of Program Guide data.
  • Overlapping Channels, which explains Broadcast Architecture concepts on integrating Program Guide data from multiple sources into a single data set.


Multiple Data Sources

The Program Guide can obtain program data from various suppliers and in various formats. A satellite service provider may supply Program Guide data over one of the provided satellite channels. A local cable operator may supply Program Guide data through a vendor that sells subscriptions to such data downloaded from the Internet nightly. Satellite broadcast schedules may arrive as data packets from the satellite, and cable TV program data may arrive as a downloaded file or data transmitted over the vertical blanking interval (VBI) in the analog television signal.

The following illustration shows some of the various possible data sources feeding the Guide database.


Overlapping Channels

The Program Guide may have to combine information about multiple broadcast sources. For example, data from the local cable company may have to reside in the Program Guide along with data from a satellite service provider. This potential requirement can be problematic when channels from different systems use the same channel numbers.

To deal with issues arising from overlapping channel numbers, Broadcast Architecture implements the idea of tuning spaces. A tuning space is a set of nonoverlapping channels that are all available through the same type of physical channel tuner, such as an analog cable tuner. A broadcast client with multiple tuning devices may provide channels from multiple tuning spaces.

A physical device may support more than one tuning space. For example, if someone moves an analog receiver from San Francisco to Seattle, that person finds that channel 3 on broadcast television is different in the two cities. A viewer with both a cable connection and a conventional broadcast antenna, using a switch box to select between providers, has inputs that represent two tuning spaces. The Program Guide must be able to handle and display information for more than one tuning space.

In addition, a channel in a single tuning space can be shared by multiple broadcast content providers. For example, channel 21 might broadcast network 1 from 9 P.M. to 9 A.M., and network 2 from 9 A.M. to 9 P.M. The Program Guide must also be able to handle and display such shared channels.


Using Guide Data

To maintain current information, new data must be uploaded to the Guide database. This uploading is performed by Guide database loaders. For more information, see the following topics:

  • Moving Data to the Program Guide. This topic discusses dynamic-link libraries (DLLs) used by the loader application to map various data formats to the model used by the broadcast client.
  • Updating the Guide Database. This topic describes the general process by which a loader DLL updates Program Guide data in the Broadcast Architecture database.


Moving Data to the Program Guide

For any given broadcast service, one or more sources may provide Program Guide data. Because of the number of sources and formats for Program Guide data, it would be unwieldy for the Program Guide to directly receive Program Guide data. There are simply too many variations. To address this problem, Broadcast Architecture uses database loader programs that can be written for any given data source. Each tuning space has an associated Guide database loader. For more information on Guide database loaders, see Guide Database Loaders.

The following illustration shows the relationship between a database loader and the Guide database.


Updating the Guide Database

The process of loading current information into the Guide database begins with the Loadstub component of Broadcast Architecture. This component calls a loader to load data into the database. Which loader to call is specified in the Loadstub arguments when Loadstub runs.

Typically, you set the Loadstub component as a task in the Task Scheduler. Making Loadstub a task allows the Program Guide data for the tuning space associated with the specified loader to be automatically updated at regular intervals. The task for a particular tuning space specifies that Loadstub should be run and the globally unique identifier (GUID) of the appropriate database loader DLL.

At the time designated by the task, the Task Scheduler runs the stub program (Loadstub.exe), passing the GUID of the appropriate loader DLL along with other command options. The stub program reads entries in the computer registry to identify the location and file name of the loader DLL based on the specified GUID. Then Loadstub uses the location and filename found to load the specified loader and call it.

The following illustration shows how the system starts the loader DLL.

For details about the information that needs to be in the registry to support tuning spaces and Guide database loaders, see Program Guide Registry Entries. For more information on creating and using Guide database loaders, see Guide Database Loaders.


Guide Database Loaders

For each tuning space, a corresponding Guide database loader exists. A database loader typically:

  • Accesses the Guide database.
  • Acquires Program Guide data from a specified source.
  • Maps data from the Program Guide source to the appropriate fields in the Guide database.
  • Updates the database with the new data.

Guide database loaders are dynamic-link libraries (DLLs). The specifics of creating a Guide database loader vary depending on:

  • Tuning spaces supported.
  • Source of the Program Guide data (for example, downloaded from the Internet versus broadcast live).
  • Format of the Program Guide data.
  • Correlation between the provided data and the Guide database schema.

Updating the Guide database involves accessing the Microsoft® Jet database engine from the loader DLL. For more information on creating and working with loaders, see the following topics:

  • About Guide Database Loaders
  • Using Guide Database Loaders

To locate information on accessing a Jet database, see Further General Information.


About Guide Database Loaders

A Guide database loader accesses available Program Guide sources, receives new data, maps data to tables and fields in the Guide database, and then loads the new data into the Guide database. Such a loader may process multiple tuning spaces. For example, a database loader for analog networks may process data for both cable and over-the-air broadcasts.

The following illustration shows the relationship between a database loader and the Guide database.

Any loader DLL that runs in the context of Broadcast Architecture should implement the following functionality:

  • Sending loader event notifications
  • Performing tuning space maintenance
  • Processing quit events
  • Implementing the entry-point function

In addition to the preceding, it is recommended that loader DLLs, if appropriate, support the /I:data_location command-line parameter that Loadstub passes to the loader. The recomended behavior for this argument is to override the default location of Program Guide data for testing or other purposes. For more information on /I:data_location, see Using Loadstub.


Sending Loader Event Notifications

Your loader DLL should send broadcast window messages when loader events occur. These messages can be sent using either the SendMessageTimeout or PostMessage function, both part of the Microsoft® Win32® application programming interface (API). To locate more information about SendMessageTimeout and PostMessage, see Further Information on Program Guide Services for the Client.

The following table lists and describes the possible broadcast messages and the events they indicate.

Message | Event
EPGLDR_ACTIVE_COMMIT_END | The loader has finished updating records. Applications that cache Program Guide data should reload the cached data now.
EPGLDR_ACTIVE_COMMIT_START | The loader is beginning to update records. Applications that cache Program Guide data will need to reload the Program Guide data when updating ends.
EPGLDR_ENDING | The loader is finished updating the Guide data. This message is sent by Loadstub and does not need to be sent by your loader DLL.
EPGLDR_EXCLUSIVE _END | The loader has finished an operation that requires exclusive access to the Guide database. This message is sent by Loadstub and does not need to be sent by your loader DLL.
EPGLDR_EXCLUSIVE_START | The loader is beginning an operation that requires exclusive access to the Guide database. This message is sent by Loadstub and does not need to be sent by your loader DLL.
EPGLDR_PASSIVE_COMMIT_END | The loader has finished updating records. Applications that cache Program Guide data do not need to reload the Program Guide data.
EPGLDR_PASSIVE_COMMIT_START | The loader is beginning to update records. Applications that cache Program Guide data do not need to reload the Program Guide data.
EPGLDR_STARTING | The loader starts to run. This message is sent by Loadstub and does not need to be sent by your loader DLL.


Maintaining a Tuning Space

Each loader DLL should clean up its corresponding tuning space. Cleaning the tuning space keeps the Guide database from growing too large by removing out of date data. This cleanup consists of the following actions:

  • Deletion of records in the Channel, Episode, Station and Theme tables that are no longer being referenced in other tables.
  • Deletion of expired records from the Time Slot table. Expired records are records whose end time is more than one day in the past.
  • Deletion of duplicate time slots from the Time Slot table. Duplicate time slots are identical or overlapping time slots specified for the same show. For example, if a show is listed as broadcasting on a particular channel from 10 A.M. to 12 P.M., and the loader adds a new time slot for that show from 10:30 to 11:30 A.M. on the same channel, one of the time slot entries should be removed.

These actions can be performed by running the cleanup queries defined in the Guide database. For more information on these queries, see Guide Database Query Reference.


Processing Quit Events

While a loader is loading data into the Guide database loadstub cannot check for messages from the operating system. Thus, there is no way for the loader to receive a notification to quit processing.

Instead, Loadstub monitors the operating system message queue for quit event notifications. At convenient times in loader processing, your loader should call the function at the address in pfnForceQuit. Note that Loadstub.exe passes this address to the loader through a parameter for the DLL's entry-point function. This function enables Loadstub to forward quit event notifications to the loader so that the loader can stop processing, if necessary.

Your loader can implement this functionality by calling the following code whenever loader processing can be gracefully stopped

if ((*pfnForceQuit()){
  //Code to clean up and gracefully exit the loader
}

where pfnForceQuit was passed in the entry-point function.


Implementing the Entry-Point Function

A database loader DLL must implement a standard entry-point function for Loadstub to call. The call to that entry-point function starts the DLL code that loads data into the Guide database. The entry-point function must be named EPG_DBLoad.

The prototype for this function is

ExitCodeList APIENTRY
EPG_DBLoad(int &argc, _TCHAR **argv, CdbDBEngine &db
    , PFNFORCEQUIT pfnForceQuit);

where the first two parameters are the command line parameters as you would see in a main function of a standard C program. The next parameter is a reference to the database, and the final parameter is the address of the quit-processing callback function. This callback function returns TRUE if the operating system is trying to shut down the loader, and FALSE otherwise.

Note The sample loader, Load.cpp, already contains an implementation of EPG_DBLoad. Thus, if you build your loader using the Load framework, you do not need to implement this function. For more information on Load, see Broadcast Architecture Sample Applications. For more information on writing a loader, see Writing a Custom Guide Database Loader.


Using Guide Database Loaders

Your application can either use a Guide database loader provided Broadcast Architecture or a custom loader. The loader currently provided with Broadcast Architecture adds television-schedule data for the Gemstar G-Guide system to the Guide database. To work with other types of data, you must have a custom loader for that data.

For more information, see:

  • Using Loaders Provided by Broadcast Architecture
  • Writing a Custom Loader


Using Loaders Provided by Broadcast Architecture

Broadcast Architecture currently provides a loader that adds Gemstar G-Guide programming data to the Guide database. This loader loads information from a data file that can be downloaded from the World Wide Web or received over the vertical blanking interval of a television broadcast.

For this loader, a data location may be stored in an entry under the loader's registry key. This data location is the name of the file to use for input, for example C:\ProgramFiles\Program GuideData\Ssdata.bin. For more information on loader registry keys, see Loaders Subkey.

The data file created for the Gemstar G-Guide loader can come by a number of means, for example by television tuner signal or Internet channel.


Writing a Custom Loader

Broadcast Architecture provides a sample loader framework that you can use to quickly develop a custom loader. This sample loader, Load.cpp, implements a class, CLoadApp, that contains all of the functionality of a database loader. The sample demonstrates the use of the Guide data objects to create a new show and schedule it. The Guide data objects provide a programmatic interface to the data in the Guide database, using which your application can easily create records, delete records, retrieve field values, and set field values. To locate this sample loader, see Broadcast Architecture Sample Applications.

To make your own loader based on the sample, all you need to do is modify the CLoadApp::Handle method in the sample to load your data into the Guide database using the Guide data objects.

Even if you do not use the provided loader framework, it is recommended that you use the Guide data objects. These objects are fully tested and debugged and save you from having to reimplement their functionality.

For further information on writing a custom loader, see Writing a Custom Guide Database Loader.


Guide Database Query Reference

The Guide database contains several queries that your application can run to remove unused or out-of-date data records. These queries can be run programmatically from the loader library by using a method such as CLoadApp::ExecuteActionQuery that executes the queries for clena up the database.This method is implemented in the Load sample loader provided with Broadcast Architecture. For more information, see Writing a Custom Loader.

The Guide database contains the following cleanup queries.

Query | Action
Delete Dangling Channel | Deletes all records from the Channel table that do not have a matching entry in the Time Slot table.
Delete Dangling Episode | Deletes all records from the Episode table that do not have a matching entry in the Time Slot table.
Delete Dangling Station | Deletes all records from the Station table that do not have a matching entry in the Channel table.
Delete Dangling Theme | Deletes all records from the Theme table that do not have a matching entry in the Episode table.
Delete Expired Time Slot | Deletes all time slots with end times earlier than the specified time.
Delete Omitted Time Slot | Deletes duplicate time slots. Duplicate time slots are identical or overlapping time slots specified for the same show. This query deletes the duplicate time slot with an earlier time in its Last Updated field. For efficiency, your application should pass the start time and end time of the period for which to eliminate duplicates, and also the tuning space.


Loadstub

The Loadstub component, Loadstub.exe, starts a loader dynamic-link library (DLL). Typically, Loadstub is automatically started as a task in the Task Scheduler in the Microsoft® Windows® 98 operating system. Using this stub application provides a common interface for loader DLLs that themselves may be quite divergent in approach.

For more information on working with Loadstub, see the following topics:

  • About Loadstub, which describes what Loadstub does.
  • Using Loadstub, which details parameters your loader can set for Loadstub.


About Loadstub

Guide database loaders are all called as needed by a standard loader stub program. This stub program, Loadstub.exe, is scheduled to run at appropriate times to update the Guide database.

When the stub program starts, it first parses the command line for recognized options. The options Loadstub recognizes are /X, /R, /C, /E and /LEH; for more information on these options, see Using Loadstub. Loadstub passes any other options on to the loader. Loadstub parses options in this order:

  1. It executes the /X option to replace the database, if it exists.
  2. It starts the Microsoft® Jet database engine.
  3. It executes the /R option to repair the database, if this option exists, and does a quick check and repair of corruption errors if it does not.
  4. It executes the /C option to compact the database, if the option exists. The /C also repairs the database before compaction.
  5. It executes the /E option, if it exists, to empty a specified tuning space.
  6. It executes the /LEH option to load the specified enhancements file, if the option exists.

Once Loadstub has parsed all options, it:

  1. Uses the globally unique identifier (GUID) from the command line to extract the name of the loader DLL from the registry.
  2. Extracts user and password information from the loader.
  3. Opens a workspace in the DAO database named LoaderWSP and a user named loader.
  4. Creates a window message by calling the RegisterWindowMessage function, part of the Microsoft® Win32® application programming interface (API). On the RegisterWindowMessage call, Loadstub passes the string representation of the loader's GUID.
  5. Broadcasts an EPGLDR_STARTING message to notify broadcast client applications that the database is receiving updated data. For more information on broadcast window messages, see Sending Loader Event Notifications.
  6. Starts the loader DLL.
  7. Broadcasts an EPGLDR_ENDING message to notify client applications that the database update is completed and to indicate success or failure.
  8. Updates the LastAttempt and LastRun entries in the Program Guide Loaders key of the system registry.


Using Loadstub

The Loadstub component is typically run as a task by the Task Scheduler. For more information on setting up Loadstub to run from Task Scheduler, see:

  • Loadstub Syntax
  • Enhancements Control File and Text Files


Loadstub Syntax

When this is the case, you specify the following syntax in the Run field of a scheduled task

PathLoadstub.exe /L:Loader_GUID [Options]

where the Path, Loader_GUID, and Options parameters are defined as follows:

Path
Path to the Loadstub.exe component. If the path contains spaces, the path and file name must be surrounded by quotation marks ("), for example: "C:\Program Files\TV Viewer\Loadstub.exe"
Loader_GUID
Globally unique identifier (GUID) of the loader. This parameter is required.
Options
Additional optional arguments. These can be any combination of the following.
Argument | Description
/C | Specifies to repair and compact the database.
/E:Tuning Space GUID | Empties all data from the specified tuning space. If the Tuning Space GUID is not specified, Loadstub empties the tuning space for the loader given in the /L argument
/R | Specifies to repair the database.
/X | Specifies to replace the database. The replacement file is specified by the registry entry DBReplacementFile, under the TV Services registry key. Specifying DBReplacementFile enables an application to replace a database programmatically.
/P Specifies a partial update. This option allows a loader to implement a "quick" mode and a normal mode. For example, in "quick" mode, a loader might only gather the next four hours of Program Guide data, rather than the next two-and-a-half days.

Note: Because the data format varies between loader libraries, this parameter is not handled by the Loadstub component. Instead, Loadstub passes the parameter as an argument to the loader. Thus, in order for this parameter to work, it must be supported by the loader.
/I:data_location Specifies the location of the data file. If this parameter is not set, Loadstub uses the location stored in the registry. For the Gemstar G-Guide loader, this parameter specifies the name of the data file.

Note: Because the type of data passed into this command-line parameter varies, this parameter is not handled by the Loadstub component. Instead, Loadstub passes the parameter as an argument to the loader. Thus, in order for this parameter to work, it must be supported by the loader.
/LEH filename | Loads the named enhancement file.

The following example runs the Gemstar G-Guide loader, loading data from C:\Windows\Temporary Internet Files\Ssdata.bin instead of the location specified in the registry.

"C:\Program Files\TV Viewer\LOADSTUB.EXE" /L:{C94D1940-9F69-11d0-BDB8-0000F8027346} /P /I:"C:\Windows\Temporary Internet Files\ssdata.bin"

Note that because the path to the data contains spaces, it is surrounded by quotation marks. You can also use the short directory names, as shown following:

C:\Progra~1\TV Viewer\LOADSTUB.EXE /L:{C94D1940-9F69-11d0-BDB8-0000F8027346} /P /I:C:\Windows\Tempor~1\ssdata.bin


Enhancements Control File and Text Files

When using the the /LEH option you must specify the name of an enhancements control file. The enhancements control file is a INI file that DAO uses to update fields in the Guide database from information in a text file. The enhancements control file contains this text:

[DataFile.txt]
Format=TabDelimited
ColNameHeader=False
CharacterSet=ANSI
Col1=ID Text
Col2=Title Text
Col3="Show Reference" Text
Col4="Preload URL" Text
Col5=Address Text
Col6="Expire Date" DateTime

You must replace DataFile.txt with the name of a text file containing the enhancement data. This text file must be in the same directory as the enhancements control file. Each line in the enhancement data file is a record representing an enhancement. The fields of this record are seperated by tabs and are the same as those used in the Enhancement Table, but in the order given in the enhancements control file.


Guide Data Objects

The Guide data objects are a set of objects that applications can use to retrieve or set values in the Guide database. They wrap the Data Access Object (DAO) code necessary to access the Guide database's records and fields.

It is recommended that your loader application use the Guide data objects because they provide a convenient and tested programmatic interface to the records and fields of the Guide database.

These objects are also used internally by the Microsoft® WebTV® for Windows® component and the database loader applications installed with the Broadcast Architecture.

For more information, see the following topics:

  • About Guide Data Objects, which describes the architecture and inheritance of the Guide data objects.
  • Using Guide Data Objects, which explains how to use the Guide data objects to manipulate the records and fields in the Guide database.
  • Guide Data Object Reference, which provides detailed descriptions of the methods exposed by the Guide data objects.

To compile programs that use the Guide data objects, the Dbsets.h header file must be in the Include directory of your C/C++ compiler. You must also include header files for each recordset object that you use. For example, if your loader uses the CNetworkRecordset and CNetwork objects to access information about television networks, the loader must include the file Network.h. In addition, your application should link to the Dbsets.dll dynamic-link library.

To locate more information on working with DAO, see Further General Information.


About Guide Data Objects

The following diagram illustrates the inheritance structure of the Guide data objects. In this diagram, C TableName Recordset represents a recordset object that corresponds to the TableName table in the Guide database, and C TableName represents the record object associated with that recordset object. The objects derived from CDatabaseRecordset represent records in the database. The objects derived from CObject represent the fields within the record.

The CDatabaseConnection class is the base class of the Guide data object set and is used to open and close a workspace and to connect to a database.

The CDatabaseRecordset class is an abstract base class that defines generic recordset functionality. This class provides methods for such operations as adding and deleting records. It inherits from CDatabaseConnection and is in turn inherited by each of the table-specific recordset classes represented by C TableName Recordset.

The C TableName Recordset objects expand on the generic recordset functionality inherited from CDatabaseRecordset by re-implementing the GetTableName, GetRecordsetObject, SetRecordsetObject, and Seek methods to be specific to the table that they wrap.

The C TableName objects inherit from the Microsoft® Foundation Classes (MFC) base class, CObject. The C TableName objects are returned by C TableName Recordset::GetRecordsetObject and each wrap a single record in the table. These objects provide methods that enable you to retrieve or set values for individual fields in records.

To locate more information on CObject, see Further Information on Program Guide Services for the Client.


Using Guide Data Objects

The Guide data objects provide a set of recordset objects, named in the format C TableName Recordset, that each connect to the table in the Guide database indicated by TableName. Using these objects, you can:

  • Open a recordset.
  • Fetch, update, insert, and delete records.
  • Close the recordset.

As an example of using these techniques, see:

  • Adding a Station to the Program Guide
  • Adding a Channel to the Program Guide

The recordset objects do not contain record data themselves. Instead, they create C TableName record objects to store the data. Each C TableName object corresponds to a single record in the Guide database.

A recordset or record object can be repeatedly opened and closed without the need for deleting an object and re-instantiating a new object. You can open a recordset by calling either the OpenRecordset or OpenIndexed method of the appropriate recordset object. For example, you can access the records of the Episode table using the CEpisodeTRecordset object. To open a recordset, you can call either the CEpisodeTRecordset::OpenRecordset or CEpisodeTRecordset::OpenIndexed method.

When a recordset is opened by the Jet database engine, it can be opened as either a dynaset or snapshot. A dynaset is essentially a list of pointers to the records in the table. In other words, data is only read from the database when a record is retrieved. A snapshot reads all records in the set into a RAM cache. Part of the design process for an application that uses the Jet database engine is to determine the type of acccess required. You should consult the DAO documentation for more information on the trade-offs involved.

By default, the Jet engine opens recordsets as dynasets. You can specify that the Jet engine open a recordset as a snapshot by setting a value for the optional nOpenType parameter of the appropriate OpenIndexed method.

Note also that the record count for a recordset is not automatically defined when you open the recordset. Therefore, when your application calls the appropriate GetRecordCount method, the method must move to the last record in the set to count the records. This process can be slow for large recordsets. To avoid counting, your application can open a recordset with an ORDER BY clause, which correctly sets the initial record count.

Once your application has opened a recordset, it can retrieve a record object from the recordset by calling the GetRecordsetObject or GetRecord methods of the corresponding recordset object. The former method returns a C TableName object that wraps the current recordset. The latter method returns an object that wraps the record in the recordset indicated by the specified index. Using the C TableName object, you can retrieve or set field values for the indexed record.

For example, you can get an individual Episode record by calling the CEpisodeTRecordset::GetRecord or CEpisodeTRecordset::GetRecordsetObject methods. Both methods create a CEpisodeT object. You can then manipulate the field values of the Episode record by using the methods of the CEpisodeT object.


Adding a Station to the Program Guide

The following example uses the Guide data objects to add a station to Program Guide.

//Define a station
CStation cs(AFX_RFX_LONG_PSEUDO_NULL
        , _T("KBPC"), _T("Knowledge Base PC")
        , 0, __T("kbpc.bmp"), _T("Cool Broadcast Architecture station"));

//Insert the station into Tss.mdb
s->UpdateRS(cs);

Note The Microsoft® WebTV® for Windows® component requires that station call letters be uppercase with no leading or trailing spaces. Call letters, such as KBPC in the preceding example, identify a particular broadcast station.


Adding a Channel to the Program Guide

The following example creates a new channel.

//Define a channel
CChannelT cct(AFX_RFX_LONG_PSEUDO_NULL, m_lTuningSpace, 42
    , codtDummy, codtDummy, 0, cs.StationID()
    , _T("Broadcast Architecture channel"), _T("attachedWebPage.htm")
    , 1, 1, 1, 1, COleDateTime::GetCurrentTime());

Note The Add Record index of the Channel table contains the record number of the station entry to be associated with a channel. This functionality means that before a channel can be added, its associated station record must already exist in the Guide database. See Adding a Station to the Program Guide.


Guide Data Object Reference

The following initialization methods are implemented outside of the Guide data object classes. Note that you must call the SetJet method to allocate storage space before you can use the Guide data objects.

Method | Description
GetDatabase | Returns a DAO database object with the local static storage passed in to SetJet.
GetDatabaseConnected | Returns a value that indicates whether a CDatabaseConnection object is connected to the database.
SetJet | Passes in local static storage for the Jet engine, workspace, and database.

The following table lists the Guide data object base classes.

Class | Description
CDatabaseConnection | Provides the root encapsulation of the Microsoft® Jet database engine.
CDatabaseRecordset | An abstract base class that provides generic recordset functionality.

The following table lists the Guide Data recordset object classes.

Class | Description
CBroadcastPropertyRecordset | Connects to a Broadcast Property table recordset.
CChannelPropertyRecordset | Connects to a Channel Property table recordset.
CChannelStreamRecordset | Connects to a Channel Stream table recordset.
CChannelTRecordset | Connects to a Channel table recordset.
CEnhancementRecordset | Connects to a Enhancement table recordset.
CEpisodePropertyRecordset | Connects to a Episode Property table recordset.
CEpisodeTRecordset | Connects to a Episode table recordset.
CGenreRecordset | Connects to a Genre table recordset.
CNetworkRecordset | Connects to a Network table recordset.
CRatingRecordset | Connects to a Rating table recordset.
CRatingSystemRecordset | Connects to a Rating System table recordset.
CStationRecordset | Connects to a Station table recordset.
CStreamTypeRecordset | Connects to a Stream Type table recordset.
CSubGenreRecordset | Connects to a Sub-Genre table recordset.
CThemeRecordset | Connects to a Theme table recordset.
CTimeSlotRecordset | Connects to a Time Slot table recordset.

The following table lists the Guide Data record object classes.

Class | Description
CBroadcastProperty | Wraps a Broadcast Property table record.
CChannelProperty | Wraps a Channel Property table record.
CChannelStream | Wraps a Channel Stream table record.
CChannelT | Wraps a Channel table record.
CEnhancement | Wraps a Enhancement table record.
CEpisodeProperty | Wraps a Episode Property table record.
CEpisodeT | Wraps a Episode table record.
CGenre | Wraps a Genre table record.
CNetwork | Wraps a Network table record.
CRating | Wraps a Rating table record.
CRatingSystem | Wraps a Rating System table record.
CStation | Wraps a Station table record.
CStreamType | Wraps a Stream Type table record.
CSubGenre | Wraps a SubGenre table record.
CTheme | Wraps a Theme table record.
CTimeSlot | Wraps a Time Slot table record.


GetDatabase

The GetDatabase method return a pointer to a Data Access Objects (DAO) database object. This method should be called after you have connected to a database by using the ConnectToDatabase method.

CdbDatabase * GetDatabase(void);

Parameters

None.

Return Values

A pointer to a CdbDatabase object.

Remarks

To locate more information about DAO and the CdbDatabase object, see Further Information on Program Guide Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


GetDatabaseConnected

The GetDatabaseConnected method returns a value indicating whether a CDatabaseConnection object has a connection to the database. In other words, whether a previous call to ConnectToDatabase was successful.

BOOL GetDatabaseConnected(void);

Parameters

None.

Return Values

If a CDatabaseConnection object is connected to the database, this method returns TRUE. Otherwise, it returns FALSE.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


SetJet

The SetJet method passes in local static storage for the Data Access Objects (DAO) engine, workspace, and database objects. This method must be called before you can call any of the methods of the Guide data objects.

void SetJet(
  CdbWorkspace* pWorkspace,
);

Parameters

pEngine
A pointer to a DAO CdbDBEngine object.
A pointer to a DAO CdbWorkspace object.

A pointer to a DAO CdbDatabase object.

Return Values

This method does not return a value.

Remarks

To locate more information about DAO and the CdbDBEngine, CdbWorkspace, and CdbDatabase objects, see Further Information on Program Guide Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastProperty

Each CBroadcastProperty object corresponds to a single record of the Broadcast Property table in the Guide database. These objects are created and initialized by CBroadcastPropertyRecordset objects.

You can use the following methods to set and retrieve the field values of a CBroadcastProperty object.

The CBroadcastProperty class provides the following methods:

Method | Description
SetTuningSpace | Sets the value of the BP Tuning Space field.
SetAbbreviation | Sets the value of the BP Abbreviation field.
SetName | Sets the value of the BP Name field.
SetDisplayOrder | Sets the value of the BP Display Order field.
SetPictogramMoniker | Sets the value of the BP Pictogram Moniker field.
BroadcastPropertyID | Retrieves the value of the BP Broadcast Property ID field. This field is automatically generated and cannot be set.
TuningSpace | Retrieves the value of the BP Tuning Space field.
Abbreviation | Retrieves the value of the BP Abbreviation field.
DisplayOrder | Retrieves the value of the BP Display Order field.
PictogramMoniker | Retrieves the value of the BP Pictogram Moniker field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastProperty::Abbreviation

The Abbreviation method returns the value of the BP Abbreviation field from the CBroadcastProperty record object.

CString Abbreviation(void);

Parameters

None.

Return Values

The value of the BP Abbreviation field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastProperty::BroadcastPropertyID

The BroadcastPropertyID method returns the value of the BP Broadcast Property ID field from the CBroadcastProperty record object.

long BroadcastPropertyID(void);

Parameters

None.

Return Values

The value of the BP Broadcast Property ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastProperty::DisplayOrder

The DisplayOrder method returns the value of the BP Display Order field from the CBroadcastProperty record object.

long DisplayOrder(void);

Parameters

None.

Return Values

The value of the BP Display Order field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastProperty::Name

The Name method returns the value of the BP Name field from the CBroadcastProperty record object.

CString Name(void);

Parameters

None.

Return Values

The value of the BP Name field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastProperty::PictogramMoniker

The PictogramMoniker method returns the value of the BP Pictogram Moniker field from the CBroadcastProperty record object.

CString PictogramMoniker(void);

Parameters

None.

Return Values

The value of the BP Pictogram Moniker field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastProperty::SetAbbreviation

The SetAbbreviation method sets the value of the BP Abbreviation field in the CBroadcastProperty record object.

void SetAbbreviation(
  LPCTSTR cszAbbreviation
);

Parameters

cszAbbreviation
The BP Abbreviation value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastProperty::SetDisplayOrder

The SetDisplayOrder method sets the value of the BP Display Order field in the CBroadcastProperty record object.

void SetDisplayOrder(
  long lDisplayOrder
);

Parameters

lDisplayOrder
The BP Display Order value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastProperty::SetName

The SetName method sets the value of the BP Name field in the CBroadcastProperty record object.

void SetName(
  LPCTSTR cszName
);

Parameters

cszName
The BP Name value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastProperty::SetPictogramMoniker

The SetPictogramMoniker method sets the value of the BP Pictogram Moniker field in the CBroadcastProperty record object.

void SetPictogramMoniker(
  LPCTSTR cszPictogramMoniker
);

Parameters

cszPictogramMoniker
The BP Pictogram Moniker value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastProperty::SetTuningSpace

The SetTuningSpace method sets the value of the BP Tuning Space field in the CBroadcastProperty record object.

void SetTuningSpace(
  long lTuningSpace
);

Parameters

lTuningSpace
The BP Tuning Space value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastProperty::TuningSpace

The TuningSpace method returns the value of the BP Tuning Space field from the CBroadcastProperty record object.

long TuningSpace(void);

Parameters

None.

Return Values

The value of the BP Tuning Space field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CBroadcastPropertyRecordset

The CBroadcastPropertyRecordset class is used to retrieve and set CBroadcastProperty record objects from the BroadcastProperty table using methods defined in the CDatabaseRecordset parent class.

The CBroadcastPropertyRecordset class implements the following methods:

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Broadcast Property.
GetRecordsetObject | Initializes a CBroadcastProperty object with records from the Guide database.
SetRecordsetObject | Saves the records in a CBroadcastProperty object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in brprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelProperty

Each CChannelProperty object corresponds to a single record of the Channel Property table in the Guide database. You can use the methods of CChannelProperty to retrieve and set field values. These objects are created and initialized by CChannelPropertyRecordset objects.

The CChannelProperty class provides the following methods:

Method | Description
SetChannelID | Sets the value of the CP Channel ID field.
SetBroadcastPropertyID | Sets the value of the CP Broadcast Property ID field.
ChannelID | Retrieves the value of the CP Channel ID field.
BroadcastPropertyID | Retrieves the value of the CP Broadcast Property ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbrs.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelProperty::BroadcastPropertyID

The BroadcastPropertyID method returns the value of the CP Broadcast Property ID field from the CChannelProperty record object.

long BroadcastPropertyID(void);

Parameters

None.

Return Values

The value of the CP Broadcast Property ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbrs.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelProperty::ChannelID

The ChannelID method returns the value of the CP Channel ID field from the CChannelProperty record object.

long ChannelID(void);

Parameters

None.

Return Values

The value of the CP Channel ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbrs.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelProperty::SetBroadcastPropertyID

The SetBroadcastPropertyID method sets the value of the CP Broadcast Property ID field in the CChannelProperty record object.

void SetBroadcastPropertyID(
  long lBroadcastPropertyID
);

Parameters

lBroadcastPropertyID
The CP Broadcast Property ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbrs.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelProperty::SetChannelID

The SetChannelID method sets the value of the CP Channel ID field in the CChannelProperty record object.

void SetChannelID(
  long lChannelID
);

Parameters

lChannelID
The CP Channel ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbrs.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelPropertyRecordset

The CChannelPropertyRecordset class is used to select and create CChannelProperty objects from the Channel Property table using functions defined in the CDatabaseRecordset parent class.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Channel Property.
GetRecordsetObject | Initializes a CChannelProperty object with records from the Guide database.
SetRecordsetObject | Saves the records in a CChannelProperty object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbrs.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelStream

Each CChannelStream object corresponds to a single record of the Channel Stream table in the Guide database. You can use the methods of CChannelStream to retrieve and set field values. These objects are created and initialized by CChannelStreamRecordset objects.

The CChannelStream class provides the following methods:

Method | Description
SetChannelID | Sets the value of the CSR Channel ID field.
SetStreamTypeID | Sets the value of the CSR Stream Type ID field.
SetSubChannel | Sets the value of the CSR SubChannel field.
SetName | Sets the value of the CSR Name field.
ChannelID | Retrieves the value of the CSR Channel ID field.
StreamTypeID | Retrieves the value of the CSR Stream Type ID field.
SubChannel | Retrieves the value of the CSR SubChannel field.
Name | Retrieves the value of the CSR Name field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in chanstr.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelStream::ChannelID

The ChannelID method returns the value of the CSR Channel ID field from the CChannelStream record object.

long SetChannelID(void);

Parameters

None.

Return Values

The value of the CSR Channel ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in chanstr.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelStream::Name

The Name method returns the value of the CSR Name field from the CChannelStream record object.

CString Name(void);

Parameters

None.

Return Values

The value of the CSR Name field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in chanstr.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelStream::SetChannelID

The SetChannelID method sets the value of the CSR Channel ID field in the CChannelStream record object.

void SetChannelID(
  long lChannelID
);

Parameters

lChannelID
The CSR Channel ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in chanstr.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelStream::SetName

The SetName method sets the value of the CSR Name field in the CChannelStream record object.

void SetName(
  CString cszName
);

Parameters

cszName
The CSR Name value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in chanstr.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelStream::SetStreamTypeID

The SetStreamTypeID method sets the value of the CSR Stream Type ID field in the CChannelStream record object.

void SetStreamTypeID(
  long lStreamTypeID
);

Parameters

lStreamTypeID
The CSR Stream Type ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in chanstr.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelStream::SetSubChannel

The SetSubChannel method sets the value of the CSR SubChannel field in the CChannelStream record object.

void SetSubChannel(
  long lSubChannel
);

Parameters

lSubChannel
The CSR SubChannel value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in chanstr.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelStream::StreamTypeID

The StreamTypeID method returns the value of the CSR Stream Type ID field from the CChannelStream record object.

long StreamTypeID(void);

Parameters

None.

Return Values

The value of the CSR Stream Type ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in chanstr.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelStream::SubChannel

The SubChannel method returns the value of the CSR SubChannel field from the CChannelStream record object.

long SubChannel(void);

Parameters

None.

Return Values

The value of the CSR SubChannel field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in chanstr.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelStreamRecordset

The CChannelStreamRecordset class is used to select and create CChannelStream objects from the Channel Stream table using functions defined in the CDatabaseRecordset parent class.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Channel Stream.
GetRecordsetObject | Initializes a CChannelStream object with records from the Guide database.
SetRecordsetObject | Saves the records in a CChannelStream object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in chanstr.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT

Each CChannelT object corresponds to a single record of the Channel table in the Guide database. You can use the methods of CChannelT to retrieve and set field values. These objects are created and initialized by CChannelTRecordset objects.

The CChannelT class provides the following methods:

Method | Description
SetTuningSpace | Sets the value of the C Tuning Space field.
SetChannelNumber | Sets the value of the C Channel Number field.
SetStartTime | Sets the value of the C Start Time field.
SetEndTime | Sets the value of the C End Time field.
SetLength | Sets the value of the C Length field.
SetStationID | Sets the value of the C Station ID field.
SetDescription | Sets the value of the C Description field.
SetRatingID | Sets the value of the C Rating ID field.
SetDisplayMask | Sets the value of the C Display Mask field.
SetPaymentAddress | Sets the value of the C Payment Address field.
SetPaymentToken | Sets the value of the C Payment Token field.
SetLastUpdate | Sets the value of the C Last Update field.
SetTunable | Sets the value of the C Tunable field.
ChannelID | Retrieves the value of the C Channel ID field. This field is automatically generated and cannot be set.
TuningSpace | Retrieves the value of the C Tuning Space field.
ChannelNumber | Retrieves the value of the C Channel Number field.
StartTime | Retrieves the value of the C Start Time field.
EndTime | Retrieves the value of the C End Time field.
Length | Retrieves the value of the C Length field.
StationID | Retrieves the value of the C Station ID field.
Description | Retrieves the value of the C Description field.
RatingID | Retrieves the value of the C Rating ID field.
DisplayMask | Retrieves the value of the C Display Mask field.
PaymentAddress | Retrieves the value of the C Payment Address field.
PaymentToken | Retrieves the value of the C Payment Token field.
LastUpdate | Retrieves the value of the C Last Update field.
Tunable | Retrieves the value of the C Tunable field.
SetEnhMapID | Sets the value of the C Enhancement Mapping ID field.
EnhMapID | Retrieves the value of the C Enhancement Mapping ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::ChannelID

The ChannelID method returns the value of the C Channel ID field from the CChannelT record object.

long ChannelID(void);

Parameters

None.

Return Values

The value of the C Channel ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::ChannelNumber

The ChannelNumber method returns the value of the C Channel Number field from the CChannelT record object.

long ChannelNumber(void);

Parameters

None.

Return Values

The value of the C Channel Number field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::Description

The Description method returns the value of the C Description field from the CChannelT record object.

CString Description(void);

Parameters

None.

Return Values

The value of the C Description field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::DisplayMask

The DisplayMask method returns the value of the C Display Mask field from the CChannelT record object.

long DisplayMask(void);

Parameters

None.

Return Values

The value of the C Display Mask field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::EndTime

The EndTime method returns the value of the C End Time field from the CChannelT record object.

COleDateTime EndTime(void);

Parameters

None.

Return Values

The value of the C End Time field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::EnhMapID

The EnhMapID method returns the value of the C Enhancement Mapping ID field from the CChannelT record object.

CString EnhMapID(void);

Parameters

None.

Return Values

Returns the value of the C Enhancement Mapping ID field if successful.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

C Enhancement Mapping ID


CChannelT::LastUpdate

The LastUpdate method returns the value of the C Last Update field from the CChannelT record object.

COleDateTime LastUpdate(void);

Parameters

None.

Return Values

The value of the C Last Update field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::Length

The Length method returns the value of the C Length field from the CChannelT record object.

long Length(void);

Parameters

None.

Return Values

The value of the C Length field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::PaymentAddress

The PaymentAddress method returns the value of the C Payment Address field from the CChannelT record object.

long PaymentAddress(void);

Parameters

None.

Return Values

The value of the C Payment Address field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::PaymentToken

The PaymentToken method returns the value of the C Payment Token field from the CChannelT record object.

long PaymentToken(void);

Parameters

None.

Return Values

The value of the C Payment Token field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::RatingID

The RatingID method returns the value of the C Rating ID field from the CChannelT record object.

long RatingID(void);

Parameters

None.

Return Values

The value of the C Rating ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetChannelNumber

The SetChannelNumber method sets the value of the C Channel Number field in the CChannelT record object.

void SetChannelNumber(
  long lChannelNumber
);

Parameters

lChannelNumber
The C Channel Number value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetDescription

The SetDescription method sets the value of the C Description field in the CChannelT record object.

void SetDescription(
  LPCTSTR szDescription
);

Parameters

szDescription
The C Description value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetDisplayMask

The SetDisplayMask method sets the value of the C Display Mask field in the CChannelT record object.

void SetDisplayMask(
  long lDisplayMask
);

Parameters

lDisplayMask
The C Display Mask value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetEndTime

The SetEndTime method sets the value of the C End Time field in the CChannelT record object.

void SetEndTime(
  COleDateTime& EndTime
);

Parameters

EndTime
The C End Time value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetEnhMapID

The SetEnhMapID method sets the value of the C Enhancement Mapping ID field in the CChannelT record object.

void SetEnhMapID(
  LPCTSTR szEnhMapID
);

Parameters

szEnhMapID
C Enhancement Mapping ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

C Enhancement Mapping ID


CChannelT::SetLastUpdate

The SetLastUpdate method sets the value of the C Last Update field in the CChannelT record object.

void SetLastUpdate(
  COleDateTime& LastUpdate
);

Parameters

LastUpdate
The C Last Update value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetLength

The SetLength method sets the value of the C Length field in the CChannelT record object.

void SetLength(
  long lLength
);

Parameters

lLength
The C Length value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetPaymentAddress

The SetPaymentAddress method sets the value of the C Payment Address field in the CChannelT record object.

void SetPaymentAddress(
  long lPaymentAddress
);

Parameters

lPaymentAddress
The C Payment Address value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetPaymentToken

The SetPaymentToken method sets the value of the C Payment Token field in the CChannelT record object.

void SetPaymentToken(
  long lPaymentToken
);

Parameters

lPaymentToken
The C Payment Token value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetRatingID

The SetRatingID method sets the value of the C Rating ID field in the CChannelT record object.

void SetRatingID(
  long lRatingID
);

Parameters

lRatingID
The C Rating ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetStartTime

The SetStartTime method sets the value of the C Start Time field in the CChannelT record object.

void SetStartTime(
  COleDateTime& StartTime
);

Parameters

StartTime
The C Start Time value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetStationID

The SetStationID method sets the value of the C Station ID field in the CChannelT record object.

void SetStationID(
  long lStationID
);

Parameters

lStationID
The C Station ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetTunable

The SetTunable method sets the value of the C Tunable field in the CChannelT record object.

void SetTunable (
  BOOL bTunable
);

Parameters

bTunable
The C Tunable value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::SetTuningSpace

The SetTuningSpace method sets the value of the C Tuning Space field in the CChannelT record object.

void SetTuningSpace(
  long lTuningSpace
);

Parameters

lTuningSpace
The C Tuning Space value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::StartTime

The StartTime method returns the value of the C Start Time field from the CChannelT record object.

COleDateTime StartTime(void);

Parameters

None.

Return Values

The value of the C Start Time field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::StationID

The StationID method returns the value of the C Station ID field from the CChannelT record object.

long StationID(void);

Parameters

None.

Return Values

The value of the C Station ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::Tunable

The Tunable method returns the value of the C Tunable field from the CChannelT record object.

BOOL Tunable(void);

Parameters

None.

Return Values

The value of the C Tunable field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelT::TuningSpace

The TuningSpace method returns the value of the C Tuning Space field from the CChannelT record object.

long TuningSpace(void);

Parameters

None.

Return Values

The value of the C Tuning Space field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CChannelTRecordset

The CChannelTRecordset object inherits from the CDatabaseRecordset object. The CChannelTRecordset class is used to select and create CChannelT objects from the Channel table using functions defined in the CDatabaseRecordset parent class.

The CChannelTRecordset class implements the following methods:

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Channel.
GetRecordsetObject | Initializes a CChannelT object with records from the Guide database.
SetRecordsetObject | Saves the records in a CChannelT object to the Guide database.
Seek | Returns a value that indicates whether the specified record was found in the recordset.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in channelt.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseConnection

The CDatabaseConnection class provides the root encapsulation of the Jet database engine. Before you can use any of the methods below, you must first call the SetJet method.

The CDatabaseConnection class provides the following methods:

Method | Description
StartEngine | Starts the Jet database engine.
ConnectToDatabase | Opens a connection to the specified database.
DisconnectFromDatabase | Closes the connection to the specified database.
GetWorkspaceName | Retrieves the name of the workspace
GetWorkspaceUnknown | Gets a pointer to the workspace.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseConnection::ConnectToDatabase

The ConnectToDatabase method creates a workspace and opens a connection to the specified database.

BOOL ConnectToDatabase(
  const CString &csViewer,
  const CString &csPassword,
  const CString &systemFile,
  const CString &databaseFile,
  CString csWorkspaceName
);

Parameters

csViewer
A reference to an MFC CString object that contains the viewer name. Loader applications should log on as "Loader". This ensures that they have read/write permissions to the database.
csPassword
A reference to an MFC CString object that contains the password of the user specified in csViewer. This string is not changed by the method call.
systemFile
A reference to an MFC CString object that contains the full path and file name of the workgroup information file. You can obtain this value by calling the ITelevisionServices::get_SystemFile method.
databaseFile
A reference to an MFC CString object that specifies the path and name of the database file. This string is not changed by the method call.
csWorkspaceName
A reference to an MFC CString object containing the name of the open workspace. You can call the GetWorkspaceName method to get this information after ConnectToDatabase returns. The loaders can use any workspace name, but "LoaderWSP" is recommended.

Return Values

If the database was successfully opened this method returns TRUE. Otherwise it returns FALSE.

Remarks

The ConnectToDatabase method calls StartEngine automatically if the Jet database engine hasn't already been started. However, if you need to use engine functionality, such as compacting or repairs, without opening the database, you can call StartEngine explicitly.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseConnection::DisconnectFromDatabase

The DisconnectFromDatabase method closes the connection to the database. It also closes the workspace.

BOOL DisconnectFromDatabase(void);

Parameters

None.

Return Values

If the database and workspace were successfully closed this method returns TRUE. Otherwise it returns FALSE.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseConnection::GetWorkspaceName

The GetWorkspaceName method retrieves the name of the open workspace. This value is set during the call to the SetJet method.

CString GetWorkspaceName(void);

Parameters

None.

Return Values

An MFC CString object that contains the name of the workspace. Your application should not alter this string.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseConnection::GetWorkspaceUnknown

The GetWorkspaceUnknown method returns a pointer to the workspace opened during the SetJet method call.

LPUNKNOWN GetWorkspaceUnknown(void);

Parameters

None.

Return Values

This methods returns an IUnknown pointer to a workspace interface. You should cast this variable to an IDAOWorkspace pointer.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseConnection::StartEngine

The StartEngine method starts the Jet database engine.

BOOL StartEngine(
  const CString &csViewer,
  const CString &csPassword,
  const CString &systemFile
);

Parameters

csViewer
A reference to an MFC CString object that contains the viewer name. Loader applications should log on as "Loader". This ensures that they have permissions to add or delete values from the Guide database.
csPassword
A reference to an MFC CString object that contains the password of the user specified in csViewer.
systemFile
A reference to an MFC CString object that contains the full path and file name of the workgroup information file. You can obtain this value by calling the ITelevisionServices::get_SystemFile method.

Return Values

If the Jet engine was successfully started, this method returns TRUE. Otherwise it returns FALSE.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset

The CDatabaseRecordset class is an abstract base class that provides the root encapsulation for recordset manipulation. It inherits from CDatabaseConnection.

The CDatabaseRecordset class provides the following methods:

Method | Description
OpenRecordset | Initializes the recordset object.
OpenRecordsetQueryDef | Initializes the recordset object with the results of the specified query.
CloseRecordset | Clears the data from a recordset object.
GetQueryPrefix | Returns the query prefix
GetRecordCount | Counts the number of records in the recordset.
GetRecord | Returns a pointer to the specified record.
GotoRecord | Jumps to the specified record in the recordset.
FindRecord | Locates a record in the recordset.
InsertRecord | Adds a the specified record to the recordset.
UpdateRecord | Updates the current record in the recordset.
DeleteRecord | Deletes the current record from the recordset.
OpenIndexed | Opens a recordset and indexes it.
SeekAddRS | Looks for a matching record. If one is found, its field values are updated with those of the record object passed.
UpdateRS | Updates a record in the Guide database.
StartUpdateRS | Updates a record, keeping it open for further editing.
EndUpdateRS | Updates and completes editing of a record opened for editing by StartUpdateRS.
Edit | Opens a low-level DAO Edit session.
Update | Update the entire recordset from the Guide database. (This is the low-level complement of Edit)
GetLongField | Returns the value of the specified Long field of a record in the recordset.
GetField | Returns the value of the specified field of a record in the recordset. This method is overloaded. You can specify the field using either the field name or its index in the field list.
SetField | Sets the value of the specified field of a record in the recordset.
GetTableName | Returns the name of the table associated with the C TableName Recordset object. This method is re-implemented by the recordset objects that inherit from CDatabaseRecordset.

The CDatabaseRecordset class also defines the following protected methods. These methods are reimplemented by the C TableName Recordset objects that inherit from CDatabaseRecordset.

Protected method | Description
SetRecordsetObject | Sets the values of a record object to the Guide database.
GetRecordsetObject | Returns a record object.
Seek | Returns a value that indicates whether the specified object is in the recordset.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::CloseRecordset

The CloseRecordset method clears the data from a recordset object.

void CloseRecordset(void);

Parameters

None.

Return Values

This method does not return a value.

Remarks

You can reuse recordset objects by opening and closing a single recordset object multiple times. This is more efficient than deleting and creating a new instance of a recordset object.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::DeleteRecord

The DeleteRecord method deletes the current record from the recordset.

BOOL DeleteRecord(void);

Parameters

None.

Return Values

A BOOL indicating the success or failure of the method. If this value is TRUE, the method succeeded. If it is FALSE, an error occurred.

Remarks

Only the current record of an open recordset can be deleted.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::Edit

The Edit method provides low-level functionality that calls directly into the DAO Recordset to start an Edit session. Most applications will not use this method. It is intended for use by ISVs that write their own Guide data object classes to wrap tables they have added to the Guide database.

void Edit(void);

Parameters

None.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::EndUpdateRS

The EndUpdateRS method updates a record that was opened for editing by the StartUpdateRS method.

void EndUpdateRS(void);

Parameters

None.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::FindRecord

The FindRecord method searches the recordset for a record that matches the specified type and search criteria.

long FindRecord(
  long FindType,
  LPCTSTR Criteria
);

Parameters

FindType
A flag that specifies the type of record to find. It can be any one of the following values.
Value | Meaning
dbFindFirst | Find the first record that matches the criteria.
dbFindLast | Find the last record that matches the criteria.
dbFindNext | Find the next record that matches the criteria.
dbFindPrevious | Find the previous record that matches the criteria.

Criteria
A string that can be evaluated as a logical expression within the context of the recordset. For example, "Channel Number = 27".

Return Values

A long that specifies the 0-based index of the found record. If a match is not found, this method moves the record pointer to the first record, and returns -1.

Remarks

Opening a recordset using the OpenIndexed method and then using the Seek method to find records provides better performance than using the FindRecord method.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::GetField

The GetField method returns the value of the specified field from a record in the recordset object. This method is overloaded and you can use either a LPCTSTR or a long to index the index.

Syntax1

COleVariant GetField(
  LPCTSTR pstrIndex
);

Parameters1

pstrIndex
Specifies the name of the field to retrieve.

Syntax2

COleVariant GetField(
  long lIndex
);

Parameters2

lIndex
The index number of the field to retrieve. For example, if you passed in 3, this method gets the value of the third field.

Return Values

The value of the field specified by the index parameter.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::GetLongField

The GetLongField method returns the value of the specified long field from a record in the recordset object.

long GetLongField(
  LPCTSTR pstrIndex
);

Parameters

pstrIndex
Specifies the name of the field to retrieve.

Return Values

The value of the field specified by pstrIndex. If you call this method to retrieve a field that has a data type other than long, for example a text field, this method returns 0.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::GetQueryPrefix

The GetQueryPrefix method returns the query prefix.

CString GetQueryPrefix(void);

Parameters

None.

Return Values

A string of the form "SELECT * FROM <TableName". Where TableName is the name of the table associated the recordset object. For example if you call CEpisodeTRecordset::GetQueryPrefix, the string returned is "SELECT * FROM <Episode".

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::GetRecord

The GetRecord method returns a record object. This object contains information corresponding to a single record in the Guide database.

void* GetRecord(
  long RecordNumber
);

Parameters

RecordNumber
The 0-based index of the record to retrieve from the recordset. This cannot be greater than the value returned by GetRecordCount - 1.

Return Values

A void pointer that receives the record object. Your application must cast the void pointer to the appropriate object type before it can access the record. For example, if your application calls the GetRecord method of an CEpisodeTRecordset object, an episode record object is returned. Thus the void pointer would need to be cast to an CEpisodeT pointer.

Your application can then use the methods of the record object to retrieve and set field values.

When the record object is no longer needed, your application should destroy it.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::GetRecordCount

The GetRecordCount method counts the number of records in the recordset.

long GetRecordCount(void);

Parameters

None.

Return Values

The total number of records.

Remarks

Calling the GetRecordCount method causes the recordset object to move to the last record, which may be slow for large record sets.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::GetRecordsetObject

The GetRecordsetObject method initializes the recordset object with values from its corresponding table in the Guide database.

The table-specific version of this method is implemented by the C TableName Recordset objects that inherit from CDatabaseRecordset.

void* GetRecordsetObject(void)

Parameters

None.

Return Values

This method returns a void pointer to the record at the current record pointer. This should be cast to its corresponding object type.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::GetTableName

The GetTableName method returns the name of the table associated with the current recordset.

CString GetTableName(void);

Parameters

None.

Return Values

A string that contains the name of the table in the Guide database that is associated with the current recordset object.

Remarks

GetTableName is implemented by the C TableName Recordset objects that inherit from CDatabaseRecordset. For example, CEpisodeTRecordset implements this method to return "Episode".

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::GotoRecord

The GotoRecord method jumps to the specified record in a recordset.

BOOL GotoRecord(
  long RecordNumber
);

Parameters

RecordNumber
A long that specifies the 0-based index of the record to jump to. This value cannot be greater than GetRecordCount - 1.

Return Values

A BOOL indicating the success or failure of the method. If this value is TRUE, the method succeeded. If it is FALSE, an error occurred.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::InsertRecord

The InsertRecord method adds a record to the specified recordset.

BOOL InsertRecord(
  void* cRecordsetObject
);

Parameters

cRecordsetObject
A pointer to a recordset object.

Return Values

A BOOL indicating the success or failure of the method. If this value is TRUE, the method succeeded. If it is FALSE, an error occurred.

Remarks

If the InsertRecord method is called on a dynaset-type recordset, the record is added at the end of the recordset. For a table-type recordset, for which an index has been specified, the record is added in their proper place in the sort order. If the recordset is a table-type and no index is specified, new records are added to the end of the recordset.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::OpenIndexed

The OpenIndexed method opens a recordset and indexes it.

void OpenIndexed(
  int iKeyID,
  int nOpenType,
  LPCTSTR lpszSQL,
  int nOptions
);

Parameters

iKeyID
Specifies a string resource identifier that contains the name of the index to open. Most tables have either a "Primary Key" or a "TSSLoadBy" recordset in Tss.mdb.
nOpenType
Specifies whether to open the recordset as a dynaset or a snapshot.

This parameter can be one of the following values.
Value | Meaning
dbOpenSnapshot | Open the recordset as a snapshot, in other words, create a fixed copy of the records in the table.
dbOpenDynaset | Open the recordset as a dynaset, a set of pointers to the records in a table. This is the default.

lpszSQL
Specifies the name of the table to open. You can also use this parameter to pass in any SQL statement that can be opened.
nOptions
Specifies options to pass into the OpenRecordset call. To locate more information about OpenRecordset, see Further Information on Program Guide Services for the Client.

Return Values

This method does not return a value.

Remarks

This method is functionally equivalent to calling the OpenRecordset method and then calling SetIndex, where the SetIndex method is the DAO wrapper for the Index Automation property for the DAO Recordset.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::OpenRecordset

The OpenRecordset method opens the specified recordset in the Guide database.

BOOL OpenRecordset(
  LPCTSTR WhereBy,
  long lType
);

Parameters

WhereBy
A SQL WHERE clause that specifies the recordset criteria. Only records that match this parameter will be opened.
lType
An optional parameter that specifies whether the Jet database engine opens the recordset as a snapshot or a dynaset.

This parameter can be one of the following values.
Value | Meaning
dbOpenSnapshot | Open the recordset as a snapshot, in other words, create a fixed copy of the records in the table.
dbOpenDynaset | Open the recordset as a dynaset, a set of pointers to the records in a table. This is the default.

Return Values

If the recordset was successfully opened, this method returns TRUE. Otherwise it returns FALSE.

Remarks

You can reuse recordset objects by opening and closing a single recordset object multiple times. This is more efficient than deleting and creating a new instance of a recordset object.

The record count is not automatically defined when you open a recordset. Therefore, when you call GetRecordCount, the method must move to the last record in the set. This can be slow for large recordsets. However, recordsets opened with an ORDER BY clause correctly set the initial record count.

In the case of large recordsets, opening the recordset as a snapshot can degrade performance.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::OpenRecordsetQueryDef

The OpenRecordsetQueryDef method creates a recordset containing the results of the specified query.

BOOL OpenRecordsetQueryDef(
  LPCTSTR QueryName,
  long lType
);

Parameters

QueryName
Specifies the name of the query. For a list of queries defined in the Guide database, see Guide Database Query Reference.
lType
An optional parameter that specifies whether the Jet database engine opens the recordset as a snapshot or a dynaset.

This parameter can be one of the following values.
Value | Meaning
dbOpenSnapshot | Open the recordset as a snapshot, in other words, create a fixed copy of the records in the table.
dbOpenDynaset | Open the recordset as a dynaset, a set of pointers to the records in a table. This is the default.
dbOpenTable | Open the entire table. In this case, the QueryName parameter simply specifies the table name.

Return Values

If the recordset was successfully opened, this method returns TRUE. Otherwise it returns FALSE.

Remarks

You can reuse recordset objects by opening and closing a single recordset object multiple times. This is more efficient than deleting and creating a new instance of a recordset object.

The record count is not automatically defined when you open a recordset. Therefore, when you call GetRecordCount, the method must move to the last record in the set. This can be slow for large recordsets. However, recordsets opened with an ORDER BY clause correctly set the initial record count.

In the case of large recordsets, opening the recordset as a snapshot can degrade performance.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::Seek

The Seek method returns a value that indicates whether the specified record object was found in the recordset.

BOOLEAN Seek(
  LPCTSTR lpszComparison,
  CObject &coo
);

Parameters

lpszComparison
A string that indicates the type of comparison operation to perform, for example "=" or "<".
coo
In the protected CDatabaseRecordset implementation of this method, this parameter is a reference to a record object.

In the public CChannelTRecordset implementation of this method this parameter is a long that specifies the channel identifier to search for.

In the public CEpisodeTRecordset implementation of this method this parameter is a long that specifies the episode identifier to search for.

Return Values

If the object was found in the recordset, this method returns TRUE. Otherwise it returns FALSE.

Remarks

Note that the Seek method only seeks on fields in the currently opened index.

For example, if you passed a CStation object to the CStationRecordset::Seek method, it will search for the first record with matching call letters, and ignore other fields such as the station name.

The table-specific version of this method is implemented by the C TableName Recordset objects that inherit from CDatabaseRecordset. However, the Seek method is implemented as a protected function by all recordset objects except CChannelTRecordset and CEpisodeTRecordset.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::SeekAddRS

The SeekAddRS method checks the current recordset for a record object whose index field value is identical to that of the specified object. If it finds a match, it moves the recordset pointer to the matching object. If it does not find a match, it adds the record you passed in to the recordset.

For example, if you called the CStationRecordset::SeekAddRS method and passed in a CStation object, the method would compare the call letters in the object you passed in against the call letters of records in the recordset.

HRESULT SeekAddRS(
  CObject &coo
);

Parameters

coo
A reference to a C TableName record object.

Return Values

Returns one of the following HRESULTS .

Value | Meaning
E_FAIL | The record does not exist and cannot be added.
S_FALSE | The record already exists, and SeekAddRS set the recordset pointer to the existing record.
S_OK | The record was added successfully.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::SetField

The SetField method sets the value of the specified field of a record in the recordset object.

void SetField(
  LPCTSTR pstrIndex,
  COleVariant cov
);

Parameters

pstrIndex
The name of the field to set.
cov
The field value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::SetRecordsetObject

The SetRecordsetObject method persists the values of the record object to its corresponding table in the Guide database.

The table-specific version of this method is implemented by the C TableName Recordset objects that inherit from CDatabaseRecordset.

BOOL SetRecordsetObject(
  void* cRecordsetObject
);

Parameters

cRecordsetObject
A pointer to a C TableName record object.

Return Values

A BOOL indicating the success or failure of the method. If this value is TRUE, the method succeeded. If it is FALSE, an error occurred.

Remarks

This method updates the record at the current record pointer.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::StartUpdateRS

The StartUpdateRS method enables you to partially update a record in the database. The record will remain open for editing until you call the EndUpdateRS method.

void StartUpdateRS(
  CObject &coo
);

Parameters

coo
A reference to a C TableName record object.

Return Values

This method does not return a value.

Remarks

This method is useful when you need to update a record but do not have all the values required to call UpdateRS.

For example, if you need to add a record to a CStationRecordset, but don't yet have the station's name value, only its call letters, you could pass a CStation with only the call letters specified to StartUpdateRS. Then when you acquire the station's name, you can add it to the record by calling the SetField method. When you are finished editing the record, you should call EndUpdateRS.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::Update

The Update method calls directly into the underlying DAO Recordset to complete an Edit session. Most applications will not use this method. It is intended for use by ISVs that write their own Guide data object classes to wrap tables they have added to the Guide database.

void Update(void);

Parameters

None.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CDatabaseRecordset::UpdateRecord

The UpdateRecord method updates the current record in the recordset object from the Guide database. Only the current record of an open recordset can be updated.

BOOL UpdateRecord(
  void* cRecordsetObject
);

Parameters

cRecordsetObject
A pointer to a recordset object.

Return Values

A BOOL indicating the success or failure of the method. If this value is TRUE, the method succeeded. If it is FALSE, an error occurred.

Remarks

This method is automatically called by the InsertRecord method when it adds a new empty record to the recordset. You can also use this method to replace the current record with a passed-in C TableName.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

Example

The following example updates the current record of the CThemeRecordset recordset.

Ctheme *pct = new (Ctheme);
CthemeRecordset ctr;
Ctr->UpdateRecord((void *) pct));


CDatabaseRecordset::UpdateRS

The UpdateRS method searches the recordset for a record whose index field value is identical to that of the specified object. If a match is found, this method copies the field values of the specified object to the matching object in the recordset.

For example, if you called the CStationRecordset::UpdateRS method and passed in a CStation object. It would search on the index field, the S Call Letters field, to find a match. If the object you passed in had the call letters "KZZZ," and a record in the table had the call letters "KZZZ," the remaining field values of the table object would be overwritten with the field values of the object you passed in.

void UpdateRS(
  CObject &coo
);

Parameters

coo
A reference to a C TableName record object.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in dbsets.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancement

Each CEnhancement object corresponds to a single record of the Enhancement table in the Guide database. You can use the methods of CEnhancement to retrieve and set field values. These objects are created and initialized by CEnhancementRecordset objects.

The CEnhancement class provides the following methods:

Method | Description
SetEnhancementID | Sets the value of the EN Enhancement ID field.
SetTitle | Sets the value of the EN Title field.
SetShowReference | Sets the value of the EN Show Reference field.
SetPreloadURL | Sets the value of the EN Preload URL field.
SetAddress | Sets the value of the EN Address field.
SetExpireDate | Sets the value of the EN Expire Date field.
EnhancementID | Retrieves the value of the EN Enhancement ID field.
Title | Retrieves the value of the EN Title field.
ShowReference | Retrieves the value of the EN Show Reference field.
PreloadURL | Retrieves the value of the EN Preload URL field.
Address | Retrieves the value of the EN Address field.
ExpireDate | Retrieves the value of the EN Expire Date field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancement::Address

The Address method returns the value of the EN Address field from the CEnhancement record object.

CString Address(void);

Parameters

None.

Return Values

The value of the EN Address field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancement::EnhancementID

The EnhancementID method returns the value of the EN Enhancement ID field from the CEnhancement record object.

CString EnhancementID(void);

Parameters

None.

Return Values

The value of the EN Enhancement ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

EN Enhancement ID


CEnhancement::ExpireDate

The ExpireDate method returns the value of the EN Expire Date field from the CEnhancement record object.

COleDateTime ExpireDate(void);

Parameters

None.

Return Values

The value of the EN Expire Date field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancement::PreloadURL

The PreloadURL method returns the value of the EN Preload URL field from the CEnhancement record object.

CString PreloadURL(void);

Parameters

None.

Return Values

The value of the EN Preload URL field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancement::SetAddress

The SetAddress method sets the value of the EN Address field in the CEnhancement record object.

void SetAddress(
  LPCTSTR cszAddress
);

Parameters

cszAddress
The EN Address value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancement::SetEnhancementID

The SetEnhancementID method sets the value of the EN Enhancement ID field in the CEnhancement record object.

void SetEnhancementID(
  LPCTSTR cszEnhancementID
);

Parameters

cszEnhancementID
The EN Enhancement ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancement::SetExpireDate

The SetExpireDate method sets the value of the EN Expire Date field in the CEnhancement record object.

void SetExpireDate(
  COleDateTime ExpireDate
);

Parameters

ExpireDate
The EN Expire Date value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancement::SetPreloadURL

The SetPreloadURL method sets the value of the EN Preload URL field in the CEnhancement record object.

void SetPreloadURL(
  LPCTSTR cszPreloadURL
);

Parameters

cszPreloadURL
The EN Preload URL value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancement::SetShowReference

The SetShowReference method sets the value of the EN Show Reference field in the CEnhancement record object.

void SetShowReference(
  LPCTSTR cszShowReference
);

Parameters

cszShowReference
The EN Show Reference value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancement::SetTitle

The SetTitle method sets the value of the EN Title field in the CEnhancement record object.

void SetTitle(
  LPCTSTR cszTitle
);

Parameters

cszTitle
The EN Title value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancement::ShowReference

The ShowReference method returns the value of the EN Show Reference field from the CEnhancement record object.

CString ShowReference(void);

Parameters

None.

Return Values

The value of the EN Show Reference field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancement::Title

The Title method returns the value of the EN Title field from the CEnhancement record object.

CString Title(void);

Parameters

None.

Return Values

The value of the EN Title field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEnhancementRecordset

The CEnhancementRecordset class is used to select and create CEnhancement objects from the Enhancement table via functions in the CDatabaseRecordset parent class. This class provides Enhancement recordset manipulation via parent functions

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Enhancement.
GetRecordsetObject | Initializes a CEnhancement object with records from the Guide database.
SetRecordsetObject | Saves the records in a CEnhancement object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in enhance.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeProperty

Each CEpisodeProperty object corresponds to a single record of the Episode Property table in the Guide database. You can use the methods of CEpisodeProperty to retrieve and set field values. These objects are created and initialized by CEpisodePropertyRecordset objects.

The CEpisodeProperty class provides the following methods:

Method | Description
SetEpisodeID | Sets the value of the Episode ID field.
SetBroadcastPropertyID | Sets the value of the Broadcast Property ID field.
EpisodeID | Retrieves the value of the Episode ID field.
BroadcastPropertyID | Retrieves the value of the Broadcast Property ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in epprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeProperty::BroadcastPropertyID

The BroadcastPropertyID method returns the value of the Broadcast Property ID field from the CEpisodeProperty record object.

long BroadcastPropertyID(void);

Parameters

None.

Return Values

The value of the EP Broadcast Property ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in epprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

Broadcast Property ID


CEpisodeProperty::EpisodeID

The EpisodeID method returns the value of the Episode ID field from the CEpisodeProperty record object.

long EpisodeID(void);

Parameters

None.

Return Values

The value of the EP Episode ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in epprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

Episode ID


CEpisodeProperty::SetBroadcastPropertyID

The SetBroadcastPropertyID method sets the value of the Broadcast Property ID field in the CEpisodeProperty record object.

void SetBroadcastPropertyID(
  long lBroadcastPropertyID
);

Parameters

lBroadcastPropertyID
The EP Broadcast Property ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in epprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

Broadcast Property ID


CEpisodeProperty::SetEpisodeID

The SetEpisodeID method sets the value of the Episode ID field in the CEpisodeProperty record object.

void SetEpisodeID(
  long lEpisodeID
);

Parameters

lEpisodeID
The EP Episode ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in epprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

Episode ID


CEpisodePropertyRecordset

The CEpisodePropertyRecordset class is used to select and create CEpisodeProperty objects from the EpisodeProperty table via functions in the CDatabaseRecordset parent class.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Episode Property.
GetRecordsetObject | Initializes a CEpisodeProperty object with records from the Guide database.
SetRecordsetObject | Saves the records in a CEpisodeProperty object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in epprop.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT

Each CEpisodeT object corresponds to a single record of the Episode table in the Guide database. You can use the methods of CEpisodeT to retrieve and set field values. These objects are created and initialized by CEpisodeTRecordset objects.

The CEpisodeT class provides the following methods:

Method | Description
SetTitle | Sets the value of the E Title field.
SetDescription | Sets the value of the E Description field.
SetDisplayMask | Sets the value of the E Display Mask field.
SetThemeID | Sets the value of the E Theme ID field.
SetRatingID | Sets the value of the E Rating ID field.
SetAbbreviation | Sets the value of the E Abbreviation field.
SetLastUpdate | Sets the value of the E Last Update field.
EpisodeID | Retrieves the value of the E Episode ID field. This field is automatically generated and cannot be set.
Title | Retrieves the value of the E Title field.
Description | Retrieves the value of the E Description field.
DisplayMask | Retrieves the value of the E Display Mask field.
ThemeID | Retrieves the value of the E Theme ID field.
RatingID | Retrieves the value of the E Rating ID field.
Abbreviation | Retrieves the value of the E Abbreviation field.
LastUpdate | Retrieves the value of the E Last Update field.
SetEnhMapID | Sets the value of the E Enhancement Mapping ID field.
EnhMapID | Retrieves the value of the E Enhancement Mapping ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::Abbreviation

The Abbreviation method returns the value of the E Abbreviation field from the CEpisodeT record object.

long Abbreviation(void);

Parameters

None.

Return Values

The value of the E Abbreviation field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::Description

The Description method returns the value of the E Description field from the CEpisodeT record object.

CString Description(void);

Parameters

None.

Return Values

The value of the E Description field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::DisplayMask

The DisplayMask method returns the value of the E Display Mask field from the CEpisodeT record object.

long DisplayMask(void);

Parameters

None.

Return Values

The value of the E Display Mask field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::EnhMapID

The EnhMapID method returns the value of the E Enhancement Mapping ID field from the CEpisodeT record object.

CString EnhMapID(void);

Parameters

None.

Return Values

Returns the value of the E Enhancement Mapping ID field if successful.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

E Enhancement Mapping ID


CEpisodeT::EpisodeID

The EpisodeID method returns the value of the E Episode ID field from the CEpisodeT record object.

long EpisodeID(void);

Parameters

None.

Return Values

The value of the E Episode ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::LastUpdate

The LastUpdate method returns the value of the E Last Update field from the CEpisodeT record object.

COleDateTime LastUpdate(void);

Parameters

None.

Return Values

The value of the E Last Update field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::RatingID

The RatingID method returns the value of the E Rating ID field from the CEpisodeT record object.

long RatingID(void);

Parameters

None.

Return Values

The value of the E Rating ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::SetAbbreviation

The SetAbbreviation method sets the value of the E Abbreviation field in the CEpisodeT record object.

void SetAbbreviation(
  long lAbbreviation
);

Parameters

lAbbreviation
The E Abbreviation value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::SetDescription

The SetDescription method sets the value of the E Description field in the CEpisodeT record object.

void SetDescription(
  LPCTSTR cszDescription
);

Parameters

cszDescription
The E Description value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::SetDisplayMask

The SetDisplayMask method sets the value of the E Display Mask field in the CEpisodeT record object.

void SetDisplayMask(
  long lDisplayMask
);

Parameters

lDisplayMask
The E Display Mask value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::SetEnhMapID

The SetEnhMapID method sets the value of the E Enhancement Mapping ID field in the CEpisodeT record object.

void SetEnhMapID(
  LPCTSTR szEnhMapID
);

Parameters

szEnhMapID
E Enhancement Mapping ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

E Enhancement Mapping ID


CEpisodeT::SetLastUpdate

The SetLastUpdate method sets the value of the E Last Update field in the CEpisodeT record object.

void SetLastUpdate(
  COleDateTime codtLastUpdate
);

Parameters

codtLastUpdate
The E Last Update value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::SetRatingID

The SetRatingID method sets the value of the E Rating ID field in the CEpisodeT record object.

void SetRatingID(
  long lRatingID
);

Parameters

lRatingID
The E Rating ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::SetThemeID

The SetThemeID method sets the value of the E Theme ID field in the CEpisodeT record object.

void SetThemeID(
  long lThemeID
);

Parameters

lThemeID
The E Theme ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::SetTitle

The SetTitle method sets the value of the E Title field in the CEpisodeT record object.

void SetTitle(
  LPCTSTR cszTitle
);

Parameters

cszTitle
The E Title value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::ThemeID

The ThemeID method returns the value of the E Theme ID field from the CEpisodeT record object.

long ThemeID(void);

Parameters

None.

Return Values

The value of the E Theme ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeT::Title

The Title method returns the value of the E Title field from the CEpisodeT record object.

CString Title(void);

Parameters

None.

Return Values

The value of the E Title field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CEpisodeTRecordset

The CEpisodeTRecordset class is used to select and create CEpisodeT objects from the EpisodeT table using functions defined in the CDatabaseRecordset parent class.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Episode.
GetRecordsetObject | Initializes a CEpisodeT object with records from the Guide database.
SetRecordsetObject | Saves the records in a CEpisodeT object to the Guide database.
Seek | Returns a value that indicates whether the specified record is in the recordset.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in episodet.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CGenre

Each CGenre object corresponds to a single record of the Genre table in the Guide database. You can use the methods of CGenre to retrieve and set field values. These objects are created and initialized by CGenreRecordset objects.

The CGenre class provides the following methods:

Method | Description
SetTuningSpace | Sets the value of the G Tuning Space field.
SetName | Sets the value of the G Name field.
GenreID | Retrieves the value of the G Genre ID field. This field is automatically generated and cannot be set.
TuningSpace | Retrieves the value of the G Tuning Space field.
Name | Retrieves the value of the G Name field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in genre.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

CGenreRecordset, Genre table


CGenre::GenreID

The GenreID method returns the value of the G Genre ID field from the CGenre record object.

long GenreID(void);

Parameters

None.

Return Values

The value of the G Genre ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in genre.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

G Genre ID


CGenre::Name

The Name method returns the value of the G Name field from the CGenre record object.

CString Name(void);

Parameters

None.

Return Values

The value of the G Name field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in genre.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

G Name


CGenre::SetName

The SetName method sets the value of the G Name field in the CGenre record object.

void SetName(
  LPCTSTR cszName
);

Parameters

cszName
G Name value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in genre.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

G Name


CGenre::SetTuningSpace

The SetTuningSpace method sets the value of the G Tuning Space field in the CGenre record object.

void SetTuningSpace(
  long lTuningSpace
);

Parameters

lTuningSpace
G Tuning Space value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in genre.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

G Tuning Space


CGenre::TuningSpace

The TuningSpace method returns the value of the G Tuning Space field from the CGenre record object.

long TuningSpace(void);

Parameters

None.

Return Values

The value of the G Tuning Space field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in genre.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

G Tuning Space


CGenreRecordset

The CGenreRecordset class is used to select and create CGenre objects from the Genre table via functions in the CDatabaseRecordset parent class.

The CGenreRecordset class re-implements the following methods defined in CDatabaseRecordset.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Genre.
GetRecordsetObject | Initializes a CGenre object with records from the Guide database.
SetRecordsetObject | Saves the records in a CGenre object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in genre.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

CDatabaseRecordset, CGenre, Genre table


CNetwork

Each CNetwork object corresponds to a single record of the Network table in the Guide database. You can use the methods of CNetwork to retrieve and set field values. These objects are created and initialized by CNetworkRecordset objects.

The CNetwork class provides the following methods:

Method | Description
SetName | Sets the value of the N Name field.
SetLogoMoniker | Sets the value of the N LogoMoniker field.
NetworkID | Retrieves the value of the N Network ID field. This field is automatically generated and cannot be set.
Name | Retrieves the value of the N Name field.
LogoMoniker | Retrieves the value of the N LogoMoniker field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in network.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CNetwork::LogoMoniker

The LogoMoniker method returns the value of the N LogoMoniker field from the CNetwork record object.

CString LogoMoniker(void);

Parameters

None.

Return Values

The value of the N LogoMoniker field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in network.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CNetwork::Name

The Name method returns the value of the N Name field from the CNetwork record object.

CString Name(void);

Parameters

None.

Return Values

The value of the N Name field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in network.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CNetwork::NetworkID

The NetworkID method returns the value of the N Network ID field from the CNetwork record object.

long NetworkID(void);

Parameters

None.

Return Values

The value of the N Network ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in network.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CNetwork::SetLogoMoniker

The SetLogoMoniker method sets the value of the N LogoMoniker field in the CNetwork record object.

void SetLogoMoniker(
  LPCTSTR szLogoMoniker
);

Parameters

szLogoMoniker
The N LogoMoniker value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in network.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CNetwork::SetName

The SetName method sets the value of the N Name field in the CNetwork record object.

void SetName(
  LPCTSTR szName
);

Parameters

szName
The N Name value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in network.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CNetworkRecordset

The CNetworkRecordset class is used to select and create CNetwork objects from the Network table via functions in the CDatabaseRecordset parent class.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Network.
GetRecordsetObject | Initializes a CNetwork object with records from the Guide database.
SetRecordsetObject | Saves the records in a CNetwork object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in network.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRating

Each CRating object corresponds to a single record of the Rating table in the Guide database. You can use the methods of CRating to retrieve and set field values. These objects are created and initialized by CRatingRecordset objects.

The CRating class provides the following methods:

Method | Description
SetRatingSystemID | Sets the value of the R Rating System ID field.
SetRating | Sets the value of the R Rating field.
SetDescription | Sets the value of the R Description field.
SetPictogramMoniker | Sets the value of the R Pictogram Moniker field.
RatingID | Retrieves the value of the R Rating ID field. This field is automatically generated and cannot be set.
RatingSystemID | Retrieves the value of the R Rating System ID field.
Rating | Retrieves the value of the R Rating field.
Description | Retrieves the value of the R Description field.
PictogramMoniker | Retrieves the value of the R Pictogram Moniker field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in rating.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRating::Description

The Description method returns the value of the R Description field from the CRating record object.

CString Description(void);

Parameters

None.

Return Values

The value of the R Description field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in rating.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRating::PictogramMoniker

The PictogramMoniker method returns the value of the R Pictogram Moniker field from the CRating record object.

CString PictogramMoniker(void);

Parameters

None.

Return Values

The value of the R PictogramMoniker field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in rating.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRating::Rating

The Rating method returns the value of the R Rating field from the CRating record object.

FLOAT Rating(void);

Parameters

None.

Return Values

The value of the R Rating field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in rating.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRating::RatingID

The RatingID method returns the value of the R Rating ID field from the CRating record object.

long RatingID(void);

Parameters

None.

Return Values

The value of the R Rating ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in rating.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRating::RatingSystemID

The RatingSystemID method returns the value of the R Rating System ID field from the CRating record object.

long RatingSystemID(void);

Parameters

None.

Return Values

The value of the R Rating System ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in rating.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRating::SetDescription

The SetDescription method sets the value of the R Description field in the CRating record object.

void SetDescription(
  LPCTSTR cszDescription
);

Parameters

cszDescription
The R Description value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in rating.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRating::SetPictogramMoniker

The SetPictogramMoniker method sets the value of the R Pictogram Moniker field in the CRating record object.

void SetPictogramMoniker(
  LPCTSTR cszPictogramMoniker
);

Parameters

cszPictogramMoniker
The R PictogramMoniker value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in rating.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRating::SetRating

The SetRating method sets the value of the R Rating field in the CRating record object.

void SetRating(
  FLOAT flRating
);

Parameters

flRating
The R Rating value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in rating.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRating::SetRatingSystemID

The SetRatingSystemID method sets the value of the R Rating System ID field in the CRating record object.

void SetRatingSystemID(
  long lRatingSystemID
);

Parameters

lRatingSystemID
The R Rating System ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in rating.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRatingRecordset

The CRatingRecordset class is used to select and create CRating objects from the Rating table via functions in the CDatabaseRecordset parent class.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Rating.
GetRecordsetObject | Initializes a CRating object with records from the Guide database.
SetRecordsetObject | Saves the records in a CRating object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in rating.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRatingSystem

Each CRatingSystem object corresponds to a single record of the Rating System table in the Guide database. You can use the methods of CRatingSystem to retrieve and set field values. These objects are created and initialized by CRatingSystemRecordset objects.

The CRatingSystem class provides the following methods:

Method | Description
SetTuningSpace | Sets the value of the RS Tuning Space field.
SetName | Sets the value of the RS Name field.
SetDescription | Sets the value of the RS Description field.
RatingSystemID | Retrieves the value of the RS Rating System ID field.
TuningSpace | Retrieves the value of the RS Tuning Space field.
Name | Retrieves the value of the RS Name field.
Description | Retrieves the value of the RS Description field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ratingsy.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRatingSystem::Description

The Description method returns the value of the RS Description field from the CRatingSystem record object.

CString Description(void);

Parameters

None.

Return Values

The value of the RS Description field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ratingsy.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRatingSystem::Name

The Name method returns the value of the RS Name field from the CRatingSystem record object.

CString Name(void);

Parameters

None.

Return Values

The value of the RS Name field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ratingsy.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRatingSystem::RatingSystemID

The RatingSystemID method returns the value of the RS Rating System ID field from the CRatingSystem record object.

long RatingSystemID(void);

Parameters

None.

Return Values

The value of the RS Rating System ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ratingsy.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRatingSystem::SetDescription

The SetDescription method sets the value of the RS Description field in the CRatingSystem record object.

void SetDescription(
  LPCTSTR cszDescription
);

Parameters

cszDescription
The RS Description value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ratingsy.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRatingSystem::SetName

The SetName method sets the value of the RS Name field in the CRatingSystem record object.

void SetName(
  LPCTSTR cszName
);

Parameters

cszName
The RS Name value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ratingsy.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRatingSystem::SetTuningSpace

The SetTuningSpace method sets the value of the RS Tuning Space field in the CRatingSystem record object.

void SetTuningSpace(
  long lTuningSpace
);

Parameters

lTuningSpace
The RS Tuning Space value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ratingsy.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRatingSystem::TuningSpace

The TuningSpace method returns the value of the RS Tuning Space field from the CRatingSystem record object.

long TuningSpace(void);

Parameters

None.

Return Values

The value of the RS Tuning Space field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ratingsy.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CRatingSystemRecordset

The CRatingSystemRecordset class is used to select and create CRatingSystem objects from the RatingSystem table via functions in the CDatabaseRecordset parent class.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Rating System.
GetRecordsetObject | Initializes a CRatingSystem object with records from the Guide database.
SetRecordsetObject | Saves the records in a CRatingSystem object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ratingsy.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStation

Each CStation object corresponds to a single record of the Station table in the Guide database. You can use the methods of CStation to retrieve and set field values. These objects are created and initialized by CStationRecordset objects.

The CStation class provides the following methods:

Method | Description
SetCallLetters | Sets the value of the S Call Letters field.
SetName | Sets the value of the S Name field.
SetNetworkID | Sets the value of the S Network ID field.
SetLogo | Sets the value of the S Logo field.
SetDescription | Sets the value of the S Description field.
StationID | Retrieves the value of the S Station ID field. This field is automatically generated and cannot be set.
CallLetters | Retrieves the value of the S Call Letters field.
Name | Retrieves the value of the S Name field.
NetworkID | Retrieves the value of the S Network ID field.
Logo | Retrieves the value of the S Logo field.
Description | Retrieves the value of the S Description field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStation::CallLetters

The CallLetters method returns the value of the S Call Letters field from the CStation record object.

CString CallLetters(void);

Parameters

None.

Return Values

The value of the S Call Letters field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStation::Description

The Description method returns the value of the S Description field from the CStation record object.

CString Description(void);

Parameters

None.

Return Values

The value of the S Description field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStation::Logo

The Logo method returns the value of the S Logo field from the CStation record object.

CString Logo(void);

Parameters

None.

Return Values

The value of the S Logo field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStation::Name

The Name method returns the value of the S Name field from the CStation record object.

CString Name(void);

Parameters

None.

Return Values

The value of the S Name field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStation::NetworkID

The NetworkID method returns the value of the S Network ID field from the CStation record object.

long NetworkID(void);

Parameters

None.

Return Values

The value of the S Network ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStation::SetCallLetters

The SetCallLetters method sets the value of the S Call Letters field in the CStation record object.

void SetCallLetters(
  LPCTSTR szCallLetters
);

Parameters

szCallLetters
The S Call Letters value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStation::SetDescription

The SetDescription method sets the value of the S Description field in the CStation record object.

void SetDescription(
  LPCTSTR szDescription
);

Parameters

szDescription
The string to save in the S Description field of a station record.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStation::SetLogo

The SetLogo method sets the value of the S Logo field in the CStation record object.

void SetLogo(
  LPCTSTR szLogo
);

Parameters

szLogo
A string giving the name of the .BMP file that contains the logo image.

Return Values

This method does not return a value.

Remarks

The Program Guide gets logos from .BMP files that are stored in the TV Viewer\Bitmaps directory. Each logo has two formats, the first is a small logo that appears next to the station call letters in the Program Guide. The second format is a larger logo that appears in the upper right corner of the Program Guide when the user selects the station.

Both of the logo files must use an 8 bit color depth and the Windows system palette. Failure to use these settings will cause the Program guide to use the wrong colors when displaying the logo. Some bitmap editors may require you to copy the palette from one of the bitmaps in TV Viewer\Bitmap to properly set the palette.

The small logo is 48 pixels wide and 36 pixels high. The background should bre black and the forground should be light green (for bitmap editors that allow you to enter RGB values use red = 102, green = 204, and blue = 153) to match the color scheme that the Program guide uses.

The large logo is 184 pixels wide and 138 pixels high. It can use any if the colors in the Windows system palette.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStation::SetName

The SetName method sets the value of the S Name field in the CStation record object.

void SetName(
  LPCTSTR szName
);

Parameters

szName
The S Name value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStation::SetNetworkID

The SetNetworkID method sets the value of the S Network ID field in the CStation record object.

void SetNetworkID(
  long lNetworkID
);

Parameters

lNetworkID
The S Network ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStation::StationID

The StationID method returns the value of the S Station ID field from the CStation record object.

long StationID(void);

Parameters

None.

Return Values

The value of the S Station ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStationRecordset

The CStationRecordset class is used to select and create CStation objects from the Station table via functions in the CDatabaseRecordset parent class.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Station.
GetRecordsetObject | Initializes a CStation object with records from the Guide database.
SetRecordsetObject | Saves the records in a CStation object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in station.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStreamType

Each CStreamType object corresponds to a single record of the Stream Type table in the Guide database. You can use the methods of CStreamType to retrieve and set field values. These objects are created and initialized by CStreamTypeRecordset objects.

The CStreamType class provides the following methods:

Method | Description
SetTuningSpace | Sets the value of the SR Tuning Space field.
SetValue | Sets the value of the SR Value field.
SetDescription | Sets the value of the SR Description field.
SetCategory | Sets the value of the SR Category field.
SetLocaleID | Sets the value of the SR Locale ID field.
StreamTypeID | Retrieves the value of the SR Stream Type ID field. This field is automatically generated and cannot be set.
TuningSpace | Retrieves the value of the SR Tuning Space field.
Value | Retrieves the value of the SR Value field.
Description | Retrieves the value of the SR Description field.
Category | Retrieves the value of the SR Category field.
LocaleID | Retrieves the value of the SR Locale ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStreamType::Category

The Category method returns the value of the SR Category field from the CStreamType record object.

long Category(void);

Parameters

None.

Return Values

The value of the SR Category field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStreamType::Description

The Description method returns the value of the SR Description field from the CStreamType record object.

CString Description(void);

Parameters

None.

Return Values

The value of the SR Description field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStreamType::LocaleID

The LocaleID method returns the value of the SR Locale ID field from the CStreamType record object.

long LocaleID(void);

Parameters

None.

Return Values

The value of the SR Locale ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStreamType::SetCategory

The SetCategory method sets the value of the SR Category field in the CStreamType record object.

void SetCategory(
  long lCategory
);

Parameters

lCategory
The SR Category value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

SR Category


CStreamType::SetDescription

The SetDescription method sets the value of the SR Description field in the CStreamType record object.

void SetDescription(
  CString cszDescription
);

Parameters

cszDescription
The SR Description value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStreamType::SetLocaleID

The SetLocaleID method sets the value of the SR Locale ID field in the CStreamType record object.

void SetLocaleID(
  long lLocaleID
);

Parameters

lLocaleID
The SR Locale ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStreamType::SetTuningSpace

The SetTuningSpace method sets the value of the SR Tuning Space field in the CStreamType record object.

void SetTuningSpace(
  long lTuningSpace
);

Parameters

lTuningSpace
The SR Tuning Space value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.

See Also

SR Tuning Space


CStreamType::SetValue

The SetValue method sets the value of the SR Value field in the CStreamType record object.

void SetValue(
  long lValue
);

Parameters

lValue
The SR Value value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStreamType::StreamTypeID

The StreamTypeID method returns the value of the SR Stream Type ID field from the CStreamType record object.

long StreamTypeID(void);

Parameters

None.

Return Values

The value of the SR Stream Type ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStreamType::TuningSpace

The TuningSpace method returns the value of the SR Tuning Space field from the CStreamType record object.

long TuningSpace(void);

Parameters

None.

Return Values

The value of the SR Tuning Space field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStreamType::Value

The Value method returns the value of the SR Value field from the CStreamType record object.

long Value(void);

Parameters

None.

Return Values

The value of the SR Value field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CStreamTypeRecordset

The CStreamTypeRecordset class is used to select and create CStreamType objects from the StreamType table via functions in the CDatabaseRecordset parent class.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Stream Type.
GetRecordsetObject | Initializes a CStreamType object with records from the Guide database.
SetRecordsetObject | Saves the records in a CStreamType object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in streamty.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CSubGenre

Each CSubGenre object corresponds to a single record of the SubGenre table in the Guide database. You can use the methods of CSubGenre to retrieve and set field values. These objects are created and initialized by CSubGenreRecordset objects.

The CSubGenre class provides the following methods:

Method | Description
SetName | Sets the value of the SG Name field.
SubGenreID | Retrieves the value of the SG Sub Genre ID field. This field is automatically generated and cannot be set.
Name | Retrieves the value of the SG Name field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in subgenre.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CSubGenre::Name

The Name method returns the value of the SG Name field from the CSubGenre record object.

CString Name(void);

Parameters

None.

Return Values

The value of the SG Name field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in subgenre.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CSubGenre::SetName

The SetName method sets the value of the SG Name field in the CSubGenre record object.

void SetName(
  LPCTSTR cszName
);

Parameters

cszName
The SG Name value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in subgenre.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CSubGenre::SubGenreID

The SubGenreID method returns the value of the SG Sub Genre ID field from the CSubGenre record object.

long SubGenreID(void);

Parameters

None.

Return Values

The value of the SG SubGenre ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in subgenre.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CSubGenreRecordset

The CSubGenreRecordset class is used to select and create CSubGenre objects from the Sub-Genre table via functions in the CDatabaseRecordset parent class.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case SubGenre.
GetRecordsetObject | Initializes a CSubGenre object with records from the Guide database.
SetRecordsetObject | Saves the records in a CSubGenre object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in subgenre.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTheme

Each CTheme object corresponds to a single record of the Theme table in the Guide database. You can use the methods of CTheme to retrieve and set field values. These objects are created and initialized by CThemeRecordset objects.

The CTheme class provides the following methods:

Method | Description
SetThemeID | Sets the value of the T Theme ID field.
SetGenreID | Sets the value of the T Genre ID field.
SetSubGenreID | Sets the value of the T Sub Genre ID field.
ThemeID | Retrieves the value of the T Theme ID field.
GenreID | Retrieves the value of the T Genre ID field.
SubGenreID | Retrieves the value of the T Sub Genre ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in theme.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTheme::GenreID

The GenreID method returns the value of the T Genre ID field from the CTheme record object.

long GenreID(void);

Parameters

None.

Return Values

The value of the T Genre ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in theme.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTheme::SetGenreID

The SetGenreID method sets the value of the T Genre ID field in the CTheme record object.

void SetGenreID(
  long lGenreID
);

Parameters

lGenreID
The T Genre ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in theme.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTheme::SetSubGenreID

The SetSubGenreID method sets the value of the T Sub Genre ID field in the CTheme record object.

void SetSubGenreID(
  long lSubGenreID
);

Parameters

lSubGenreID
The T SubGenre ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in theme.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTheme::SetThemeID

The SetThemeID method sets the value of the T Theme ID field in the CTheme record object.

void SetThemeID(
  long lThemeID
);

Parameters

lThemeID
The T Theme ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in theme.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTheme::SubGenreID

The SubGenreID method returns the value of the T Sub Genre ID field from the CTheme record object.

long SubGenreID(void);

Parameters

None.

Return Values

The value of the T SubGenre ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in theme.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTheme::ThemeID

The ThemeID method returns the value of the T Theme ID field from the CTheme record object.

long ThemeID(void);

Parameters

None.

Return Values

The value of the T Theme ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in theme.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CThemeRecordset

The CThemeRecordset class is used to select and create CTheme objects from the Theme table via functions in the CDatabaseRecordset parent class.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Theme.
GetRecordsetObject | Initializes a CTheme object with records from the Guide database.
SetRecordsetObject | Saves the records in a CTheme object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in theme.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot

Each CTimeSlot object corresponds to a single record of the Time Slot table in the Guide database. You can use the methods of CTimeSlot to retrieve and set field values. These objects are created and initialized by CTimeSlotRecordset objects.

The CTimeSlot class provides the following methods:

Method | Description
SetChannelID | Sets the value of the TS Channel ID field.
SetEpisodeID | Sets the value of the TS Episode ID field.
SetStartTime | Sets the value of the TS Start Time field.
SetEndTime | Sets the value of the TS End Time field.
SetLength | Sets the value of the TS Length field.
SetPaymentAddress | Sets the value of the TS Payment Address field.
SetPaymentToken | Sets the value of the TS Payment Token field.
SetLastUpdate | Sets the value of the TS Last Update field.
SetPayPerView | Sets the value of the TS Pay Per View field.
SetClosedCaption | Sets the value of the TS Closed Caption field.
SetStereo | Sets the value of the TS Stereo field.
SetRerun | Sets the value of the TS Rerun field.
SetTapeInhibited | Sets the value of the TS Tape Inhibited field.
SetOtherPropertiesExist | Sets the value of the TS Other Properties Exist field.
SetAlternateDataExists | Sets the value of the TS Alternate Data Exists field.
SetAlternateAudioExists | Sets the value of the TS Alternate Audio Exists field.
TimeSlotID | Retrieves the value of the TS Time Slot ID field. This field is automatically generated and cannot be set.
ChannelID | Retrieves the value of the TS Channel ID field.
EpisodeID | Retrieves the value of the TS Episode ID field.
StartTime | Retrieves the value of the TS Start Time field.
EndTime | Retrieves the value of the TS End Time field.
Length | Retrieves the value of the TS Length field.
PaymentAddress | Retrieves the value of the TS Payment Address field.
PaymentToken | Retrieves the value of the TS Payment Token field.
LastUpdate | Retrieves the value of the TS Last Update field.
PayPerView | Retrieves the value of the TS Pay Per View field.
ClosedCaption | Retrieves the value of the TS Closed Caption field.
Stereo | Retrieves the value of the TS Stereo field.
Rerun | Retrieves the value of the TS Rerun field.
TapeInhibited | Retrieves the value of the TS Tape Inhibited field.
OtherPropertiesExist | Retrieves the value of the TS Other Properties Exist field.
AlternateDataExists | Retrieves the value of the TS Alternate Data Exists field.
AlternateAudioExists | Retrieves the value of the TS Alternate Audio Exists field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::AlternateAudioExists

The AlternateAudioExists method returns the value of the TS Alternate Audio Exists field from the CTimeSlot record object.

BOOL AlternateAudioExists(void);

Parameters

None.

Return Values

The value of the TS Alternate Audio Exists field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::AlternateDataExists

The AlternateDataExists method returns the value of the TS Alternate Data Exists field from the CTimeSlot record object.

BOOL AlternateDataExists(void);

Parameters

None.

Return Values

The value of the TS Alternate Data Exists field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::ChannelID

The ChannelID method returns the value of the TS Channel ID field from the CTimeSlot record object.

long ChannelID(void);

Parameters

None.

Return Values

The value of the TS Channel ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::ClosedCaption

The ClosedCaption method returns the value of the TS Closed Caption field from the CTimeSlot record object.

BOOL ClosedCaption(void);

Parameters

None.

Return Values

The value of the TS Closed Caption field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::EndTime

The EndTime method returns the value of the TS End Time field from the CTimeSlot record object.

COleDateTime EndTime(void);

Parameters

None.

Return Values

The value of the TS End Time field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::EpisodeID

The EpisodeID method returns the value of the TS Episode ID field from the CTimeSlot record object.

long EpisodeID(void);

Parameters

None.

Return Values

The value of the TS Episode ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::LastUpdate

The LastUpdate method returns the value of the TS Last Update field from the CTimeSlot record object.

COleDateTime LastUpdate(void);

Parameters

None.

Return Values

The value of the TS Last Update field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::Length

The Length method returns the value of the TS Length field from the CTimeSlot record object.

long Length(void);

Parameters

None.

Return Values

The value of the TS Length field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::OtherPropertiesExist

The OtherPropertiesExist method returns the value of the TS Other Properties Exist field from the CTimeSlot record object.

BOOL OtherPropertiesExist(void);

Parameters

None.

Return Values

The value of the TS Other Properties Exist field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::PaymentAddress

The PaymentAddress method returns the value of the TS Payment Address field from the CTimeSlot record object.

long PaymentAddress(void);

Parameters

None.

Return Values

The value of the TS Payment Address field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::PaymentToken

The PaymentToken method returns the value of the TS Payment Token field from the CTimeSlot record object.

long PaymentToken(void);

Parameters

None.

Return Values

The value of the TS Payment Token field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::PayPerView

The PayPerView method returns the value of the TS PayPerView field from the CTimeSlot record object.

BOOL PayPerView(void);

Parameters

None.

Return Values

The value of the TS PayPerView field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::Rerun

The Rerun method returns the value of the TS Rerun field from the CTimeSlot record object.

BOOL Rerun(void);

Parameters

None.

Return Values

The value of the TS Rerun field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetAlternateAudioExists

The SetAlternateAudioExists method sets the value of the TS Alternate Audio Exists field in the CTimeSlot record object.

void SetAlternateAudioExists(
  BOOL bAlternateAudioExists
);

Parameters

bAlternateAudioExists
The TS Alternate Audio Exists value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetAlternateDataExists

The SetAlternateDataExists method sets the value of the TS Alternate Data Exists field in the CTimeSlot record object.

void SetAlternateDataExists(
  BOOL bAlternateDataExists
);

Parameters

bAlternateDataExists
The TS Alternate Data Exists value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetChannelID

The SetChannelID method sets the value of the TS Channel ID field in the CTimeSlot record object.

void SetChannelID(
  long lChannelID
);

Parameters

lChannelID
The TS Channel ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetClosedCaption

The SetClosedCaption method sets the value of the TS Closed Caption field in the CTimeSlot record object.

void SetClosedCaption(
  BOOL bClosedCaption
);

Parameters

bClosedCaption
The TS Closed Caption value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetEndTime

The SetEndTime method sets the value of the TS End Time field in the CTimeSlot record object.

void SetEndTime(
  COleDateTime EndTime
);

Parameters

EndTime
The TS End Time value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetEpisodeID

The SetEpisodeID method sets the value of the TS Episode ID field in the CTimeSlot record object.

void SetEpisodeID(
  long lEpisodeID
);

Parameters

lEpisodeID
The TS Episode ID value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetLastUpdate

The SetLastUpdate method sets the value of the TS Last Update field in the CTimeSlot record object.

void SetLastUpdate(
  COleDateTime LastUpdate
);

Parameters

LastUpdate
The TS Last Update value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetLength

The SetLength method sets the value of the TS Length field in the CTimeSlot record object.

void SetLength(
  long lLength
);

Parameters

lLength
The TS Length value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetOtherPropertiesExist

The SetOtherPropertiesExist method sets the value of the TS Other Properties Exist field in the CTimeSlot record object.

void SetOtherPropertiesExist(
  BOOL bOtherPropertiesExist
);

Parameters

bOtherPropertiesExist
The TS Other Properties Exist value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetPaymentAddress

The SetPaymentAddress method sets the value of the TS Payment Address field in the CTimeSlot record object.

void SetPaymentAddress(
  long lPaymentAddress
);

Parameters

lPaymentAddress
The TS Payment Address value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetPaymentToken

The SetPaymentToken method sets the value of the TS Payment Token field in the CTimeSlot record object.

void SetPaymentToken(
  long lPaymentToken
);

Parameters

lPaymentToken
The TS Payment Token value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetPayPerView

The SetPayPerView method sets the value of the TS PayPerView field in the CTimeSlot record object.

void SetPayPerView(
  BOOL bPayPerView
);

Parameters

bPayPerView
The TS PayPerView value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetRerun

The SetRerun method sets the value of the TS Rerun field in the CTimeSlot record object.

void SetRerun(
  BOOL bRerun
);

Parameters

bRerun
The TS Rerun value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetStartTime

The SetStartTime method sets the value of the TS Start Time field in the CTimeSlot record object.

void SetStartTime(
  COleDateTime StartTime
);

Parameters

StartTime
The TS Start Time value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetStereo

The SetStereo method sets the value of the TS Stereo field in the CTimeSlot record object.

void SetStereo(
  BOOL bStereo
);

Parameters

bStereo
The TS Stereo value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::SetTapeInhibited

The SetTapeInhibited method sets the value of the TS Tape Inhibited field in the CTimeSlot record object.

void SetTapeInhibited(
  BOOL bTapeInhibited
);

Parameters

bTapeInhibited
The TS Tape Inhibited value to set.

Return Values

This method does not return a value.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::StartTime

The StartTime method returns the value of the TS Start Time field from the CTimeSlot record object.

COleDateTime StartTime(void);

Parameters

None.

Return Values

The value of the TS Start Time field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::Stereo

The Stereo method returns the value of the TS Stereo field from the CTimeSlot record object.

BOOL Stereo(void);

Parameters

None.

Return Values

The value of the TS Stereo field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::TapeInhibited

The TapeInhibited method returns the value of the TS Tape Inhibited field from the CTimeSlot record object.

BOOL TapeInhibited(void);

Parameters

None.

Return Values

The value of the TS Tape Inhibited field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlot::TimeSlotID

The TimeSlotID method returns the value of the TS Time Slot ID field from the CTimeSlot record object.

long TimeSlotID(void);

Parameters

None.

Return Values

The value of the TS Time Slot ID field.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


CTimeSlotRecordset

The CTimeSlotRecordset class is used to select and create CTimeSlot objects from the Time Slot table via functions in the CDatabaseRecordset parent class.

Method | Description
GetTableName | Returns the name of the table associated with this recordset, in this case Time Slot.
GetRecordsetObject | Initializes a CTimeSlot object with records from the Guide database.
SetRecordsetObject | Saves the records in a CTimeSlot object to the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in timeslot.h.
Import Library: Use dbsets.lib or dbsetsSt.lib.
Unicode: Yes.


Guide Database Schema

The collection of data describing current and upcoming broadcast video events is stored in a Microsoft® Jet database file called the Guide database. For more information on the structure of this database and how to investigate the database further, see the following sections:

  • About the Guide Database Schema
  • Using the Guide Database Schema
  • Guide Database Schema Reference


About the Guide Database Schema

Broadcast Architecture uses a Microsoft® Jet database to contain the Guide database. It does so to take advantage of a widely accepted database format that is easily programmed from various development tools, including the Microsoft® Visual C++® development system and the Microsoft® Visual Basic® development system. The Jet database engine:

  • Provides a high-level interface, called Data Access Objects (DAO), supported by various versions of Visual Basic and Visual C++.
  • Supports Structured Query Language (SQL) for easy definition of complex queries.
  • Is an Automation server.


Using the Guide Database Schema

To investigate and print out the details of the Guide database schema, including field descriptions, field sizes, and referential integrity rules, you can make a copy of the empty database installed by the broadcast client installation program. You can then examine the copy using Microsoft® Access, as described in the following procedure.

To examine the Guide database schema in detail
  1. Open Microsoft® Windows Explorer.
  2. Open the folder for Microsoft® WebTV® for Windows. This folder resides within the folder where the broadcast client software resides on your computer.
  3. Select the two database files, Tss.mdb and Tss.mdw.
  4. Copy these files to a different folder convenient to your development project.
  5. Use Access to open these files, and explore and print out the database structure as explained in the Access documentation.

For improved performance and ease of navigation, many of the tables in the Guide database schema are referentially linked with automatically generated counters. The referential integrity of these counter fields is guaranteed by:

  • The Microsoft® Jet database engine.
  • The schema structure.
  • The behavior of the database loader.

You can use these automatically generated identifier (ID) fields in queries and code that navigate among the tables. However, you should never store these identifier fields externally to the database, because their values are subject to ongoing change when the database loaders add and delete records as part of updating the database. If an application must save an external reference to an item in the database, it must use one of the key fields flagged as external to do so.


Guide Database Schema Reference

The Guide database schema contains the following tables.

Table | Description
AdTrack | Stores information about rotating advertisements such as the name of the file containing the ad and how often to display it.
Broadcast Property | Provides names for various broadcast properties, such as closed captioning.
Channel | Describes channels that can be tuned to.
Channel Property | Specifies properties associated with individual channels.
Channel Stream | Lists the data streams available for a specific channel.
Enhancement | Contains information used by Microsoft WebTV for Windows to link shows to their enhancements.
Episode | Describes television program episodes for which the database has information.
Episode Property | Specifies properties associated with individual show episodes.
Genre | Provides names for categories of show episodes, for example movies, television series, and so on.
Network | Defines the broadcast networks in use, such as ABC, CBS, NBC, and so on.
Rating | Defines names for individual ratings used in the various rating systems in use.
Rating System | Identifies the rating systems in use, such as the Motion Picture Association of America (MPAA) system.
Station | Defines the current set of individual broadcast content providers.
Stream Type | Provides names for all data streams available on a specific channel. The data streams can provide information such as stock and sports updates, or data for the Program Guide.
Sub-Genre | Provides names for subcategories within a genre.
Theme | Defines unique pairs of genres and subgenres to help classify show episodes.
Theme ID Mapping | Maps genres and subgenres information in the data sent by broadcast content providers to the genre-subgenre pairs in the Theme table.
Time Slot | Defines time slot and channel information for show episodes.

For information on how to examine the Guide database schema, see Using the Guide Database Schema. The following sections show the database schema. For information on the terms used in the reference section, see the Microsoft® Access documentation.


AdTrack Table

The AdTrack table in the Guide database contains information about rotation ads. The AdTrack table contains the following fields.

Field | Description
AdName | Name of the advertisement.
Impressions | Number of times the advertisement appears.
PageGroup | File name for the advertisement schedule.


AdName

The AdName field provides the name of the advertisement. This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Text
Field size: 20 characters
Default value: Not applicable
Required: Yes


Impressions

The Impressions field provides the number of times, or impressions, that the advertisement is displayed to the user. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


PageGroup

The PageGroup field provides the name of the advertisement schedule file. The Program Guide uses the advertisement schedule file to determine what advertisements to show. This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Text
Field size: 20 characters
Default value: Not applicable
Required: Yes


Broadcast Property Table

The Broadcast Property table in the Guide database gives names for various broadcast properties, such as closed captioning. The Broadcast Property table contains the following fields.

Field | Description
BP Abbreviation | Short name for this property.
BP Broadcast Property ID | Unique identifier for this broadcast property record.
BP Display Order | Priority of this item when there is not room to display all properties.
BP Name | Name for this property.
BP Pictogram Moniker | File name of the bitmap associated with this property.
BP Tuning Space | Tuning space to which this broadcast property belongs.


BP Abbreviation

The BP Abbreviation field contains the short name for this property, restricted to 4 bytes in length (for example, cc, st, or ppv). This field's values are as follows:

Key: Not applicable
Index: No
Data type: Text
Field size: 4 characters
Default value: Zero-length string
Required: Yes


BP Broadcast Property ID

The BP Broadcast Property ID field contains the unique identifier for this broadcast property record. This field's values are as follows:

Key: Primary
Index: Yes (no duplicates)
Data type: AutoNumber
Field size: Long integer
Default value: Automatically incremented
Required: Yes


BP Display Order

The BP Display Order field identifies the priority of this item when there is not room to display all properties. This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


BP Name

The BP Name field contains the name for this property (for example, closed captioned, stereo, or pay-per-view). This field's values are as follows:

Key: Not applicable
Index: No
Data type: Text
Field size: 128 characters
Default value: Zero-length string
Required: No


BP Pictogram Moniker

The BP Pictogram Moniker field contains the file name of the bitmap associated with this property. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Text
Field size: 255 characters
Default value: Zero-length string
Required: No


BP Tuning Space

The BP Tuning Space field identifies the tuning space to which this broadcast property belongs. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: Yes


Channel Table

The Channel table in the Guide database defines for each tuning space all properties and all channels that can be tuned to. The Channel table contains the following fields. For information on reserved fields, see Reserved Fields in the Channel Table.

Field | Description
C Channel ID | Internally generated unique identifier for this channel.
C Channel Number | Tuning identifier for the channel's input stream.
C Description | Extended description of this channel.
C End Time | Time when this channel becomes unavailable on the network.
C Enhancement Mapping ID | Mapping identifier from the Enhancement table.
C Last Update | Last time this row in the table was updated.
C Length | Length of the time the channel is available, in minutes.
C Rating ID | Foreign key from the Rating table.
C Start Time | Time when this channel becomes available on the network.
C Station ID | Station mapped to this channel during the specified time period.
C Tunable | Value that specifies whether the channel can be tuned to.
C Tuning Space | Logical identifier of the network type for the physical broadcast (for example, broadcast tuner, satellite, and so on).


Reserved Fields in the Channel Table

The Channel table contains several fields, listed following, that are not supported and that are reserved for future use:

  • C Display Mask
  • C Payment Address
  • C Payment Token


C Channel ID

The C Channel ID field provides an internally generated unique identifier for this channel. This field's values are as follows:

Key: Primary
Index: Yes (no duplicates)
Data type: AutoNumber
Field size: Long integer
Default value: Automatically incremented
Required: Yes


C Channel Number

The C Channel Number field provides the tuning identifier for the channel's input stream. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: Yes


C Description

The C Description field provides an extended description of this channel. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Memo
Field size: Not applicable
Default value: Zero-length string
Required: No


C End Time

The C End Time field provides the time when this channel becomes unavailable on the network. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Date/time
Field size: Not applicable
Default value: NULL date
Required: No


C Enhancement Mapping ID

The C Enhancement Mapping ID field provides the identifier of the enhancement in the Enhancement Mapping table. This field's values are as follows:

Key: Foreign key
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


C Last Update

The C Last Update field identifies the last time this row in the table was updated. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Date/time
Field size: Not applicable
Default value: Not applicable
Required: No


C Length

The C Length field provides the length of the time the channel is available, in minutes. This value is useful when channels are available only during certain times. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


C Rating ID

The C Rating ID field is a foreign key from the Rating table. This field's values are as follows:

Key: Foreign
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


C Start Time

The C Start Time field provides the time when this channel becomes available on the network. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Date/time
Field size: Not applicable
Default value: NULL date
Required: No


C Station ID

The C Station ID field provides the station mapped to this channel during the specified time period. This field's values are as follows:

Key: Foreign
Index: Yes (duplicates okay)
Data type: Number
Field size: Not applicable
Default value: Zero
Required: Yes


C Tunable

The C Tunable field specifies whether the channel represents a broadcast that can be tuned to. For example, users cannot tune to some Program Guide channels.

This field enables applications to quickly determine whether a channel can be tuned to without having to query the Channel Property table. This field is provided to enhance performance, as are the property fields in the Episode table.

This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Yes/no
Field size: Not applicable
Default value: Yes
Required: No


C Tuning Space

The C Tuning Space field provides the logical identifier of the network type of the physical broadcast (for example, broadcast tuner, satellite, and so on). This field's values are as follows:

Key: Not applicable
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: Yes


Channel Property Table

The Channel Property table in the Guide database specifies properties associated with individual channels. The Channel Property table contains the following fields.

Field | Description
CP Broadcast Property ID | Foreign key from the Broadcast Property table.
CP Channel ID | Foreign key from the Channel table.


CP Broadcast Property ID

The CP Broadcast Property ID field contains a foreign key from the Broadcast Property table. This field's values are as follows:

Key: Primary
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Not applicable
Required: No


CP Channel ID

The CP Channel ID field contains a foreign key from the Channel table. This field's values are as follows:

Key: Primary
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


Channel Stream Table

The Channel Stream table in the Guide database lists the data streams available on a specific channel. The Channel Stream table contains the following fields.

Field | Description
CSR Channel ID | Unique identifier for this channel.
CSR Name | Name of a stream.
CSR Stream Type ID | Unique identifier for this type of stream.
CSR SubChannel | Subchannel relative to the channel specified by the CSR Channel ID field.


CSR Channel ID

The CSR Channel ID field contains a foreign key from the Channel table. This field's values are as follows:

Key: Primary, foreign
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: Yes


CSR Name

The CSR Name field contains the user-oriented label used to identify this stream in this configuration. The CSR Name value overrides the description in the Stream Type table. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Memo
Field size: Not applicable
Default value: Zero-length string
Required: No


CSR Stream Type ID

The CSR Stream Type ID field contains the unique identifier for this stream type. This field's values are as follows:

Key: Primary, foreign
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: Yes


CSR SubChannel

The CSR SubChannel field contains the subchannel number used to identify this stream relative to the channel. This field's values are as follows:

Key: Primary
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


Enhancement Table

The Enhancement table in the Guide database contains information used by to link shows to their enhancements. The Enhancement table contains the following fields.

Field | Description
EN Address | Internet Protocol (IP) address of the enhancement stream.
EN Enhancement ID | Identifying name for this enhancement.
EN Expire Date | Expiration date extracted from a show reference. This date can be used in a deletion query to update this table.
EN Mapping ID | Identifier used by Microsoft® WebTV® for Windows® for efficient display of enhancements.
EN Preload URL | Home or start page for this enhancement.
EN Show Reference | Value that identifies one or more episodes to have enhancements.
EN Title | Title used to display the enhancement in the user interface.


EN Address

The EN address field is the IP address for the enhancement data stream. This field's values are as follows:

Key: Primary
Index: No
Data type: Memo
Field size: Not applicable
Default value: Zero-length string
Required: No


EN Enhancement ID

The EN Enhancement ID field contains a unique identifier for this enhancement. This field's values are as follows:

Key: Primary
Index: Yes (no duplicates)
Data type: Text
Field size: 38 characters
Default value: Zero-length string
Required: Yes


EN Expire Date

The EN Expire Date field is used to determine when to remove this enhancement from the database. This field's values are as follows:

Key: Primary
Index: No
Data type: Date
Field size: Long integer
Default value: NULL date
Required: No


EN Mapping ID

The EN Mapping ID field is used by WebTV for Windows for the efficient display of enhancements. This field is automatically generated when the enhancement record is created. This field's values are as follows:

Key: Primary
Index: Yes
Data type: AutoNumber
Field size: Long integer
Default value: Automatically incremented
Required: Yes


EN Preload URL

The EN Preload URL field is the Uniform Resource Locator (URL) of the data to download for this enhancement. Preloading this data enables the enhancement to include more data than the available bandwidth otherwise allows. This field's values are as follows:

Key: Primary
Index: No
Data type: Memo
Field size: Not applicable
Default value: Zero-length string
Required: No


EN Show Reference

The EN Show Reference field is the identifier of the show that uses this enhancement. This field's values are as follows:

Key: Primary
Index: Yes (duplicates okay)
Data type: Memo
Field size: Not applicable
Default value: Zero-length string
Required: No


EN Title

The EN Title field is the title of the enhancement. This field's values are as follows:

Key: Primary
Index: Yes
Data type: String
Field size: 255 characters
Default value: Zero-length string
Required: No


Episode Table

The Episode table in the Guide database describes each television program episode. The Episode table contains the following fields.

Field | Description
E Abbreviation | Bit field that indicates how to abbreviate episode titles for smaller display areas.
E Description | Extended description of this episode.
E Display Mask | This field is reserved for future use.
E Episode ID | Internally generated unique identifier for this episode.
E Last Update | Last time this row in the table was updated.
E Rating ID | Foreign key from the Rating table.
E Theme ID | Foreign key from the Theme table.
E Title | Program title.


E Abbreviation

The E Abbreviation field contains a bit field that indicates how to abbreviate episode titles for smaller display areas. For example, "Mars: Close Encounters with the Red Planet," appears as "Mars: Close Encounters" when this field has a binary value of 1110000. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


E Description

The E Description field contains an extended description of this episode (for example, "Mail order diplomas investigated"). This field's values are as follows:

Key: Not applicable
Index: No
Data type: Text
Field size: 255 characters
Default value: Zero-length string
Required: No


E Enhancement Mapping ID

The E Attachment field contains a URL or application associated with this episode. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Memo
Field size: Not applicable
Default value: Zero-length string
Required: No


E Episode ID

The E Episode ID field provides an internally generated unique identifier for this episode. This field's values are as follows:

Key: Primary
Index: Yes (no duplicates)
Data type: AutoNumber
Field size: Long integer
Default value: Automatically incremented
Required: Yes


E Last Update

The E Last Update field contains the last time this row in the table was updated. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Date/time
Field size: Not applicable
Default value: Not applicable
Required: No


E Rating ID

The E Rating ID field contains a foreign key from the Rating table. This field's values are as follows:

Key: Foreign
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


E Theme ID

The E Theme ID field contains a foreign key from the Theme table. This field's values are as follows:

Key: Foreign
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


E Title

The E Title field contains the program title (for example, Time & Again). This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Text
Field size: 255 characters
Default value: Not applicable
Required: Yes


Episode Property Table

The Episode Property table in the Guide database specifies properties associated with individual program episodes. The Episode Property table contains the following fields.

Field | Description
Broadcast Property ID | Foreign key from the Broadcast Property table.
Episode ID | Foreign key from the Episode table.


Broadcast Property ID

The Broadcast Property ID field contains a foreign key from the Broadcast Property table. This field's values are as follows:

Key: Foreign
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Not applicable
Required: Yes


Episode ID

The Episode ID field contains a foreign key from the Episode table. This field's values are as follows:

Key: Foreign
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: Yes


Genre Table

The Genre table in the Guide database provides names for different categories of program episodes. The Genre table contains the following fields.

Field | Description
G Genre ID | Unique identifier for this record.
G Name | Name of this genre (for example, movies, television series, and so on).
G Tuning Space | Numeric identifier for the data source that defines this genre.


G Genre ID

The G Genre ID field contains the unique identifier for this genre. This field's values are as follows:

Key: Primary
Index: Yes (no duplicates)
Data type: AutoNumber
Field size: Long integer
Default value: Automatically incremented
Required: Yes


G Name

The G Name field contains the name of this genre (for example, movies, television series, and so on). This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Text
Field size: 50 characters
Default value: Not applicable
Required: No


G Tuning Space

The G Tuning Space field contains a numeric identifier for the data source that defines this genre. This value identifies which loader handles the source data. This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


Network Table

The Network table in the Guide database defines information about various broadcast networks. The Network table contains the following fields.

Field | Description
N LogoMoniker | Name of the image file that contains the network logo.
N Name | Name of the network.
N Network ID | Automatically generated unique identifier for the network.


N LogoMoniker

The N LogoMoniker field provides the name of the bitmap file containing the logo for this network. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Text
Field size: 255 characters
Default value: Not applicable
Required: No


N Name

The N Name field provides the name of this network. This field's values are as follows:

Key: Not applicable
Index: Yes (no duplicates)
Data type: Text
Field size: 50 characters
Default value: Zero-length string
Required: No


N Network ID

The N Network ID field provides an internally generated unique identifier for this network. This field's values are as follows:

Key: Primary
Index: Yes (no duplicates)
Data type: AutoNumber
Field size: Long integer
Default value: Automatically incremented
Required: Yes


Rating Table

The Rating table in the Guide database defines rating names for individual ratings used in various rating systems. Any time an application changes an entry in the Rating table, that application must update the .rat file with new descriptions. Each record in the Rating table is roughly equivalent to a label entry in a Platform for Internet Content Selection (PICS) rating file. The Rating table contains the following fields.

Field | Description
R Description | Name of this rating (for example, PG-13) in the rating system.
R Pictogram Moniker | File name of the bitmap associated with this rating.
R Rating | Numerical value used to rank this rating in the rating system.
R Rating ID | Unique identifier for this record.
R Rating System ID | Identifier for the rating system that uses this rating entry.


R Description

The R Description field contains the name of this rating (for example, PG-13) in the rating system. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Text
Field size: 50 characters
Default value: Not applicable
Required: No


R Pictogram Moniker

The R Pictogram Moniker field contains the file name of the bitmap associated with this rating. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Text
Field size: 255 characters
Default value: Zero-length string
Required: No


R Rating

The R Rating field contains the numerical value used to rank this rating in the rating system. This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Number
Field size: Single
Default value: Zero
Required: No


R Rating ID

The R Rating ID field contains a unique identifier for this rating. This field's values are as follows:

Key: Primary
Index: Yes (no duplicates)
Data type: AutoNumber
Field size: Long integer
Default value: Automatically incremented
Required: Yes


R Rating System ID

The R Rating System ID field contains an identifier for the rating system using this rating entry. This field's values are as follows:

Key: Foreign
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


Rating System Table

The Rating System table in the Guide database provides names for MPAA-style ratings. The Rating System table contains the following fields.

Field | Description
RS Description | Description of the rating system.
RS Name | Name of the rating system.
RS Rating System ID | Unique identifier for this record.
RS Tuning Space | Data source defining this rating system.


RS Description

The RS Description field contains the description of this rating system. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Text
Field size: 128 characters
Default value: No
Required: No


RS Name

The RS Name field contains the name of this rating system (for example, MPAA). This field's values are as follows:

Key: Not applicable
Index: Yes (no duplicates)
Data type: Text
Field size: 50 characters
Default value: Not applicable
Required: No


RS Rating System ID

The RS Rating System ID field contains the unique identifier for this rating system. This field's values are as follows:

Key: Primary
Index: Yes (no duplicates)
Data type: AutoNumber
Field size: Not applicable
Default value: Automatically incremented
Required: Yes


RS Tuning Space

The RS Tuning Space field contains the data source defining this rating system. This value identifies which loader handles the source data. This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


Station Table

The Station table in the Guide database defines individual broadcast content providers. The Station table contains the following fields.

Field | Description
S Call Letters | Call letters of this station (HBOW, for example).
S Description | Extended description of the programming provided by this station.
S Logo | Name of the file that contains the logo bitmap for this station.
S Name | Name of this station (The Sports Channel,for example).
S Network ID | Foreign key from the Network table.
S Station ID | Internally generated unique identifier for this station.


S Call Letters

The S Call Letters field provides the call letters of this station (KLMN, for example). This field's values are as follows:

Key: Not applicable
Index: Yes (no duplicates)
Data type: Text
Field size: 5 characters
Default value: Not applicable
Required: Yes


S Description

The S Description field provides an extended description of the programming provided by this station. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Memo
Field size: Not applicable
Default value: Zero-length string
Required: No


S Logo

The S Logo field provides the name of the file containing the logo bitmap for this station. The file suffix is not included in this string. For example, the S Logo value for the Program Guide record is Msepg, not Msepg.bmp. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Text
Field size: 255 characters
Default value: Zero-length string
Required: No


S Name

The S Name field provides the name of this station (The Sports Channel, for example). This field's values are as follows:

Key: Not applicable
Index: No
Data type: Text
Field size: 50 characters
Default value: Zero-length string
Required: No


S Network ID

The S Network ID field is a foreign key from the Network table. This field's values are as follows:

Key: Foreign
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


S Station ID

The S Station ID field provides an internally generated unique identifier for this station. This field's values are as follows:

Key: Primary
Index: Yes (no duplicates)
Data type: AutoNumber
Field size: Long integer
Default value: Automatically incremented
Required: Yes


Stream Type Table

The Stream Type table in the Guide database gives names for all data streams available on a specific channel. The Stream Type table contains the following fields.

Field | Description
SR Category | Value that specifies the category of the stream.
SR Description | Name of this stream (for example, video, data, and so on).
SR Locale ID | Locale identifier of the stream.
SR Stream Type ID | Unique identifier for this stream type.
SR Tuning Space | Value that identifies the source that defines this stream.
SR Value | Integer passed to the driver when requesting a specific video stream.


SR Category

The SR Category field specifies the category for the stream. This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: Yes


SR Description

The SR Description field contains the name of this stream (for example, video, data, and so on). This field's values are as follows:

Key: Not applicable
Index: No
Data type: Memo
Field size: Not applicable
Default value: Zero-length string
Required: No


SR Locale ID

The SR Locale ID field specifies the locale identifier for the stream. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


SR Stream Type ID

The SR Stream Type ID field contains the unique identifier for this stream type. This field's values are as follows:

Key: Primary
Index: Yes (no duplicates)
Data type: AutoNumber
Field size: Long integer
Default value: Automatically incremented
Required: Yes


SR Tuning Space

The SR Tuning Space field identifies the source that defines this stream. This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


SR Value

The SR Value field contains the integer passed to the driver when requesting a specific video stream. This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


Sub-Genre Table

The Sub-Genre table in the Guide database provides names for subcategories within a genre. The Sub-Genre table contains the following fields.

Field | Description
SG Name | Name of this subgenre (for example, science fiction).
SG Sub Genre ID | Unique identifier for this record.


SG Name

The SG Name field contains the name of this subgenre (for example, science fiction). This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Text
Field size: 50 characters
Default value: Not applicable
Required: No


SG Sub Genre ID

The SG Sub Genre ID field contains the unique identifier for this subgenre. This field's values are as follows:

Key: Not applicable
Index: Yes (no duplicates)
Data type: AutoNumber
Field size: Long integer
Default value: Automatically incremented
Required: Yes


Theme Table

The Theme table in the Guide database defines information about themes. A theme allows an episode to be associated with multiple genre/subgenre pairs, because genre/subgenre pairs can share the same T Theme ID field.

For example, a motion picture might have a T Theme ID of 2, placed in the E Theme ID field of the Episode table. In the Theme table, the genre/subgenre pair Science Fiction/Movie and the genre/subgenre pair Movie/Action can both share that same T Theme ID of 2.

The Theme table contains the following fields.

Field | Description
T Genre ID | Foreign key from the Genre table.
T Sub Genre ID | Foreign key from the Sub-Genre table.
T Theme ID | Internally generated unique identifier for this record.


T Genre ID

The T Genre ID field contains a foreign key from the Genre table. This field's values are as follows:

Key: Primary
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: Yes


T Sub Genre ID

The T Sub Genre ID field contains a foreign key from the Sub-Genre table. This field's values are as follows:

Key: Primary
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: Yes


T Theme ID

The T Theme ID field contains the internally generated unique identifier for this theme. This field's values are as follows:

Key: Primary
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: Yes


Theme ID Mapping Table

The Theme ID Mapping table in the Guide database maps a genre, subgenre, or genre/subgenre pair to a corresponding theme identifier. The Theme ID Mapping table contains the following fields.

Field | Description
TM Genre Identifier | Identifier of the genre to map. Either this field or the TM Genre Name field can be used to specify the genre.
TM Genre Name | Name of the genre to map. Either this field or the TM Genre Identifier field can be used to specify the genre.
TM SubGenre Identifier | Identifier of the subgenre to map. Either this field or the TM SubGenre Name field can be used to specify the subgenre.
TM SubGenre Name | Name of the subgenre to map. Either this field or the TM SubGenre Identifier field can be used to specify the subgenre.
TM Theme ID | Theme identifier.
TM Tuning Space | Tuning space that this mapping applies to.


TM Genre Identifier

The TM Genre Identifier field specifies the genre to map. Either this field or TM Genre Name can be use to specify the genre. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


TM Genre Name

The TM Genre Name field specifies the genre to map. Either this field or TM Genre Identifier can be use to specify the genre. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Text
Field size: 255 characters
Default value: Not applicable
Required: No


TM SubGenre Identifier

The TM SubGenre Identifier field specifies the subgenre to map. Either this field or TM SubGenre Name can be use to specify the subgenre. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


TM SubGenre Name

The TM SubGenre Name field specifies the subgenre to map. Either this field or TM SubGenre Identifier can be use to specify the subgenre. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Text
Field size: 255 characters
Default value: Not applicable
Required: No


TM Theme ID

The TM Theme ID field specifies the theme identifier to which the genre, subgenre, or genre/subgenre pair should be mapped to. This field's values are as follows:

Key: Not applicable
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Not applicable
Required: No


TM Tuning Space

The TM Tuning Space field specifies the tuning space for which this mapping applies. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Number
Field size: Long integer
Default value: Not applicable
Required: No


Time Slot Table

The Time Slot table in the Guide database defines time slot and channel information for each program episode. The Time Slot table contains the following fields. For information on reserved fields, see Reserved Fields in the Time Slot Table,

Field | Description
TS Alternate Audio Exists | Value that indicates whether an alternate audio stream is available.
TS Alternate Data Exists | Value that indicates whether an alternate data stream is available.
TS Channel ID | Foreign key from the Channel table.
TS Closed Caption | Value that specifies whether the broadcast has closed captions.
TS End Time | Ending time for this time slot.
TS Episode ID | Foreign key from the Episode table.
TS Last Update | Last time this row in the table was updated.
TS Length | Length of this time slot, in minutes.
TS Other Properties Exist | Value that indicates whether additional properties exist for the broadcast.
TS Rerun | Value that specifies whether the broadcast is a rerun.
TS Start Time | Beginning time for this time slot.
TS Stereo | Value that specifies whether the broadcast is in stereo.
TS Time Slot ID | Unique identifier for this time slot record.


Reserved Fields in the Time Slot Table

The Time Slot table contains the following fields that are not supported and that are reserved for future use:

  • TS Pay Per View
  • TS Payment Address
  • TS Payment Token
  • TS Tape Inhibited


TS Alternate Audio Exists

The TS Alternate Audio Exists field indicates whether an alternate audio stream is available. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Yes/no
Field size: Not applicable
Default value: Zero
Required: No


TS Alternate Data Exists

The TS Alternate Data Exists field indicates whether an alternate data stream is available. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Yes/no
Field size: Not applicable
Default value: Zero
Required: No


TS Channel ID

The TS Channel ID field contains a foreign key from the Channel table. This field's values are as follows:

Key: Primary, foreign
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


TS Closed Caption

The TS Closed Caption field specifies whether the broadcast has closed captions. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Yes/no
Field size: Not applicable
Default value: Zero
Required: No


TS End Time

The TS End Time field contains the ending time for this time slot. This field's values are as follows:

Key: Primary
Index: Yes (duplicates okay)
Data type: Date/time
Field size: Not applicable
Default value: Not applicable
Required: Yes


TS Episode ID

The TS Episode ID field contains a foreign key from the Episode table. This field's values are as follows:

Key: Primary
Index: Yes (duplicates okay)
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


TS Last Update

The TS Last Update field contains the last time this row in the table was updated. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Date/time
Field size: Not applicable
Default value: Not applicable
Required: Yes


TS Length

The TS Length field contains the length of this time slot in minutes. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Number
Field size: Long integer
Default value: Zero
Required: No


TS Other Properties Exist

The TS Other Properties Exist field indicates whether additional properties exist for the broadcast. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Yes/no
Field size: Not applicable
Default value: Zero
Required: No


TS Rerun

The TS Rerun field specifies whether the broadcast is a rerun. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Yes/no
Field size: Not applicable
Default value: Zero
Required: No


TS Start Time

The TS Start Time field contains the beginning time for this time slot. This field's values are as follows:

Key: Primary
Index: Yes (duplicates okay)
Data type: Date/time
Field size: Not applicable
Default value: Not applicable
Required: Yes


TS Stereo

The TS Stereo field specifies whether the broadcast is in stereo. This field's values are as follows:

Key: Not applicable
Index: No
Data type: Yes/no
Field size: Not applicable
Default value: Zero
Required: No


TS Time Slot ID

The TS Time Slot ID field contains a unique identifier for this time slot record. This field's values are as follows:

Key: Not applicable
Index: Yes (no duplicates)
Data type: AutoNumber
Field size: Long integer
Default value: Automatically incremented
Required: Yes


Program Guide Registry Entries

Guide database loaders depend on information stored in the computer's registry to do their job properly. The registry entries that provide this information are found in the following registry subkeys:

  • Tuning Spaces
  • Loaders


Tuning Spaces Subkey

This registry subkey lists all tuning spaces, that is all sources that provide Program Guide data. Each tuning space has a tuning identifier that uniquely identifies it.

The list of identifiers specifying the available tuning spaces is found under the Tuning Spaces subkey as follows:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\TV Services\
Tuning Spaces\TuningIdentifierList

TuningIdentifierList is an ordered list of all tuning identifier subkeys. This list provides a way to choose the appropriate loader for a given tuning space. The following table describes the entries under each TuningIdentifierList subkey.

Value | Type | Meaning
Name | String | Short name of this tuning space for display to the user
AMFClass | GUID | Globally unique identifier (GUID) passed to Loadstub.exe to run this loader
Description | String | Description of this tuning space for display to the user
Loader | GUID | Globally unique identifier (GUID) for the Guide database loader used for this tuning space
MinChannel | short | Minimum channel number acceptable for this tuning space
MaxChannel | short | Maximum channel number acceptable for this tuning space
Devices | String | List of logical device identifiers for all devices that support the Microsoft® ActiveX® control for video (the Video control)

A broadcast receiver card can handle more than one tuning space. For example, NTSC cards provide both cable and over-the-air broadcast channels from an external antenna. In these situations, the installation portion of Television System Services (TSS) must make entries in the registry for each possible tuning space. In the preceding example, cable and broadcast need to be treated as two separate tuning spaces, because their channel numbering spaces overlap and conflict in many cases.


Loaders Subkey

This registry subkey contains a sub key for each database loader installed. The name of the sub key for a loader is its globally unique identifier (GUID). The subkey for a loader looks like this:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\TV
Services\Guide\Loaders\LoaderGUIDs

Where LoaderGUIDs is the GUID for the subkey. The following table lists and describes the entries under this registry subkey.

Value | Type | Meaning
Name |  | File name of the database loader dynamic-link library (DLL).
TuningID |  | List providing a pointer to the tuning spaces handled by the database loader identified by a particular GUID.
LastAttemptTime |  | Date and time this loader most recently started. If this entry does not exist, then the loader never attempted to run.
LastCompletionTime |  | Date and time this loader most recently finished running. If this entry does not exist, then the loader never finished running successfully.
LastCompletionResult |  | Return value from the loader DLL the last time it finished running.

Each loader can have additional loader-specific information in the Program Guide Loaders subkey.


Video Control

In Broadcast Architecture, you can use the Microsoft® ActiveX® control for video (the Video control, Vid.ocx) to manage and display multimedia streams in Web pages and applications. Although the Video control can also be used to display video in enhancement pages, it is usually more convenient to use the Enhancement control. For more information, see Which Video Control Should I Use?

The following topics describe the Video control, explain how to use it in an application, and outline reference information for the object classes implemented by the Video control:

  • About the Video Control
  • Using the Video Control
  • Video Control Reference


About the Video Control

Your application can use the Microsoft® ActiveX® control for video (the Video control, Vid.ocx) to manage audio and video streams. This control also enables your application to interact with the Video Access server, Vidsvr.exe, to manage user purchase of broadcast items, such as pay-per-view shows.

The input stream that the Video control displays can be a live stream, such as an analog television broadcast received through a television tuner card.

Because the Video control is an ActiveX control, it cannot exist outside of a container application. Examples of containers are application windows, forms written using the Microsoft® Visual Basic® development system, and HTML pages displayed in Web browsers.

For more information, see the following topics:

  • Video Access Server
  • Available Devices
  • Event Notification
  • Device Contention


Video Access Server

The video access server, Vidsvr.exe, is a component of Broadcast Architecture that manages video devices by using the Microsoft® DirectShow™ filter graph. Much of the functionality exposed by the Video control, such controlling devices, is actually implemented in the video access server.

The object definition language file, Vidsvr.odl, defines interfaces exposed by both the video access server and the Video control. To utilize the functionality of the video access server, call the corresponding methods, properties, and events of the Video control.


Available Devices

When a broadcast client system starts, the Video Access server creates a list of the devices available on the client. Using this list, your application can programmatically query and control individual devices. In the current version of Broadcast Architecture, the only listed device is an analog television tuner card. Future versions will support other input devices, such as a file playback device and output devices.

This list is available to the Video control through the BPCDevices collection. Each BPCDeviceBase object in this collection represents a particular device on the client. The properties and methods of BPCDeviceBase can programmatically query and control these devices.

The Video Access server builds this list of available multimedia devices using the Plug and Play enumeration in the DirectShow application programming interface (API). You can then set the Video control input device to one of the enumerated devices.


Event Notification

The Video control sends events relating to itself such as BPCVid.DblClick, which is raised when a user double-clicks inside the control, to your application.

The Video control uses events to implement device contention resolution. It uses the BPCVid.GotControl and BPCVid.LostControl methods to notify applications when they have or lose control of a particular device. For more information, see Device Contention.

To receive event notifications from the Video control, you must implement event-handler methods in your application. These methods are called by the Video control when an event occurs.


Device Contention

The Video control uses a cooperative mechanism to prevent device conflicts. This prevents multiple instances of the Video control from attempting to control a particular device at the same time, which would cause unpredictable results.

The BPCVid.GotControl and BPCVid.LostControl event notifications are used to inform an application that it has control or must relinquish control of a particular device.

For example, if your application needs to use a particular device it must first request control of the device by setting the input or output property of the Video control equal to the device. Your application should then wait until it receives a GotControl notification before it uses the device. If the application attempts to access the device before it has control, unexpected behavior can occur.

Similarly, if your application receives a LostControl notification, it should immediately stop using the device in question until it can regain control. Otherwise, unexpected behavior occurs when multiple applications access the device.

Thus, in order to handle device contention, your application must implement GotControl and LostControl event handlers.

The device contention protocol also implements priority levels for application access to devices. These priority levels are used when two applications are in contention for a device. In this case, control is given to the application with higher priority. If both applications have equal priority, the application that currently has control of the device retains control. You can set the priority for an instance of the Video control using the BPCVid.Priority property.


Using the Video Control

The Microsoft® ActiveX® control for video (the Video control) is a dual-interface ActiveX control. This functionality means you can use the control from a variety of programming environments, such as World Wide Web pages, applications built in the Microsoft® Visual Basic® development system, Java applets and applications, and C++ applications.

For details on working with the Video control to display video streams, manage devices, and interact with the Video Access server, see:

  • Adding the Video Control to an Application
  • Setting an Input Device
  • Setting an Output Device
  • Setting an Input Channel
  • Suspending the Video Server
  • Tuning to Receive VBI Data
  • Reinitializing the Filter Graph
  • Handling Power Management Events

For additional information on the tasks involved in using the Video control, see Displaying Video. In addition, Broadcast Architecture material includes sample applications that demonstrate use of the Video control. To locate these samples, see Broadcast Architecture Sample Applications.

Note If you are displaying the Video control in a window that does not set have the WS_CLIPCHILDREN style set, the Video display may not refresh properly.

This is of concern to developers programming in C++ using the Microsoft® Foundation Classes (MFC). By default, MFC windows do not set the WS_CLIPCHILDREN style. To cause the Video control to refresh properly in these applications you can either override CWnd::PreCreateWindow to set this style, or paint the correct color key during the call to CWnd::OnEraseBkgnd. The correct color key value can be obtained from BPCVid.ColorKey.

To locate more information about the WS_CLIPCHILDREN window style and the CWnd::PreCreateWindow and CWnd::OnEraseBkgnd methods, see Further Information on Streaming Video Services for the Client.


Adding the Video Control to an Application

The Video control is an ActiveX control that you can use to display video in an application. Because the Video control uses ActiveX, it can be called from any COM-supporting programming environment.

To use the Video control in an application, you must first add it to your project. How you do this differs depending on which programming environment you use. For detailed information about how to add an ActiveX control to your project, see the documentation for your programming environment.

The following topics describe how to add the Video control to some common programming environments:

  • Adding the Video Control to a Web Page
  • Adding the Video Control to a Microsoft Visual Basic Project
  • Adding the Video Control to a Microsoft Visual C++ Project
  • Adding the Video Control to a Microsoft Visual J++ Project


Adding the Video Control to a Web Page

You can add the Video control to Web pages. To do this, insert the control using an <OBJECT> tag such as the following:

<OBJECT
  ID = vid
  CLASSID = "clsid:31263EC0-2957-11CF-A1E5-00AA9EC79700"
  BORDER = 0
  VSPACE = 0
  HSPACE = 0
  ALIGN = TOP
  HEIGHT = 100%
  WIDTH = 100%
>
</OBJECT>

Note In the preceding object tag, you can change the value of any parameter except CLASSID. The CLASSID value must appear exactly as shown.

Once you have added the control to the HTML page, you can access its methods and properties from script or other controls embedded in the HTML page. For example, the following Microsoft® Visual Basic® Scripting Edition (VBScript) sets the input channel for an instance of the Video control named vid.

<SCRIPT LANGUAGE = VBScript>
Dim MyChannel = 12

For Each Device In vid.Devices
  If vid.Input.HasChannel Then
    If Device.ChannelAvailable(MyChannel)
      vid.Input = Device
      vid.Input.Channel = MyChannel
      Exit For
    End If
  End If
Next

</SCRIPT>

The software included with the Broadcast Architecture Programmer's Reference includes a sample HTML application, WebTune, that uses the Video control. For more information about this sample, see Broadcast Architecture Sample Applications.


Adding the Video Control to a Microsoft Visual Basic Project

You can add the Video control to a Visual Basic application. To do this, use the following procedure.

To add the Video control to a Visual Basic project
  1. Open or create a Visual Basic project.
  2. Select Components from the Project menu. A list of the installed components appears.
  3. Select the check box next to Microsoft BPC Video Server and Control module. If the control is not listed, check whether the computer has the Microsoft® WebTV® for Windows component of the Microsoft® Windows 98® operating system installed.
  4. Click OK. The Video control is added to the project and appears as an icon in the Toolbox.

Once the Video control is added to the project, you can drag-and-drop it onto a form or dialog box and set its properties using the form or dialog box's property sheet. You can call the methods and properties of the Video control using the name of the Video control. For example, if the name of the Video control is vid, you would use the following to display the Video control's About dialog box.

vid.AboutBox

To create instances of other Microsoft BPC Video Server and Control module objects, use the New keyword. For example, the following creates a new BPCVBIControl object.

Dim vbi As BPCVBIControl
Set vbi = New BPCVBIControl

Software provided with the Broadcast Architecture Programmer's Reference includes a sample Visual Basic control, Vid_Tune.ocx, and a sample Visual Basic application, VidCntrl.exe, that use the Video control. For more information about these samples, see Broadcast Architecture Sample Applications.


Adding the Video Control to a Microsoft Visual C++ Project

You can add the Video control to Microsoft® Foundation Classes (MFC) and Active Template Library (ATL) projects in the Microsoft® Visual C++® development system. To do this, use the following procedure.

To add the Video control to a Visual C++ project
  1. Open or create a Visual C++ project.
  2. Select Add To Project from the Project menu.
  3. Select Components and Controls from the pop-up menu.

    A dialog box appears displaying a set of folders containing components. Open the folder titled Registered ActiveX Controls.

  4. Select Vid Control from the list and click the Insert button. If Vid Control is not included in the list, verify that the WebTV for Windows component of Windows 98 is installed.

    The Confirm Classes dialog box appears, which enables you to select which of the Video control's classes you would like to add to your application.

  5. Select the check boxes next to the classes you want to add to your project. Note that several of the classes listed are reserved for future use and are not currently implemented. For a list of the Video control's reserved classes, see Reserved Classes in the Video Control.

    Visual C++ automatically generates header and implementation files for the classes you select and adds them to your project.

Once the Video control has been added to your project, you can create instances of Video control objects, access the Video control's methods, properties, and events, and add the Video control to user interfaces.

Note To access objects that are not part of the Video control, such as BPCVBIControl and BPCSuspend, run Mytyplib.exe on Vidsvr.odl and insert the generated files into your project. In addition, you can use the header file Bpcsusp.h, which wraps the IBPCSuspend interface and provides additional suspend functionality.

The software included with the Broadcast Architecture Programmer's Reference includes a sample MFC application, VideoMFC.exe, that uses the Video control. For more information about this sample, see Broadcast Architecture Sample Applications.


Adding the Video Control to a Microsoft Visual J++ Project

You can add the Video control to projects built using the Microsoft® Visual J++™ development system for Java. To do this, follow this procedure:

To add the Video control to a Visual J++ project
  1. Open or create a Java project.
  2. From the Tools menu, select Java Type Library Wizard.
  3. A dialog box appears, listing all the installed controls.
  4. Click to select the check box next to Microsoft BPC Video Server and Control Module.
  5. Click OK.

    The Java Type Library Wizard generates class files for the Video control.

  6. Add the Video control's classes to your Java files using the import keyword. For example, the following line imports all of the Video control's classes into a file's namespace:
    import vidsvr.*;

Once the Video control has been added to your project, you can create instances of Video control objects, access the Video control's methods, properties, and events and add the Video control to user interfaces.


Setting an Input Device

In order to display a video stream, your application must first set an input device or source for that stream. Your application does this by setting the BPCVid.Input property of the Video control equal to one of the available devices in the BPCDevices collection.

There are many different types of input devices. Your application must ensure that any device it selects as an input device supports the operations that it is trying to perform. To do so, your application can use properties of the form Has Xxxx, which indicate whether the current device supports the property Xxxx.

For example, the BPCDeviceBase.HasChannel indicates whether the device supports channels and can be tuned by calling BPCDeviceBase.Channel. The HasChannel property of a television tuner card is True.

If there are multiple tuners available on a broadcast client, your application can use the BPCDeviceBase.ChannelAvailable method to determine whether a device can tune to the specified channel.

Once your application has selected a device that supports the intended video stream from BPCDevices, your application can set that device as the input device. This process is illustrated in the following example:

'Search the collection for a device that
'supports channels. When one is found, set the
'that device as the input device.

For Each Device In vid.Devices
  If Device.HasChannel Then
    vid.Input = Device
    Exit For
  End If
Next


Setting an Output Device

You can also use the Video control to send video streams to an output device. For example, your application can record a television broadcast by setting a tuner card as the input device and a VCR as the output device.

Note Broadcast Architecture does not support functionality to enable infrared (IR) frequency transmission, such as might be used to emulate a remote control signal and control consumer electronics. Thus, although you can set a VCR or other output device to receive a video stream, the user still has to turn on the VCR and start recording manually.

Setting an output device is similar to setting an input device, but instead of using the BPCVid.Input property your application uses the BPCVid.Output property.

The following example searches the Devices collection for a device that supports output. When one is found, the example sets that device as the output device.

For Each Device In vid.Devices
  If Device.IsOutput Then
    vid.Output = Device
    Exit For
  End If
Next


Setting an Input Channel

Once you have set an input device for the Video control that supports channels, as described in Setting an Input Device, you can use the BPCDeviceBase.Channel property to set the device to the appropriate channel.

However, if multiple tuning spaces are defined on a broadcast client, as happens when there are multiple tuner cards installed, a particular device might not be able to tune to the specified channel. You can check whether a device supports a channel by using the BPCDeviceBase.ChannelAvailable method.

The following example loops through the BPCDevices collection, searching for a device that supports the specified channel. If such a device is found, the script sets that device as the input device and sets the device's Channel property.

Dim MyChannel = 12

For Each Device In vid.Devices
  If vid.Input.HasChannel Then
    If Device.ChannelAvailable(MyChannel)
      vid.Input = Device
      vid.Input.Channel = MyChannel
      Exit For
    End If
  End If
Next


Suspending the Video Server

You can use the BPCSuspend object to suspend background data capture and cause the video server to release its devices for use by other applications.

To do this you create an instance of BPCSuspend and call its DeviceRelease method. If the video server successfully releases all devices the method returns a valid BPCSuspended object. Otherwise, it returns Nothing. If Nothing is returned, it means that the video server was unable to release some devices because they are currently being used by client video applications.

Your application should handle the case where DeviceRelease returns Nothing as it would a device busy or device open type of failure. Your application can wait and try again, or signal the user to shut down video applications.

When your application is done using the devices, it should destroy the BPCSuspended object. This notifies the video server that it can resume using the devices and return to background data capture.

'Note: for the following object creation to work,
'you must add the Vid.ocx component into your project.
'For more information, see Adding the Video Control to an Application
Dim susp As BPCSuspend
Set susp = New BPCSuspend
Dim suspended As BPCSuspended

'Attempt to suspend the video server
susp.DeviceRelease 0, suspended

'Test whether the video server was suspended
If (suspended Is Nothing) Then
  'Handle the case where devices cannot be released
Else
  'Use the devices
End If

'Release suspended to enable the video server to use the devices
Set suspended = Nothing

Note If you are developing applications using C/C++, you can use the wrapper class implemented in Bpcsusp.h to provide suspend functionality.


Tuning to Receive VBI Data

Broadcast Architecture supports receiving data transmitted in the vertical blanking interval (VBI) that exists between successive scans of analog television images. Examples of types of data transmitted over the VBI are enhancement files and updates to television listings.

In order to receive VBI data, the television tuner must be tuned to that channel. In the case where the user is watching television on the same channel on which VBI data is being transmitted, the tuner is already set to the necessary channel. However, if the user is not watching television, you must programmatically set the tuner to the appropriate channel in order to receive the VBI data.

You can do this by using the BPCVBIControl to silently tune the television tuner to the appropriate channel. Using this control does not start Microsoft® WebTV® for Windows®, nor does it display video on the client. For example, you can use BPCVBIControl to tune to a channel during the middle of the night and receive updated television listings.

However, if an application is already using the tuner, for example if the user is watching television, the BPCVBIControl returns an error when you attempt to tune to a different channel. The user watching video is always higher priority than VBI data acquisition.

In this manner, the BPCVBIControl is disabled while any application is using video. Any tuners not used by the video application will stay tuned to the last channel a VBI control requested. If an application needs to tune to a VBI transmission while another application is using video, it must create a new instance of the Video control in order to access the tuner.

In order to tune the tuner to the VBI data channel, you must create an instance of BPCVBIControl and call the VBITune method. When your application no longer needs to receive VBI data on that channel it should release the BPCVBIControl object. This causes the tuner to receive VBI data on the default channel, if any, defined in the registry. This enables applications such as EPG data loaders to run in the background and acquire their data.

This is demonstrated in the following code:

Dim vbictrl As BPCVBIControl
Set vbictrl = New BPCVBIControl

'Set the tuner to receive VBI data on channel 27
vbictrl.VBITune 0, 2, 27, AMTUNER_SUBCHAN_DEFAULT, _
                                AMTUNER_SUBCHAN_DEFAULT

'Code to receive and process the VBI data.
'Your application can use the VBI Client Interface
'to retrieve data from the VBI of a television signal.
'For more information on this client interface, see the
'Broadcast Architecture Device-Driver Kit (DDK).

'Release the tuner to receive VBI data using the default channel
'specified in the system registry.
Set vbictrl = Nothing


Reinitializing the Filter Graph

Broadcast clients utilize DirectShow filters to process data streams in order to receive, decode and display audio and video. The filters are coordinated together in a filter graph. The video server passes information from this filter graph to video clients such as the Video control and applications that utilize the Video control.

If your application changes the hardware configuration, such as a setup application that configures a newly installed device, it may need to reinitialize the filter graph. The Video control provides a method, BPCVid.ReInit, which enables your application to request that the filter graph be stopped and recreated.

Because several applications may be relying on data from the filter graph when a video client requests that the filter graph be reinitialized, the video server coordinates the client applications to ensure that all are ready for the reinitialization. The video server does this by firing BPCVid.StateChange events to its clients, specifying changes in the filter graph initialization status.

For more detailed information about this process, see the BPCVid.ReInit reference topic.


Handling Power Management Events

Systems that implement advanced power management or the Advanced Configuration and Power Interface (ACPI) cause Windows 98 to request that the video server and controls suspend operation when the system goes to sleep. Your application should handle the Video control's power management events so it does not attempt to access the Video control or devices while they are unavailable.

When the video server receives a suspend request from the power management system it releases all devices and destroys the filter graph. Each instance of the Video control sends a BPCVid.Power event, specifying PBT_APMQUERYSUSPEND. Applications should not call the Video control or devices until they receive one of the following values in a subsequent Power event: PBT_APMQUERYSUSPENDFAILED, PBT_APMRESUMEAUTOMATIC, or PBT_APMRESUMESUSPEND. At this time, your application can resume use of the Video control and server. Because the filter graph was rebuilt, your application must reenumerate devices and refresh any device information it had stored.

If the value returned in the Power event is PBT_APMQUERYSUSPENDFAILED the system did not suspend, because another application refused the suspend request.


Video Control Reference

The following sections document the programmatic interfaces of the Microsoft® ActiveX® control for video (the Video control, Vid.ocx) and the Video Access server, Vidsvr.exe. These reference topics assume use by developers in the Microsoft® Visual Basic® development system and Microsoft® Visual Basic® Scripting Edition (VBScript) scripting language. Therefore, only Visual Basic language syntax is shown.

The following objects are provided by the MSBPCVideo object library, Vid.ocx.

Object | Description
BPCVid | The Video control.
BPCDevices | A collection of all available devices on the user's computer.
BPCDeviceBase | A device.
BPCSuspend | Object that can be used to suspend the video server and get it to release all devices.
BPCSuspended | Object that indicates whether the video server is suspended.
BPCVBIControl | Object that sets or retrieves the channel and tuning space over which the tuner receives the VBI signal.

Note that the Video control contains several reserved classes. For more information on these, see Reserved Classes in the Video Control.


Reserved Classes in the Video Control

The Video control contains several classes, listed following, that are not supported and that are reserved for future use.

BPCPurchase | BPCHistoryItemsCollection | BPCMessage
BPCEmailMessage | BPCEmailMessageCollection |


Object References

In the object reference topics, the syntax placeholder object refers to an object expression that evaluates to one of the classes specified.

The Input and Output properties of the Video control are each assigned DeviceBase objects when setting the properties' values. You can specify the properties of a DeviceBase object in either property with the following syntax:

Vid1.Devices(index).property

where Vid1, index, and property are placeholders respectively for the:

  • Specific Video control.
  • Index to the specific DeviceBase object in the Devices collection.
  • Property you want to use.

You can also specify DeviceBase object properties after you assign them to the Input or Output properties of the Video control. These are also valid object expressions that reference a property of a DeviceBase object:

Vid1.Input.property
Vid1.Output.property

where Vid1 and property are the respective placeholders for the specific Video control you are using and the property to set of the associated DeviceBase object.


Visual Basic Extender Object

Because the Video control is an ActiveX control, it cannot exist outside of a container application. Examples of containers are Visual Basic forms, application windows, and HTML pages displayed by a Web browser.

When you use an ActiveX control, such as the Video control, in a Visual Basic application, the Visual Basic environment extends the control's functionality using an Extender object.

The Extender object enables programmers to easily access and manipulate a control's interaction with the container. It also provides standard container functionality, such as sending an event when a user clicks on the control and setting whether the control is visible.

The Extender object is part of the Visual Basic container, not the control. The Visual Basic container, however, exposes the properties, methods, and events of the Extender object as if they were part of the control. Some Extender object properties are standard; others are specific to certain containers.

The following tables list and describe the Extender object and Visual Basic–specific properties, methods, and events. The properties are as follows.

Property | Description
Container | Read only object that represents the visual container of the control. Returns or sets the container of a control on a Form.
DragIcon | Picture that specifies the icon to use when the control is dragged.
DragMode | Integer that specifies if the control automatically drags, or if the application using the control must call the Drag method.
Enabled | Boolean value that specifies whether the control is enabled.
Height | Integer that specifies the height of the control in the container's scale units.
HelpContextID | Integer that specifies the context identifier to use when the F1 key is pressed and the control has the focus.
Index | Integer that specifies the position in a control array this instance of the control occupies.
Left | Integer that specifies the position of the left edge of the control relative to the left edge of the container, specified in the container's scale units.
Name | String that contains the user-defined name of the control.
Parent | Read only object that represents the container of the control, such as a form in Visual Basic. Returns the form, object, or collection that contains a control or another object or collection. Use the Parent property to access the properties, methods, or controls of an object's parent.
TabIndex | Integer that specifies the position of the control in the tab order of the controls in the container.
TabStop | Boolean value that specifies if the tab stops on the control.
Tag | String that contains a user-defined value.
ToolTipText | String that contains the text to be displayed when the cursor hovers above the control for more than a second.
Top | Integer that specifies the position of the upper edge of the control relative to the upper edge of the container, specified in the container's scale units.
Visible | Boolean value that specifies whether the control is visible.
WhatThisHelpID | Context identifier to use when the "What's This" pop-up is used to provide information on the control.
Width | Width of the control in the container's scale units.

Note The Container and Parent properties are similar. However, Parent is part of the standard set of Extender object properties, and Container is part of an additional set of properties that are not available for all containers.

The Extender object methods and Visual Basic–specific extender methods are listed following.

Method | Description
Drag | Begins, ends, or cancels an operation in which the control is dragged.
ShowWhatsThis | Displays a selected topic in a Help file using the "What's This" pop-up provided by Help.
Move | Moves the position of the control.
ZOrder | Places the control at the front or back of the z-order within its graphical level.
SetFocus | Sets the focus to the control.

The Extender object events and Visual Basic–specific extender events are listed following.

Event | Description
DragDrop | Occurs when another control on the form is dropped on this control.
LostFocus | Occurs when the control loses focus.
DragOver | Occurs when another control on the form is dragged over this control.
GotFocus | Occurs when the control gets focus

To locate more information about the methods, properties, and events of the Extender object, see Further Information on Streaming Video Services for the Client.


Registry Entries for the Video Control

The Video control and Video Server use the following registry keys to store information. These values are stored in subkeys of this registry key: HKLM\Software\Microsoft\TV Services\

Name | Data Type | Description
"AudioPin" | String | Specifies that the video server should use a different pin name than the default. For example "CD/Aux".
"VBITS" | REG_DWORD | Default VBI tuning space.
"VBIChan" | REG_DWORD | Default VBI channel.
TuningSpaces\"OverScanPct" | DWORD | The overscan percentage.

The tuning space information for each device is stored in the registry under a key named HKLM\Software\Microsoft\TV Services\TuningSpaces\<N>\, where <N> is the tuning space number.

Note Tuning space numbers are assigned sequentially as devices are installed. Because of this, the tuning space number for a device may change between installations. To get the tuning space number associated with a particular tuning space, call ITelevisionServices::TuningSpaceNumberFromName.

Name | Data Type | Description
"AMFClass" | String | GUID representing the Microsoft® DirectShow™ filter class for the devices that can tune this tuning space. A device sets either this key or AMFCategory. For more information see the note at the end of this table.
"Description" | String | Description of the tuning space.
"Devices" | String | This key is not currently in use.
"InputType" | Binary | For analog tuners, this is the value set for the tuner input type. In other words, the value passed to IAMTVTuner::put_InputType.
"Loader" | String | Specifies the loader that retrieves programming guide information for this tuning space. This value points to the appropriate loader in the loaders section of the registry.
"MaxChannel" | Binary | The highest channel number supported by this tuning space.
"MediaType" | Binary | The configure auxpin for the appropriate video type.
"MinChannel" | Binary | The lowest channel number supported by this tuning space.
"Name" | String | The name of the tuning space.
"AMFCategory" | String | GUID of the auxpin DirectShow Filter category for devices which can tune to this tuning space. A device sets either this key or AMFClass. For more information see the note at the end of this table.
"PinName" | String | Name of the pin on the crossbar.
"PinType" | String | Type of pin on the crossbar.

Note AMFCategory and AMFClass are mutually exclusive. If the tuner device is an old-style ring-3 filter that cannot be created from a device enumerator, it uses AMFClass. If the tuner device is a new ring-3 filter that can be enumerated from the DirectShow device enumerator or if it is a ring-0 Windows Driver Model (WDM)-proxied driver, it uses AMFCategory.

To locate additional information about DirectShow, IAMTVTuner and WDM, see Further General Information.


BPCVid

The BPCVid class defines the Microsoft® ActiveX® object which provides streaming video functionality. It is designed to be forward-compatible with the Microsoft® DirectShow™ version 1.0 ActiveX control.

Note Version 1.0 of Broadcast Architecture is not compatible with the DirectShow 1.0 ActiveX control.

For more information, see the following topics:

  • BPCVid Properties
  • BPCVid Methods
  • BPCVid Events

Note that BPCVid contains several reserved properties, methods, and events. For more information on these, see Reserved Properties, Methods, and Events in BPCVid.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


Reserved Properties, Methods, and Events in BPCVid

The BPCVid interface contains several properties, methods, and events, listed following, that are not supported and that are reserved for future use.

CurrentState | StartTime | StopTime
Login | Logout | Run
Stop | Pause | BlackedOut
CAFail | CAFault | CannotPurchase
CardInvalid | CardMissing | CASuccess
ColdStart | CopyCard | CostExceeded
EPGFilterChanged | HandlePurchaseOffer | NewEmail
NoSubscriber | NotReady | OSDRequest
PasswordCleared | RatingExceeded | Ready
Retry | RevokeEvent | SignalLost
TapingControlChanged | TuningChanged | WrongCard


BPCVid Properties

The BPCVid object has the following properties:

Property | Description
Balance | The current audio balance between left and right speakers.
ClosedCaption | A value that indicates whether closed captioning is turned on.
ColorKey | The color to use for color keying.
Debug | A value that indicates whether debugging information is displayed.
DeviceCount | The number of devices currently available.
Devices | A collection of the devices currently available on the user's computer.
DisplayMode | A value that indicates whether the current position in the video is displayed in number of frames displayed or time elapsed.
Font | The font used in the title window.
HWnd | A handle to the window hosting the Video control.
ImageSourceHeight | The authored height of the source image. This value does not change if the user resizes the control.
ImageSourceWidth | The authored width of the source image. This value does not change if the user resizes the control.
Input | The input device.
LocaleID | The locale identifier. This property supports the country codes of Microsoft® Windows® operating systems and determines which control character set to display, which date and currency formats to use, and so on.
MovieWindowSetting | A value that sizes the window displaying the images associated with a multimedia stream.
Output | The output device.
Power | A value that indicates whether the device is currently turned on.
PrerollTime | A value that indicates the amount of time to allow a tape to roll before starting to record.
Priority | The priority of this application. This value is used to resolve device conflicts.
VideoOn | A value that indicates whether video is displayed by the control.
Volume | The current audio volume level.

The following properties of BPCVid are passed to the Visual Basic Extender object. To locate more information about Extender properties, see Further Information on Streaming Video Services for the Client.

Property | Description
Container | Object that represents the visual container of the control.
DragIcon | Picture that specifies the icon to use when the control is dragged.
DragMode | Integer that specifies if the control automatically drags, or if the application using the control must call the Drag method.
Height | Integer that specifies the height of the control in the container's scale units.
HelpContextID | Integer that specifies the context identifier to use when the F1 key is pressed when the control has the focus.
Index | Integer that specifies the position in a control array this instance of the control occupies.
Left | Integer that specifies the position of the left edge of the control relative to the left edge of the container, specified in the container's scale units.
Name | String that contains the user-defined name of the control.
Parent | Object that represents the container of the control, such as a form in Visual Basic.
TabIndex | Integer that specifies the position of the control in the tab order of the controls in the container.
TabStop | Boolean value that specifies if the tab stops on the control.
Tag | String that contains a user-defined value.
ToolTipText | String that contains the text to be displayed when the cursor hovers above the control from more than a second.
Top | Integer that specifies the position of the upper edge of the control relative to the upper edge of the container, specified in the container's scale units.
Visible | Boolean value that specifies whether the control is visible.
WhatThisHelpID | Context identifier to use when the "What's This" pop-up is used to provide information on the control.
Width | Width of the control in the container's scale units.


BPCVid.Balance

The Balance property sets or retrieves a value that controls the multimedia stream's audio balance between left and right speakers.

Syntax

object.Balance [ = lBalance]

Parts

object
Object expression that resolves to a BPCVid or BPCDeviceBase object.
lBalance
A Long that specifies the balance value. The number must be from –10,000 through +10,000. The default value is zero.

Remarks

The default value of zero indicates equal balance between left and right.

This property of the BPCVid object is passed to the current input device. You should set it using the BPCVid object instead of the BPCDeviceBase object. Otherwise, the Video control is not updated, and future behavior is undefined.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.Volume


BPCVid.ClosedCaption

The ClosedCaption property indicates whether closed captioning is turned on.

Syntax

object.ClosedCaption [ = bCC ]

Parts

object
Object expression that resolves to a BPCVid object.
bCC
Boolean expression that is True if closed captioning is enabled and False if it is disabled.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.ColorKey

The ColorKey property specifies the color to use for color keying. This property is not fully implemented. Currently, the ColorKey value is always set to magenta (0x00FF00FF).

Syntax

object.ColorKey [ = lColorVal ]

Parts

object
Object expression that resolves to a BPCVid object.
lColorVal
A Long or constant that determines the color to use for color keying. The following table lists and describes the possible values for the lColorVal parameter.
Value | Meaning
Normal RGB colors | Colors specified by using the Color palette or programmatically by using the RGB or QBColor functions. For more information, see Further Information on Streaming Video Services for the Client.
System default colors | Colors specified by system color constants listed in the object library in the Visual Basic Object Browser. As needed, Windows substitutes the user's color choices for default colors as specified in the Control Panel settings.

Remarks

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a number in this range equals zero; the lower three bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (&HFF). If the high byte isn't zero, Visual Basic uses the system colors, as defined in the user's Control Panel settings and by constants listed in the object library in the Object Browser.

This property is not stored locally in the BPCVid object; instead, it is passed to the restricted property in the corresponding BPCDevices object. You set this property, however, using BPCVid. This ensures that the Video control is properly updated.


BPCVid.Debug

The Debug property specifies whether debugging information is displayed on-screen in the Video control.

Syntax

object.Debug [ = bDebug ]

Parts

object
Object expression that resolves to a BPCVid object.
bDebug
Boolean expression that is True if debugging information is shown on-screen in the Video control and False if it is not.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.DeviceCount

The DeviceCount property returns the number of objects in the BPCDevices collection. This property is read-only.

Syntax

[ lCount = ] object.DeviceCount

Parts

object
Object expression that resolves to a BPCVid object.
lCount
Long that specifies the number of objects in the BPCDevices collection.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDevices, BPCVid.Devices


BPCVid.Devices

The Devices property is a read-only property that returns a BPCDevices collection of the available devices.

Syntax

[ oDevices = ] object.Devices

Parts

object
Object expression that resolves to a BPCVid object.
oDevices
Object expression that resolves to a BPCDevices object.

Remarks

You not create an instance of a BPCDevices object directly, instead obtain the BPCDevices collection by using BPCVid.Devices.

In the current version of Broadcast Architecture, only analog television tuner cards are listed in the BPCDevices collection. Future versions will list other input devices, such as a file playback device and output devices.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDevices, BPCVid.DeviceCount

Example

The following example retrieves the collection of available devices and stores it in the object variable devices.

'Declare an object variable to receive the collection.
Dim devices As BPCDevices

'Obtain the collection from the Video control.
Set devices = vid.Devices


BPCVid.DisplayMode

The DisplayMode property specifies the current position in the video is displayed in number of frames displayed or time elapsed.

Syntax

object.DisplayMode [ = iDisplayMode ]

Parts

object
Object expression that resolves to a BPCVid object.
iDisplayMode
Integer or constant to specify the display mode, as described in the following table.
Value | Meaning
modeFrames | The current position is measured in frames.
modeTime | The current position is measured in time.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.Font

The Font property specifies the font used in the title bar of the Video control.

Syntax

object.Font [ = Font ]

Parts

object
Object expression that resolves to a BPCVid object.
Font
An IFontDisp interface that specifies the font. To locate more information about IFontDisp, see Further Information on Streaming Video Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.HWnd

The HWnd property contains a reference to the window hosting the Video control. This property is read-only.

Syntax

[Hwnd = ] object.HWnd

Parts

object
Object expression that resolves to a BPCVid object.
Hwnd
An OLE_HANDLE that receives the handle of the host window.

Remarks

Windows identifies each form and control in an application by assigning it a handle, or HWnd. The HWnd property is used with Microsoft® Win32® API calls, most often as a parameter.

Because Windows may change the value of HWnd, your application must not change the HWnd value or store it in a variable. To locate more information on using HWnd, see Further Information on Streaming Video Services for the Client.

This property is not stored locally in the BPCVid object; instead, it is passed to the restricted property in the corresponding BPCDevices object. You set this property, however, using BPCVid. This ensures that the Video control is properly updated.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.ImageSourceHeight

The ImageSourceHeight property contains the height of the source image. This property is read-only.

Syntax

[ lHeight = ] object.ImageSourceHeight

Parts

object
Object expression that resolves to a BPCVid or BPCDeviceBase object.
lHeight
Long that receives the height of the source image, in pixels.

Remarks

This is a read-only property. The value of this property is independent of the projected image size, which is determined by the BPCVid.MovieWindowSetting property.

This property of the BPCVid object is passed to the current input device. You should set it using the BPCVid object instead of the BPCDeviceBase object. Otherwise, the Video control is not updated, and future behavior is undefined.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.ImageSourceWidth, BPCVid.MovieWindowSetting


BPCVid.ImageSourceWidth

The ImageSourceWidth property contains the authored width of the source image. This property is read-only.

Syntax

[ lWidth = ] object.ImageSourceWidth

Parts

object
Object expression that resolves to a BPCVid or BPCDeviceBase object.
lWidth
Long that receives the width of the source image.

Remarks

This is a read-only property. The value of this property is independent of the projected image size, which is determined by the BPCVid.MovieWindowSetting property.

This property of the BPCVid object is passed to the current input device. You should set it using the BPCVid object instead of the BPCDeviceBase object. Otherwise, the Video control is not updated, and future behavior is undefined.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.ImageSourceHeight, BPCVid.MovieWindowSetting


BPCVid.Input

The Input property sets or returns information on the device supplying input to the Video control.

Syntax

object.Input [ = oDevice]

Parts

object
Object expression that resolves to a BPCVid object.
oDevice
Object expression that resolves to a BPCDeviceBase object.

Remarks

Once you assign a BPCDeviceBase object to the Input property, the media stream from the input device is displayed by the control. To suppress the display, set the BPCVid.VideoOn property to False. Alternatively, you can set the Visible property to False to hide the entire window. The Visible property is implemented by the Extender object; for more information, see Visual Basic Extender Object.

This property is not stored locally in the BPCVid object; instead, it is passed to the restricted property in the corresponding BPCDevices object. You set this property, however, using BPCVid. This ensures that the Video control is properly updated.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase, BPCVid.Output, BPCVid.VideoOn


BPCVid.LocaleID

The LocaleID property sets or returns the identifier for the current locale.

Syntax

object.LocaleID [ = lLocale]

Parts

object
Object expression that resolves to a BPCVid object.
lLocale
Long that specifies the locale identifier.

Remarks

This property supports the country codes of the Windows operating systems. The locale determines which control character set to display, which formats to use for dates and currency, and so on. To locate more information on locale identifiers, see Further Information on Streaming Video Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.MovieWindowSetting

The MovieWindowSetting property sets or returns a value that sizes the window displaying the images associated with a multimedia stream. This property is not fully implemented. The size is always the specified window size adjusted down to the nearest 4/3 aspect ratio.

Syntax

object.MovieWindowSetting [ = iSetting ]

Parts

object
Object expression that resolves to a BPCVid object.
iSetting
Integer or constant to specify the window size, as described in the following table.
Value | Meaning
movieDefaultSize | Uses the default authored size.
movieDoubleSize | Increases the image to twice the authored size.
movieFullScreen | Projects the image onto a full-screen control window.
movieHalfSize | Sizes the image to fit half the screen.
movieMaximizeSize | Projects the image onto a maximized control window.
moviePermitResizeNoRestrict | Enables the user to resize the image without restriction.
moviePermitResizeWithAspect | Enables the user to resize the image, while maintaining a 4/3 aspect ratio.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.ImageSourceHeight, BPCVid.ImageSourceWidth


BPCVid.Output

The Output property sets or returns the device to which the Video control sends output. This is not supported in the current version of Broadcast Architecture.

Syntax

object.Output[ = oDevice]

Parts

object
Object expression that resolves to a BPCVid object.
oDevice
Object expression that resolves to a BPCDeviceBase object.

Remarks

When you set this property to a valid output device, the media stream coming from the Input property is:

  • Sent to this device.
  • Displayed in the control window.

To suppress this output, set this property to the value Nothing or to the BPCDeviceBase object named Null in the BPCDevices collection.

This property is not stored locally in the BPCVid object; instead, it is passed to the restricted property in the corresponding BPCDevices object. You set this property, however, using BPCVid. This ensures that the Video control is properly updated.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.Input, BPCDeviceBase


BPCVid.Power

The Power property sets or returns a value that controls whether an external device has power on or not.

Syntax

object.Power [ = bState ]

Parts

object
Object expression that resolves to a BPCVid or BPCDeviceBase object.
bState
Boolean that is True if the device is on and False if it is off.

Remarks

This property of the BPCVid object is passed to the current input device. You should set it using the BPCVid object instead of the BPCDeviceBase object. Otherwise, the Video control is not updated, and future behavior is undefined.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.PrerollTime

The PrerollTime property specifies the time, in seconds, that a tape or other recording device should run before the multimedia stream starts.

Syntax

object.PrerollTime [ = dTime ]

Parts

object
Object expression that resolves to a BPCVid or BPCDeviceBase object.
dTime
Double that specifies the number of seconds the tape should run before the stream starts.

Remarks

This property of the BPCVid object is passed to the current input device. You should set it using the BPCVid object instead of the BPCDeviceBase object. Otherwise, the Video control is not updated, and future behavior is undefined.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.Priority

The Priority property sets or returns a value that defines the priority of an instance of the Video control in the system.

Syntax

object.Priority [ = lPriority]

Parts

object
Object expression that resolves to a BPCVid object.
lPriority
A Long that specifies the priority of the device.

Remarks

Use this property to surrender or require control of a resource. To relinquish any claim to a resource, set the BPCVid.Input or BPCVid.Output property to Nothing.

This property is used to resolve device conflicts. When two control instances are in contention for a device, control is given to the application with higher priority. If both instances have equal priority, the instance that currently has control of the device retains control.

This property is not stored locally in the BPCVid object; instead, it is passed to the restricted property in the corresponding BPCDevices object. You set this property, however, using BPCVid. This ensures that the Video control is properly updated.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.GotControl, BPCVid.LostControl


BPCVid.VideoOn

The VideoOn property sets or returns a value indicating whether video is displayed by the control.

Syntax

object.VideoOn [ = bState ]

Parts

object
Object expression that resolves to a BPCVid object.
bState
Boolean expression that is True if multimedia data from the device indicated by the BPCVid.Input property is displayed by the Video control, and False if it is not displayed. True is the default.

Remarks

You can use this property to turn off video when your application needs to pass the contents of the current input device to the output device without displaying anything on-screen. For example, you can use VideoOn if your application is scheduling a recording in the background.

To route media data from the device indicated by Input to the device indicated by the BPCVid.Output property without displaying the media data, set VideoOn to False.

Setting VideoOn to False mutes audio output in addition to turning off video. To play audio-only content, set VideoOn to True and set the BPCDevices.Height and BPCDevices.Width properties to zero.

This property is not stored locally in the BPCVid object; instead, it is passed to the restricted property in the corresponding BPCDevices object. You set this property, however, using BPCVid. This ensures that the Video control is properly updated.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.Input


BPCVid.Volume

The Volume property sets or retrieves a value that controls the loudness of the multimedia stream.

Syntax

object.Volume [ = lLoudness ]

Parts

object
Object expression that resolves to a BPCVid or BPCDeviceBase object.
lLoudness
A Long that specifies the audio volume. The possible values range from –10,000 to 0. The default value, zero, represents full volume. The value –10,000 represents minimum volume.

Remarks

This property of the BPCVid object is passed to the current input device. You should set it using the BPCVid object instead of the BPCDeviceBase object. Otherwise, the Video control is not updated, and future behavior is undefined.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.Balance


BPCVid Methods

The following methods are implemented in the BPCVid object.

Method | Description
AboutBox | Displays version and copyright information about the Video control.
AutoScan | Returns the signal strength of the channel.
Close | Sets all inputs and outputs to NULL.
MinMaxChannel | Returns the lowest and highest channel numbers supported by the specified tuning space.
Refresh | Forces an update to the current window size, position, and visibility.
ReInit | Requests that the video server reinitialize the filter graph.
TSDeviceCount | Returns the number of devices available for a given tuning space.
Tune | Selects an input device based on the tuning space parameter, sets the current input device to the selected device, and tunes the current input device to the specified channel.

The following methods are implemented in the BPCVid object as wrappers for the equivalent methods in the Visual Basic Extender object.

Method | Description
Drag | Begins, ends, or cancels an operation in which the control is dragged.
ShowWhatsThis | Displays a selected topic in a Help file using the "What's This" pop-up provided by Help.
Move | Moves the position of the control.
ZOrder | Places the control at the front or back of the z-order within its graphic level.
SetFocus | Set the focus to the control.


BPCVid.AboutBox

The AboutBox method displays version and copyright information about the control.

Syntax

object.AboutBox()

Parameters

object
Object expression that resolves to a BPCVid object.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.AutoScan

The AutoScan method returns the signal strength of the current channel.

Syntax

[lSignalStr = ] object.AutoScan()

Parameters

object
Object expression that resolves to a BPCVid object.
lSignalStr
Long indicating the signal strength. The value returned depends on the device. If a channel is present but the device does not support signal strength measurements, this method returns 1.

Remarks

This method is implemented in the BPCVid object as a wrapper for the equivalent restricted method in the BPCDevices object. Applications should access this method through BPCVid.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.Close

The Close method sets all inputs and outputs to NULL.

Syntax

object.Close()

Parameters

object
Object expression that resolves to a BPCVid object.

Remarks

This method does not affect device tuning.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.MinMaxChannel

The MinMaxChannel method returns the lowest and highest channel numbers supported by the device corresponding to the specified tuning space.

Syntax

object.MinMaxChannel( lTuningSpace, lChannelMin, lChannelMax )

Parameters

object
Object expression that resolves to a BPCVid object.
lTuningSpace
Long that specifies the tuning space identifier of the device. If this parameter is not a registered tuning space, the method causes an incorrect parameter error.
lChannelMin
Long that receives the lowest channel number the device supports.
lChannelMax
Long that receives the highest channel number the device supports.

Remarks

For version 1.0 of Broadcast Architecture, this method only supports television tuners. If you call MinMaxChannel and specified another type of tuning space, such as a satellite tuner card, the version 1.0 implementation of this method causes an error.

The minimum and maximum channels returned by this method correspond to the values returned by the IAMTVTuner::ChannelsMinMax method of DirectShow. To locate more information about this method, see Further Information on Streaming Video Services for the Client.

This method is implemented in the BPCVid object as a wrapper for the equivalent restricted method in the BPCDevices object. Applications should access this method through BPCVid.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase.MinMaxChannel

Examples

The following example retrieves the minimum and maximum channel supported by the tuning space identified by the number 3. These values are stored in the variables min and max.

Dim min As Long
Dim max As Long
vid.MinMaxChannel 3, min, max


BPCVid.Refresh

The Refresh method forces an update to the current window size, position, and visibility.

Syntax

object.Refresh()

Parameters

object
Object expression that resolves to a BPCVid or BPCDeviceBase object.

Remarks

The following method is implemented in the BPCVid object as a wrapper for the equivalent method in the BPCDeviceBase object. You should call this method from the BPCVid object instead of the BPCDeviceBase object. Otherwise, the Video control may not be properly updated, and future behavior is undefined.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.Tune

The Tune method tunes the current input device to the specified channel.

Syntax

object.Tune(lTuningSpace, lChannel, lVideoSubchannel, lAudioSubchannel)

Parameters

object
Object expression that resolves to a BPCVid object.
lTuningSpace
A Long that specifies the tuning space identifier. This identifier is the same value as that specified in the Guide database.
lChannel
A Long that specifies the channel number.
lVideoSubchannel
A Long that specifies the video subchannel.
lAudioSubchannel
A Long that specifies the audio subchannel.

Remarks

You can use either BPCVid.Tune method or BPCVid.Input.Channel property to set the channel displayed by the Video control. If you are simply trying to tune the Video control to a particular channel and do not care which device provides the channel you can use the Tune method. This method automatically sets BPCVid.Input to the appropriate device, as identified by ITuningSpace. However, if it is important that your application set the Input property to a particular device, you can use the BPCVid.Input.Channel syntax.

This method is implemented in the BPCVid object as a wrapper for the equivalent restricted method in the BPCDevices object. Applications should access this method through BPCVid.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid.ReInit

The ReInit method requests that the video server reinitialize the filter graph.

Syntax

object.ReInit()

Parameters

object
Object expression that resolves to a BPCVid object.

Remarks

ReInit is typically called when an application or process changes the hardware configuration in such a way that the filter graph needs to be rebuilt. An example of an application that calls ReInit is a setup application that reconfigures auxiliary video input from composite to s-video.

When you call the ReInit method, the video server sends a BPCVid.StateChange event specifying BPC_STATE_REINIT_REQUEST to each video client. A video client is an application or component that receives a data stream from the filter graph through the video server. Applications that utilize the Video control are video clients.

When a client receives a BPC_STATE_REINIT_REQUEST notification from the video server, the client must release any outstanding references to Vid.ocx objects such as BPCDeviceBase or BPCDevices. The one exception is that your application can retain references to BPCVid objects. If your video client does not release these objects, an error will result when these objects are used after the filter graph is reinitialized.

Note Note that Video controls automatically handle BPC_STATE_REINIT_REQUEST notifications, by releasing references to Vid.ocx objects. Therefore, if you are embedding the Video control in a Web page or application that does not contain any other references to Vid.ocx objects, you do not need to handle BPC_STATE_REINIT_REQUEST notifications.

After all video clients have been notified the filter graph is about to be reinitialized, the video server fires a BPCVid.StateChange event specifying BPC_STATE_REINIT_STARTED. It then destroys and recreates the filter graph. Once the filter graph has been successfully recreated, the video server sends a BPC_STATE_REINIT_COMPLETE notification.

When video clients receive the BPC_STATE_REINIT_COMPLETE notification, they are able to reenumerate and reselect devices. Note that the device list may have changed as a consequence of the reinitialization.

If a video client calls a method that requests an object from the video server during the reinitialization (between receiving the BPC_STATE_REINIT_STARTED and BPC_STATE_REINIT_COMPLETE notifications) the video server blocks the method call until the reinitialization is complete. When the filter graph has been recreated, the video server processes the blocked method calls.

Examples

The following example implements an BPCVid.StateChange event handler that responds to BPC_STATE_REINIT_XXX notifications. This illustrates the functionality you should implement if your application uses the Video control and contains references to other Vid.ocx objects.

Private Sub MyApp_StateChange( lpdDevice As BPCDeviceBase, _
                               oldState As Long, newState As Long)
  Select Case (newState)
  Case(BPC_STATE_REINIT_REQUEST)
    'Release all references to Vid.ocx objects except BPCVid
    '(This example shows how to do this for an
    'application that contains a reference to
    'a BPCDevices member variable, m_devices and
    'a BPCDeviceBase member variable, m_inputdevice)
    Set m_devices = Nothing
    Set m_inputdevice = Nothing

    'Optional - you can set a flag so that other subroutines in the
    'application can check the reinitialization state
    'of the filter graph.
    m_lReinitState = BPC_STATE_REINIT_REQUEST

  Case(BPC_STATE_REINIT_STARTED)
    'Optional - you can set a flag so that other subroutines in the
    'application can check the reinitialization state
    'of the filter graph.
    m_lReinitState = BPC_STATE_REINIT_STARTED

  Case(BPC_STATE_REINIT_COMPLETE)
    'Reenumerate the devices
    Set m_devices = vid.Devices

    'Reset any needed devices.
    '(This example displays resetting the input device.)
    For Each Device In m_devices
      If Device.HasChannel
        Then m_inputdevice = Device
        Exit For
      End If
    Next

    'Optional - you can set a flag so that other subroutines in the
    'application can check the reinitialization state
    'of the filter graph.
    m_lReinitState = BPC_STATE_REINIT_COMPLETE

  'Optional - you can handle cases other than those listed above
  'Case (...)
  Case Else

  End Select
End Sub

You can easily adapt the preceding example into an event handler for a Web page or application that uses the Video control but does not contain references to Vid.ocx objects. Simply remove the BPC_STATE_REINIT_REQUEST case statement. Because the Video control already implements this functionality, handling BPC_STATE_REINIT_REQUEST notifications is not necessary for such an application.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

Reinitializing the Filter Graph, BPCVid.StateChange


BPCVid.TSDeviceCount

The TSDeviceCount method returns the number of devices that support a specified tuning space.

Syntax

[ lCount = ] object.TSDeviceCount(lTuningSpace)

Parameters

object
Object expression that resolves to a BPCVid object.
lTuningSpace
Long that specifies the tuning space identifier. This identifier is the same value as that specified in the Guide database and/or the HKLM\Software\Microsoft\TV Services\Tuning Spaces\ registry key.

For example, the identifier 2 can represent the "Analog Broadcast TV from Antenna" tuning space.

lCount
Long that indicates the number of devices.

Remarks

This method is implemented in the BPCVid object as a wrapper for the equivalent restricted method in the BPCDevices object. Applications should access this method through BPCVid.

Examples

In the following example, 3 is the identifier for the "Analog Cable TV" tuning space and vid is an instance of the Video control. The call to TSDeviceCount method counts the number of devices that support the analog cable tuning space, such as an ATI All-in-Wonder tuner card. The number of devices is then stored in the variable numDevices.

Dim numDevices As Long
numDevices = vid.TSDeviceCount(3)

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCVid Events

The DBPCVidEvents interface is implemented on the BPCVid object and is used to send event notifications to the application or container hosting the Video control.

The following events are sent by the Video control.

Event | Description
Click | A user clicked in the control.
DblClick | A user double-clicked in the control.
Error | An error has occurred in the control or in the control's input or output device.
ErrorMessage | An error has occurred. This event is not implemented.
GotControl | The control receiving this notification has requested a device and now has the highest priority for that device.
KeyDown | The user pushed a key down.
KeyPress | The user pressed a key.
KeyUp | The user released a key.
LostControl | An application with higher priority than the current application requested the control's input or output device. The instance of the Video control receiving this event must release the device.
MouseDown | The user clicked a mouse button over the Video control.
MouseMove | The user moved the mouse over the Video control.
MouseUp | The user has released a mouse button over the Video control.
Power | The video access server received a Windows power-management event.
StateChange | A device's state changed.


BPCVid.Click

The Click event occurs when the user clicks the Video control with the left or right mouse button.

Syntax

Private Sub object_Click

Parameters

object
Object expression that resolves to a BPCVid object.

Remarks

To distinguish between the left, right, and middle mouse buttons, use the events.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.DblClick, BPCVid.MouseDown, BPCVid.MouseUp


BPCVid.DblClick

The DblClick event occurs when the user double-clicks the Video control.

Syntax

Private Sub object_DblClick

Parameters

object
Object expression that resolves to a BPCVid object.

Remarks

To distinguish between the left, right, and middle mouse buttons, use the BPCVid.MouseDown and BPCVid.MouseUp events.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.Click, BPCVid.MouseDown, BPCVid.MouseUp


BPCVid.Error

The Error event occurs when an asynchronous error occurs in the Video control or the control's input or output device.

Syntax

Private Sub object_Error(Number As Integer, _
 ByVal Description As String, ByVal SCode As Long, _
 ByVal Source As String, HelpFile As String, _
 HelpContext As Long, CancelDisplay As Boolean)

Parameters

object
Object expression that resolves to a BPCVid object.
Number
Integer that contains the low WORD of the SCode parameter.
Description
String describing the error that occurred.
SCode
Long that specifies the error code.
Source
String containing the control's name.
HelpFile
String containing the Help file name.
HelpContext
A Long that indicates the Help context.
CancelDisplay
Value that may be set by the client to cancel the default error messages.

Remarks

Broadcast Architecture does not currently generate asynchronous errors.

The Error event occurs when the Video control reports an error during playback. By default, the control displays a message box containing the description string. To avoid displaying this box, set the CancelDisplay parameter of the Error event to False.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.ErrorMessage


BPCVid.ErrorMessage

The ErrorMessage event passes an error message to the container application hosting the Video control. This event is not implemented.

Syntax

Private Sub object_ErrorMessage(iMessage As Long, Text As String)

Parameters

object
Object expression that resolves to a BPCVid object.
iMessage
Long that indicates the error number.
Text
String that describes the error.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.Error


BPCVid.GotControl

The GotControl event notifies an instance of the Video control that the instance has control of a device.

Syntax

Private Sub object_GotControl

Parameters

object
Object expression that resolves to a BPCVid object.

Remarks

This event occurs if the control requests a device that is not currently being used by an application with higher priority. If two devices have the same priority, the current control retains the device.

Your application must wait until it receives a GotControl event before it uses a device. Otherwise, applications currently using the device do not release the device, and unexpected behavior can occur.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.LostControl


BPCVid.KeyDown

The KeyDown event occurs when the user presses a key while the Video control has the focus.

Syntax

Private Sub object_KeyDown(keycode As Integer, shift As Integer)

Parameters

object
Object expression that resolves to a BPCVid object.
keycode
Key code, such as vbKeyF1 (the F1 key) or vbKeyHome (the HOME key). To specify key codes, use the constants in the Visual Basic object library in the Visual Basic Object Browser.
shift
Integer that corresponds to the state of the shift, ctrl, and alt keys at the time of the event. The shift parameter is a bit field with the least-significant bits corresponding to the shift key (bit 0), the ctrl key (bit 1), and the alt key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed. For example, if both ctrl and alt are pressed, the value of shift is 6.

Remarks

To locate more information on the Visual Basic Object Browser, see Further Information on Streaming Video Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.KeyUp, BPCVid.KeyPress


BPCVid.KeyPress

The KeyPress event occurs when the user presses and releases an ANSI key while the Video control has focus.

Syntax

Private Sub object_KeyPress(keyascii As Integer)

Parameters

object
Object expression that resolves to a BPCVid object.
keyascii
Integer that returns a standard numeric ANSI keycode. Changing keyascii to 0 cancels the key stroke so the object is not assigned a character.

Remarks

A KeyPress event can involve any printable keyboard character, the ctrl key combined with a character from the standard alphabet or one of a few special characters, and the enter or backspace key.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.KeyDown, BPCVid.KeyUp


BPCVid.KeyUp

The KeyUp event occurs when the user releases a pressed key while the Video control has the focus.

Syntax

Private Sub object_KeyUp(keycode As Integer, shift As Integer)

Parameters

object
Object expression that resolves to a BPCVid object.
keycode
Key code, such as vbKeyF1 (the F1 key) or vbKeyHome (the HOME key). To specify key codes, use the constants in the Visual Basic object library in the Visual Basic Object Browser.
shift
Integer that corresponds to the state of the shift, ctrl, and alt keys at the time of the event. The shift parameter is a bit field with the least-significant bits corresponding to the shift key (bit 0), the ctrl key (bit 1), and the alt key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed. For example, if both ctrl and alt are pressed, the value of shift is 6.

Remarks

To locate more information on the Visual Basic Object Browser, see Further Information on Streaming Video Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.KeyDown, BPCVid.KeyPress


BPCVid.LostControl

The LostControl event notifies an instance of the Video control that it has lost control of the input device.

Syntax

Private Sub object_LostControl

Parameters

object
Object expression that resolves to a BPCVid object.

Remarks

This event occurs when an application with a higher priority requests the device. Your application must honor this request and immediately release the device. If an application continues to manipulate a device after it has received a LostControl notification, unexpected behavior can occur.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.GotControl


BPCVid.MouseDown

The MouseDown event occurs when the user presses a mouse button while the Video control has focus.

Syntax

Private Sub object_MouseDown(button As Integer, shift As Integer, _
 x As OLE_XPOS_PIXELS, y As OLE_YPOS_PIXELS)

Parameters

object
Object expression that resolves to a BPCVid object.
button
Integer that on return identifies the button pressed to cause the event. The button parameter is a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.
shift
Integer that corresponds to the state of the shift, ctrl, and alt keys at the time of the event. The shift parameter is a bit field with the least-significant bits corresponding to the shift key (bit 0), the ctrl key (bit 1), and the alt key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed. For example, if both ctrl and alt are pressed, the value of shift is 6.
x
Number that on return specifies the x-coordinate of the current mouse pointer location.
y
Number that on return specifies the y-coordinate of the current mouse pointer location.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.MouseMove, BPCVid.MouseUp


BPCVid.MouseMove

The MouseMove event occurs when the user moves the mouse.

Syntax

Private Sub object_MouseMove(button As Integer, shift As Integer, _
 x As OLE_XPOS_PIXELS, y As OLE_YPOS_PIXELS)

Parameters

object
Object expression that resolves to a BPCVid object.
button
Integer that on return identifies the button pressed to cause the event. The button parameter is a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.
shift
Integer that corresponds to the state of the shift, ctrl, and alt keys at the time of the event. The shift parameter is a bit field with the least-significant bits corresponding to the shift key (bit 0), the ctrl key (bit 1), and the alt key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed. For example, if both ctrl and alt are pressed, the value of shift is 6.
x
Number that on return specifies the x-coordinate of the current mouse pointer location.
y
Number that on return specifies the y-coordinate of the current mouse pointer location.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.MouseDown, BPCVid.MouseUp


BPCVid.MouseUp

The MouseUp event occurs when the user releases a pressed mouse button.

Syntax

Private Sub object_MouseUp(button As Integer, shift As Integer, _
 x As OLE_XPOS_PIXELS, y As OLE_YPOS_PIXELS)

Parameters

object
Object expression that resolves to a BPCVid object.
button
Integer that on return identifies the button pressed to cause the event. The button parameter is a bit field with bits corresponding to the left button (bit 0), right button (bit 1), and middle button (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Only one of the bits is set, indicating the button that caused the event.
shift
Integer that corresponds to the state of the shift, ctrl, and alt keys at the time of the event. The shift parameter is a bit field with the least-significant bits corresponding to the shift key (bit 0), the ctrl key (bit 1), and the alt key (bit 2). These bits correspond to the values 1, 2, and 4, respectively. Some, all, or none of the bits can be set, indicating that some, all, or none of the keys are pressed. For example, if both ctrl and alt are pressed, the value of shift is 6.
x
Number that on return specifies the x-coordinate of the current mouse pointer location.
y
Number that on return specifies the y-coordinate of the current mouse pointer location.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.MouseDown, BPCVid.MouseMove


BPCVid.Power

The Power event indicates that the video access server has received a Windows power-management event.

Syntax

Private Sub object_Power(wParam As Long)

Parameters

object
Object expression that resolves to a BPCVid object.
wParam
Event notification message of the Windows WM_POWERBROADCAST message. To locate more information about Windows power management messages, see Further Information on Streaming Video Services for the Client.

The following power messages are valid:
Value | Meaning
PBT_APMBATTERYLOW | Battery power is low.
PBT_APMOEMEVENT | OEM-defined event occurred.
PBT_APMPOWERSTATUSCHANGE | Power status has changed.
PBT_APMQUERYSUSPEND | Request for permission to suspend.
PBT_APMQUERYSUSPENDFAILED | Suspension request denied.
PBT_APMRESUMECRITICAL | Operation resuming after critical suspension.
PBT_APMRESUMESUSPEND | Operation resuming after suspension.
PBT_APMSUSPEND | System is suspending operation.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.StateChange


BPCVid.StateChange

The StateChange event indicates a change in the state of a device. The video access server fires this event.

Syntax

Private Sub object_StateChange(lpdDevice As BPCDeviceBase, _
 ByVal oldState As Long, ByVal newState As Long)

Parameters

object
Object expression that resolves to a BPCVid object.
lpdDevice
Device whose state has changed.
oldState
State before the change occurred that triggered this event.
newState
State after the change occurred that triggered this event.

Remarks

In addition to the device state notifications defined by Broadcast Architecture, the video server forwards device state notifications defined by the DirectShow filter graph. To allow for current and future DirectShow filter states, Broadcast Architecture reserves the first 0x4000 device state identifiers for the DirectShow values.

The following device states are defined by DirectShow. To locate more information, see Further Information on Streaming Video Services for the Client.

stateStopped | The device is not in use.
statePaused | The device is paused.
stateRunning | The device is running and actively processing the multimedia stream.

The following device states are specific to Broadcast Architecture. They are declared in the Devtype.h file included with the Broadcast Architecture SDK:

Value | Meaning
BPC_STATE_SHUTDOWN | The video access server has received a system shutdown notification.
BPC_STATE_REINIT_REQUEST | The video access server has received a request to reinitialize the filter graph. For more information about this process, see BPCVid.ReInit.
BPC_STATE_REINIT_STARTED | All clients of the video access server are ready for the filter graph to be reinitialized.
BPC_STATE_REINIT_COMPLETE | Reinitialization of the filter graph is complete. Clients may resume normal activity. Note that the devices in the filter graph may have changed since reinitialization.
BPC_STATE_UNKNOWN | The device state is unknown.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.Power


BPCDevices

The BPCDevices object is a collection of all the devices currently available on the computer. In other words, BPCDevices is a collection of BPCDeviceBase objects.

The Video Access server creates an instance of one of these objects for each BPCVid object.

For more information, see the following topics:

  • BPCDevices Properties
  • BPCDevices Methods

Note that BPCDevices contains several reserved events. For more information on these, see Reserved Events in BPCDevices.

Remarks

You should not create an instance of a BPCDevices object directly, instead obtain the BPCDevices collection from BPCVid.Devices.

In the current version of Broadcast Architecture, only analog television tuner cards are listed in the BPCDevices collection. Future versions will list other input devices, such as a file playback device and output devices.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.Devices

Example

The following example retrieves the collection of available devices and stores it in the object variable devices.

'Declare an object variable to receive the collection.
Dim devices As BPCDevices

'Obtain the collection from the Video control.
Set devices = vid.Devices


Reserved Events in BPCDevices

The BPCDevices interface contains several events, listed following, that are not supported and that are reserved for future use.

BlackedOut | CAFail | CAFault
CannotPurchase | CardInvalid | CardMissing
CASuccess | ColdStart | CopyCard
CostExceeded | EPGFilterChanged | HandlePurchaseOffer
NewEmail | NoSubscriber | NotReady
OSDRequest | PasswordCleared | RatingExceeded
Ready | Retry | RevokeEvent
SignalLost | StateChange | TapingControlChanged
TuningChanged | WrongCard |


BPCDevices Properties

The BPCDevices object has the following properties.

Property | Description
Count | The number of devices currently available.


BPCDevices.Count

The Count property returns the number of devices currently available on the user's computer. This property is read-only.

Syntax

[ lCount = ] object.Count

Parts

object
Object expression that resolves to a BPCDevices object.
lCount
Long that indicates the number of BPCDeviceBase objects in the BPCDevices collection.


BPCDevices Methods

Method | Description
Item | Returns an item from the BPCDevices collection.


BPCDevices.Item

The Item method returns a reference to the specified BPCDeviceBase object in the BPCDevices collection. This property is read-only.

Syntax

[oDevice = ] object.Item(vName)

Parameters

object
Object expression that resolves to a BPCDevices object.
vName
VT_BSTR value that contains the device name of the BPCDeviceBase object.
oDevice
The BPCDeviceBase object specified by vName.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase


BPCDevices Events

The following events are sent by the Video Access server. The Video control passes these on to the application that is hosting it.

Event | Description
GotControl | The control receiving this notification has requested a device, and now has the highest priority.
LostControl | An application with higher priority requested the control's input or output device. The control receiving this notification is losing control.


BPCDeviceBase

The BPCDeviceBase object contains information about an individual device on the user's computer. The BPCDevices collection enumerates these objects.

For more information, see the following topics:

  • BPCDeviceBase Properties
  • BPCDeviceBase Methods

Note that BPCDeviceBase contains several reserved properties and methods. For more information on these, see Reserved Properties and Methods in BPCDeviceBase.

Remarks

There is no tuning space property for BPCDeviceBase. Instead the tuning space value associated with a particular device is stored as a registry key of the form \\HKLM\Software\Microsoft\TV Services\Tuning Spaces\<tuning_space>, where <tuning_space> is an integer that specifies the identifier of the tuning space.

A single device can provide multiple tuning spaces. For example an analog tuner might provide both the cable and antenna broadcast tuning spaces.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


Reserved Properties and Methods in BPCDeviceBase

The BPCDeviceBase interface contains several properties and methods, listed following, that are not supported and that are reserved for future use.

Status | Filename | HasFilename
BuyItem | CancelItem | CurrentState
EmailMessages | HandleCardChaining | HasCA
HistoryItems | ItemDetails | ProviderEPGMask
ProviderRating | ProviderStatus | ResetProviderSystem
Run | Stop | Pause
CurrentPosition | Rate | Duration


BPCDeviceBase Properties

The BPCDeviceBase class defines the following properties:

Property | Description
AudioFrequency | The frequency of the audio stream.
AudioSubchannel | The audio subchannel.
Channel | The channel that the device is currently tuned to.
CountryCode | The international dialing code that specifies the geographical location of the computer.
DefaultAudioType | The default type for the audio stream.
DefaultVideoType | The default type for the video stream.
HasChannel | A value that indicates whether the device supports channels.
IsInput | A value that indicates whether the device is set as the input device.
IsOutput | A value that indicates whether the device is set as the output device.
Name | A unique name for the device.
OverScan | The percent of pixels to trim from the edge of the video screen.
ProdName | The product name of the device. This name does not have to be unique.
UserName | The user-specified name for the device. This property is not currently implemented.
VideoFrequency | The frequency of the video stream.
VideoSubchannel | The video subchannel.

The following properties of the BPCVid object are passed to the current input device. You should set them using the BPCVid object instead of the BPCDeviceBase object. Otherwise, the Video control is not updated, and future behavior is undefined.

Property | Description
Balance | The current audio balance between left and right speakers.
ClosedCaption | A value that indicates whether closed captioning is turned on.
ImageSourceHeight | The authored height of the source image. This value does not change if the user resizes the control.
ImageSourceWidth | The authored width of the source image. This value does not change if the user resizes the control.
Power | A value that indicates whether the device is currently turned on.
PrerollTime | A value that indicates the amount of time to allow a tape to roll before starting to record.
ClosedCaption |  | A value that indicates whether closed captioning is turned on.
Volume | The current audio volume level.


BPCDeviceBase.AudioFrequency

The AudioFrequency property specifies the frequency of the audio signal. This property is read-only.

Syntax

[ lFrequency = ] object.AudioFrequency

Parts

object
Object expression that resolves to a BPCDeviceBase object.
lFrequency
Long that receives the audio frequency, in hertz.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase.VideoFrequency


BPCDeviceBase.AudioSubchannel

The AudioSubchannel property sets or retrieves the audio stream subchannel of a device.

Syntax

object.AudioSubchannel [ = lSubChannel ]

Parts

object
Object expression that resolves to a BPCDeviceBase object.
lSubChannel
A Long that specifies the subchannel.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase.VideoSubchannel, BPCDeviceBase.DefaultAudioType


BPCDeviceBase.Channel

The Channel property sets or returns the channel that the device is currently tuned to.

Syntax

object.Channel [ = lChannel ]

Parts

object
Object expression that resolves to a BPCDeviceBase object.
lChannel
Channel number tuned to.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase.HasChannel


BPCDeviceBase.CountryCode

The CountryCode property enables you to set or retrieve the country identifier for the device.

Syntax

object.CountryCode [ = lCode ]

Parts

object
Object expression that resolves to a BPCDeviceBase object.
lCode
A Long that specifies the country code.

Remarks

This property is an international dialing code that specifies the geographical location of the computer. This location information is used to set the frequency and format of analog video — for example, to choose between NTSC, PAL, and SECAM. This property is only available for analog tuners.

To locate more information on this property, see Further Information on Streaming Video Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCDeviceBase.DefaultAudioType

The DefaultAudioType property specifies the default audio type for the device.

Syntax

object.DefaultAudioType [ = lDefAudioType ]

Parts

object
Object expression that resolves to a BPCDeviceBase object.
lDefAudioType
A Long that indicates the default audio type. The audio types are device-specific types that allow the tuner to choose an appropriate subchannel if a default subchannel of –1 is specified. These types are defined in the Stream Type table of the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase.DefaultVideoType


BPCDeviceBase.DefaultVideoType

The DefaultVideoType property specifies the default video type for this device.

Syntax

object.DefaultVideoType [ = lDefaultVideoType ]

Parts

object
Object expression that resolves to a BPCDeviceBase object.
lDefaultVideoType
A Long that indicates the default video type. The video types are device-specific types that allow the tuner to choose an appropriate subchannel if a default subchannel of –1 is specified. These types are defined in the Stream Type table of the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase.DefaultAudioType, Stream Type table


BPCDeviceBase.HasChannel

The HasChannel property indicates whether the device supports channels. This property is read-only.

Syntax

[ bHasChannel = ] object.HasChannel

Parts

object
Object expression that resolves to a BPCDeviceBase object.
bHasChannel
Boolean that is True if the device supports channels and False if it does not.

Remarks

A television tuner card, for example, has a HasChannel property of True.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase.Channel


BPCDeviceBase.IsInput

The IsInput property indicates whether this device is the input device for the Video control. This property is read-only.

Syntax

[ bIsInput = ] object.IsInput

Parts

object
Object expression that resolves to a BPCDeviceBase object.
bIsInput
Boolean that receives True if the device is the input device, and False if it is not.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase.IsOutput


BPCDeviceBase.IsOutput

The IsOutput property indicates whether this device is the output device for the Video control. This property is read-only.

Syntax

[ bIsOutput = ] object.IsOutput

Parts

object
Object expression that resolves to a BPCDeviceBase object.
bIsOutput
Boolean that receives True if the device is the output device, and False if it is not.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase.IsInput


BPCDeviceBase.Name

The Name property returns the name of the current instance of the Video control. This property is read-only.

Syntax

[ sName = ] object.Name

Parts

object
Object expression that resolves to a BPCDeviceBase object.
sName
String expression that identifies the device. For example, "ATI TVTuner".

Remarks

This is a read-only property at run time. This property is the name given to the instance when it is created. This name is extended to the control when used in Visual Basic, and it may or may not be supported in other ActiveX control containers.

The value of Name is specified by the OEM in the device driver. If the OEM does not specify a name for the device, the Video control returns the generic class name for the device.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCDeviceBase.OverScan

The OverScan property sets the percentage of pixels to crop from the edges of the video picture.

Syntax

object.OverScan [ = lCutPercentage ]

Parts

object
Object expression that resolves to a BPCDeviceBase object.
lCutPercentage
A Long that contains the percent of pixels that should be trimmed from the edges of the video display. For example, if you set this value to 5 on a 100 x 100 pixel image, 5 percent of the pixels (in this case 5 pixels) is trimmed from each edge. The default value is 1.

Remarks

Setting this property enables your application to display on a computer precisely the same image a viewer sees on a television set.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCDeviceBase.ProdName

The ProdName property contains the product name of the device. This property is read-only.

Syntax

[ sName = ] object.ProdName

Parts

object
Object expression that resolves to a BPCDeviceBase object.
sName
String that contains the product name.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCDeviceBase.UserName

The UserName property enables you to set or retrieve the user name for this device.

Syntax

object.UserName [ = sName ]

Parts

object
Object expression that resolves to a BPCDeviceBase object.
sName
String that contains the user name.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCDeviceBase.VideoFrequency

The VideoFrequency property specifies the frequency of the video transmission. This property is read-only.

Syntax

[ lVideoFrequency = ] object.VideoFrequency

Parts

object
Object expression that resolves to a BPCDeviceBase object.
lVideoFrequency
Long that receives the frequency, in hertz.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase.AudioFrequency


BPCDeviceBase.VideoSubchannel

The VideoSubchannel property enables you to set or retrieve the subchannel for the video stream of this device.

Syntax

object.VideoSubchannel [ = lSubChannel ]

Parts

object
Object expression that resolves to a BPCDeviceBase object.
lSubChannel
A Long that specifies the subchannel.

Remarks

The subchannel values are set in the Stream table of the Guide database.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCDeviceBase.AudioSubchannel, BPCDeviceBase.DefaultVideoType


BPCDeviceBase Methods

The BPCDeviceBase object has the following methods.

Method | Description
ChannelAvailable | Determines if the specified channel has a valid signal.
DisplayConfigDialog | Displays a dialog box for configuration of the device.
MinMaxChannel | Returns the lowest and highest channel numbers supported by the device.

The following method is implemented in the BPCVid object as a wrapper for the equivalent method in the BPCDeviceBase object. You should call this method from the BPCVid object instead of the BPCDeviceBase object. Otherwise, the Video control may not be properly updated, and future behavior is undefined.

Method | Description
Refresh | Forces an update to the current window size, position, and visibility.


BPCDeviceBase.ChannelAvailable

The ChannelAvailable method returns a value indicating whether the specified channel has a valid signal.

Syntax

[ bSignalPresent = ] object.ChannelAvailable(nChannel, SignalStrength)

Parameters

object
Object expression that resolves to a BPCDeviceBase object.
nChannel
A Long that specifies the channel number.
SignalStrength
A Long that receives the signal strength.
bSignalPresent
Boolean that receives True if the specified channel has a valid signal and False if it does not.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCDeviceBase.DisplayConfigDialog

The DisplayConfigDialog method displays a dialog box that enables the user to configure the device.

Syntax

object.DisplayConfigDialog()

Parameters

object
Object expression that resolves to a BPCDeviceBase object.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.


BPCDeviceBase.MinMaxChannel

The MinMaxChannel method returns the lowest and highest channel numbers supported by the device.

Syntax

object.MinMaxChannel( lChannelMin, lChannelMax )

Parameters

object
Object expression that resolves to a BPCDeviceBase object.
lChannelMin
Long that receives the lowest channel number the device supports.
lChannelMax
Long that receives the highest channel number the device supports.

Remarks

For version 1.0 of Broadcast Architecture, this method only supports television tuners. If you call MinMaxChannel on another type of device, such as a satellite tuner card, the version 1.0 implementation of this method causes an error.

The minimum and maximum channels returned by this method are the same as the values returned by the IAMTVTuner::ChannelsMinMax method of DirectShow. For more information about this method, see Further Information on Streaming Video Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVid.MinMaxChannel, BPCDeviceBase.ChannelAvailable

Examples

The following example retrieves the minimum and maximum channel supported by the device identified by the tuning space identifier 3. These values are stored in the variables min and max.

Dim min As Long
Dim max As Long
vid.MinMaxChannel 3, min, max


BPCSuspend

The BPCSuspend object contains a single method, DeviceRelease, which you can use to suspend the video server and cause it to release all devices.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCSuspended, Suspending the Video Server

Examples

The following example uses the BPCSuspend object to request that the video server release all devices. When the devices are no longer needed, the BPCSuspended object is set to Nothing, allowing the video server to reconnect to the devices.

Dim susp As BPCSuspend
Set susp = New BPCSuspend
Dim suspended As BPCSuspended

'Attempt to suspend the video server
susp.DeviceRelease 0, suspended

'Test whether the video server was suspended
If (suspended Is Nothing) Then
  'Handle the case where devices cannot be released
Else
  'Use the devices
End If

'Release suspended to enable the video server to use the devices
Set suspended = Nothing


BPCSuspend.DeviceRelease

The DeviceRelease method causes the video server to attempt to release all devices.

Syntax

object.DeviceRelease(lPriority, pps)

Parameters

object
Object expression that resolves to a BPCSuspend object.
lPriority
Reserved. This value should be set to 0.
pps
Reference to a BPCSuspended object. If the video server successfully releases all video devices, this will contain a valid BPCSuspended object. Otherwise, this object contains Nothing.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCSuspended, Suspending the Video Server

Examples

The following example uses DeviceRelease to request that the video server release all devices.

Dim susp As BPCSuspend
Set susp = New BPCSuspend
Dim suspended As BPCSuspended

'Attempt to suspend the video server
susp.DeviceRelease 0, suspended


BPCSuspended

The BPCSuspended object indicates whether the video server has released all video devices.

This object is returned by the BPCSuspend.DeviceRelease method. If the method is successful and the Video server releases all video devices, the method returns a valid instance of BPCSuspended. The video server will remain suspended as long as this object instance exists.

To unsuspend the video server, release the BPCSuspended object by setting it to Nothing. The destruction of the BPCSuspended object notifies the video server that it can once again connect to devices. Otherwise, the video server will be re-enabled when the object variable goes out of scope or the application closes.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCSuspend, Suspending the Video Server


BPCVBIControl

The BPCVBIControl object provides methods that your application can use to tune the television tuner to a specific channel in order to receive data transmitted over the vertical blanking interval (VBI). BPCVBIControl does not receive or parse VBI data, it simply tunes to the specified channel

The BPCVBIControl object has the following methods.

Method | Description
VBITune | Tunes the tuner to the specified channel and tuning space in order to receive VBI data.
VBIStatus | Retrieves the current tuner settings for VBI reception and the strength of the VBI signal.

Remarks

Because the tuner is a nonsharable device, only one instance of BPCVBIControl can exist at a time. If you attempt to create a second instance, the second create will fail.

The BPCVBIControl object does not implement a resource conflict mechanism (Such as BPCDevices does with GotControl and LostControl events). Consequently, applications using this object must do so in a singular, or atomic, fashion, and ensure that no other applications are accessing BPCVBIControl simultaneously.

Displaying video is a higher priority operation tuning to a VBI-data channel. In other words, if the user is watching video on channel A, your application cannot use BPCVBIControl to tune to channel B. VBI data can only be received either when the user is watching video on the channel transmitting the VBI data, or when the user is not watching television.

When you release the BPCVBIControl object, the tuner receives VBI data using settings specified in the VBITS and VBIChan registry entries, if any. These entries are both type REG_DWORD. VBITS indicates the default VBI tuning space and VBIChan the default VBI channel. These entries are located in the HKLM\Software\Microsoft\TV Services registry key.

If the VBITS and VBIChan registry entries exist, the television tuner will automatically tune to the specified VBI channel whenever the user is not watching television and no other applications are using video. If these entries do not exist, the tuner stops the graph and releases the devices when there are no video clients.

Note The BPCSuspend object has higher priority than the BPCVBIControl and can preempt it. In other words, you can suspend the video server even if it is currently being used by the BPCVBIControl.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCSuspend, Tuning to Receive VBI Data


BPCVBIControl.VBITune

The VBITune method tunes the television tuner to the channel and tuning space which is broadcasting the VBI data.

Syntax

object.VBITune(lPriority, lTuningSpace, lChannel, lVideoSubchannel, lAudioSubchannel)

Parameters

object
Object expression that resolves to a BPCVBIControl object.
lPriority
Reserved. This parameter should be set to 0.
lTuningSpace
Long that indicates the tuning space.
lChannel
Long that indicates the channel number.
lVideoSubchannel
Long that indicates the video subchannel.

If you do not know the subchannel value, set this parameter to AMTUNER_SUBCHAN_DEFAULT. This flag is declared in the file Axextend.idl. To locate more information on Axextend.idl, see Further Information on Streaming Video Services for the Client.

lAudioSubchannel
Long that indicates the audio subchannel.

If you do not know the subchannel value, set this parameter to AMTUNER_SUBCHAN_DEFAULT.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVBIControl.VBIStatus, Tuning to Receive VBI Data

Examples

The following example causes the television tuner to receive VBI data over broadcast channel 27. When the data transmission is complete, the BPCVBIControl object is set to Nothing. This causes the tuner to receive VBI data using the default VBI channel, if any, defined in the registry.

Dim vbictrl As BPCVBIControl
Set vbictrl = New BPCVBIControl

'Set the tuner to receive VBI data on channel 27
vbictrl.VBITune 0, 2, 27, AMTUNER_SUBCHAN_DEFAULT, _
                                AMTUNER_SUBCHAN_DEFAULT

'... Code to receive and process the VBI data

'Release the tuner to receive VBI data using the default channel
'specified in the system registry.
Set vbictrl = Nothing


BPCVBIControl.VBIStatus

The VBIStatus method returns information about the channel and tuning space to which the tuner is currently tunes. It also returns the VBI signal strength.

Syntax

object.VBIStatus(lPriority, lTuningSpace, lChannel, lVideoSubchannel, lAudioSubchannel, lSignalStrength)

Parameters

object
Object expression that resolves to a BPCVBIControl object.
lPriority
Reserved. This parameter always receives 0.
lTuningSpace
Long that receives the tuning space.
lChannel
Long that receives the channel number.
lVideoSubchannel
Long that receives the video subchannel.
lAudioSubchannel
Long that receives the audio subchannel.
lSignalStrength
Long that receives the strength of the specified channel.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in vidsvr.odl.
Import Library: Included as a resource in vid.ocx.
Unicode: Yes.

See Also

BPCVBIControl.VBITune, Tuning to Receive VBI Data

Examples

The following example receives tuning information about the channel that the television tuner is currently using to receive VBI data.

Dim vbictrl As BPCVBIControl
Set vbictrl = New BPCVBIControl

'Declare variables to receive the information
Dim priority As Long
Dim tuningsp As Long
Dim channel As Long
Dim vidsubchl As Long
Dim audsubchl As Long

'Retrieve the current VBI tuning information
vbictrl.VBIStatus priority, tuningsp, channel, vidsubchl, audsubchl


Enhancement Video Control

The Enhancement Video control displays video within an enhancement. For example, in a multiframe enhancement you can use the Enhancement Video control to display the television show in one frame, while interactive content appears in the other frames. To display video using this control, you create an instance of the control in an enhancement page.

The Enhancement Video control is similar to the Video control in that both controls display video from a Hypertext Markup Language (HTML) page. However, two important differences exist between the Enhancement Video control and the Video control:

  • The Enhancement Video control can be used only in HTML pages displayed by Microsoft WebTV for Windows. In contrast, the Video control can be used in World Wide Web pages and stand-alone applications as well as in Microsoft® WebTV® for Windows®.
  • The Enhancement Video control automatically handles the connection between itself and WebTV for Windows. The Video control does not automatically handle such a connection.

If you are writing enhancement HTML pages that is only displayed by WebTV for Windows, it is much simpler to use the Enhancement Video control than the Video control.

For more information on the Enhancement Video control, see the following topics:

  • About the Enhancement Video Control
  • Using the Enhancement Video Control
  • Which Video Control Should I Use?


About the Enhancement Video Control

The Enhancement Video control displays video in HTML enhancement pages hosted by Microsoft® WebTV® for Windows®. This control is implemented as the Msepg4 class in the Msepg.ocx object library. The Enhancement Video control wraps the Video control, extending the Video control's functionality by automatically creating and handling a connection to WebTV for Windows when an instance of the Enhancement Video control is created.

Note The classes in Msepg.ocx other than Msepg4 are reserved for use by Broadcast Architecture and are not supported for use by external applications.

The Enhancement Video control accepts an HTML parameter, INTENT, which indicates how the Enhancement Video control is used in the current Web page. If you use the Enhancement Video control to display video in an enhancement, INTENT should be set to the value ENHANCE_VIDEO. For more information on INTENT, see Using the Enhancement Video Control.


Using the Enhancement Video Control

To add video to an enhancement page using the Enhancement Video control, place an instance of the control in the HTML page in the location where you want the video to appear. The INTENT parameter of the control instance must be set to the value ENHANCE_VIDEO.

You can add an instance of the Enhancement Video control to your enhancement page by using HTML code such as the following:

<OBJECT
  ID=Vid
  CLASSID="clsid:a74e7f00-c3d2-11cf-8578-00805fe4809b"
  BORDER=0
  VSPACE=0
  HSPACE=0
  ALIGN=TOP
  HEIGHT=100%
  WIDTH=100%
>
    <PARAM NAME="INTENT" VALUE=ENHANCE_VIDEO>
</OBJECT>

To see an example of how Microsoft® WebTV® for Windows® uses the Enhancement Video control, view the source code for the Video.htm and Msvideo.htm. Msvideo.htm displays full-screen video. Video.htm, which is encapsulated by the frames of Msvideo.htm, displays video using the Enhancement Video control. By default, these files are installed in the C:\Program Files\TV Viewer\Layouts\ directory.

Note The value FULL_SCREEN_VIDEO for the INTENT parameter is reserved for use by the default full-screen video page of WebTV for Windows. This use is the only situation in which INTENT should be set to this value. Enhancement files must always set INTENT to ENHANCE_VIDEO.


Which Video Control Should I Use?

To display video in an HTML file, you can use either the Video control or the Enhancement Video control.

The Video control is a general-purpose control that can be used in enhancements for Microsoft® WebTV® for Windows®, World Wide Web pages, and stand-alone applications. In contrast, the Enhancement Video control is a WebTV for Windows–aware control that can only be used in WebTV for Windows enhancements.

Each is preferable in different circumstances:

  • To display video in Web pages or stand-alone applications, or in enhancement files that require programmatic control over video input, use the Video control.
  • To display video in enhancement files that will only be displayed in WebTV for Windows and that do not require programmatic control over video input, use the Enhancement Video control.

Because the Enhancement Video control implements functionality that interacts with WebTV for Windows, it is much simpler to use the Enhancement Video control to display video in enhancements than the Video control. To add video to an enhancement file using the Enhancement Video control, all you need do is create an instance of the control on an enhancement page. Video from the current channel is then automatically displayed. In contrast, if you use the Video control you must write code or script to determine the interactive show's channel number in the user's system and to set that channel as the control's input.

Although using the Video control involves more work, it provides the advantage that your application can programmatically control tuning and video input. For example, a Video Valet application might keep a list of a user's preferred television lineup and automatically tune the Video control to the correct channel for each of the user's favorite shows. Such an application can only be created using the Video control.


DirectShow Filter Reference

This section documents features of the filters based on the Microsoft® DirectShow™ application programming interface (API) found on the broadcast client. Applications access these filters through the Microsoft® ActiveX® control for video (the Video control). Applications use these filters to control playback and display of video and audio. In addition to the filters described here, broadcast clients use filters that are part of the Microsoft® Windows® 98 operating system. To locate a description of these filters, see Further General Information.

Note For reference purposes, each filter description following includes the name of the file containing that filter. However, you do not typically address a filter through that file name. Instead, you rely on the Video control to work with the Video Access server to set the connections for your application.


Digital Crossbar Filter

File Name

Tssxbar.ax

Filter Type

Utility filter

The following illustration shows a digital crossbar filter, with control interfaces and data pins.

Summary

The Digital Crossbar filter represents a digital video hardware multiplexer (MUX). Through this filter, a video source can be chosen and routed to the VGA device.

Data Pins

Name | Direction | Description
Video | Input | Video type; UncompressedDigitalVideo subtype
Video | Output | Video type; UncompressedDigitalVideo subtype

Control Interfaces

Name | Purpose
IFilter | Provides run, stop, and pause capabilities
ICrossbarSwitch | Controls the switch


Announcement Listener

Announcement Listener and its supporting components enable the broadcast client to receive announcements of upcoming data, and to programmatically filter incoming data to select the data that the client computer should receive.

The following sections provide further information about Announcement Listener:

  • Announcements Overview
  • Announcement Listener Components
  • Creating an Announcement Filter
  • Using a File Receiver Application
  • Specifying an Announcement Stream Source


Announcements Overview

The broadcast of any data stream must be preceded by an announcement of the impending broadcast, describing the sender, address, time, contents, and other pertinent details. By examining these announcements, the broadcast client can select which data streams to keep and which data streams to ignore.

Announcement Listener and its supporting components are designed to provide interfaces for capturing and processing data introduced by specific announcements.

Announcement Listener enables installation of custom-defined filters to select announcements. Filters can be enabled and disabled individually. Announcement Listener allows arbitrary data formats, both streaming and file-based.

The following sections provide an overview of announcements:

  • Announcement Channels
  • Announcement Format
  • Recommended Announcement Fields
  • Sequence of Events


Announcement Channels

To inform clients of the data broadcasts available on a network, broadcasts must be preceded by an announcement. An announcement is a small datagram containing information about the upcoming broadcast.

Announcements are sent on publicly known addresses. These addresses are stored in the registry under HKEY_LOCAL_MACHINE/Software/Microsoft/TV Services/Announcements. Up to six Internet Protocol (IP) addresses can be stored under this key.


Announcement Format

Session announcements are formatted according to Session Description Protocol (SDP) and its associated Session Announcement Protocol (SAP). These protocols are described in work-in-progress Internet draft documents produced by the Multiparty Multimedia Session Control (MMUSIC) working group of the Internet Engineering Task Force. As such, they may be updated, replaced, or made obsolete by other documents at any time.

To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (U.S. East Coast), or ftp.isi.edu (U.S. West Coast). The SDP and SAP draft proposals are described in the documents draft-ietf-mmusic-sdp-03.txt and draft-ietf-mmusic-sap-00.txt, respectively. For example, in the United States, the SDP document can be found at:

ftp://ftp.isi.edu/internet-drafts/draft-ietf-mmusic-sdp-03.txt

SAP is a header in binary format that precedes the SDP description, and is described in the SAP draft document. Both the SAP and SDP message announcements may be encrypted.

SDP is a textual protocol. It consists of series of lines of text, with each line beginning with a single letter followed by an equal sign, followed by a text line formatted appropriately, followed by a new line.

In the Microsoft® Windows® 98 operating system and the Microsoft® Windows NT® operating system version 4.0, the SDP protocol is wrapped inside a set of Component Object Model (COM) components and interfaces to send and receive announcements of multiparty multimedia conferences. For more information about SDP services in Windows, see Further Information on Data Services for the Client.


Recommended Announcement Fields

Session Description Protocol (SDP) specifies a number of required and recommended fields (for more information, see Announcement Format).

In addition to these, the following attribute is available with Broadcast Architecture:

  • a=hidden

    Indicates that an announcement is not intended for human eyes — that is, it is intended for a programmatic filter.


Sequence of Events

This overview describes how the various elements of Announcement Listener work in time sequence.

First, filters are installed on the client computer. A filter is an Automation server, which is an in-process server implemented as a DLL (dynamic link library) file. There are two filters that are installed as part of Broadcast Architecture. One for receiving announcements of upcoming file transfers and one for receiving enhancements for interactive television. Custom filters can be installed by the user by using the Annui.exe program.

When Annui.exe installs a filter it calls the DLLRegisterServer function, implemented by the filter to register the filter as a service. Once the filter is registered, Announcement listener will use it to match incoming announcements.

When an announcement arrives on a socket associated with an announcement address, Announcement Listener parses the announcement packet and puts the elements of the announcement in an Sdpblb object. Announcement Listener also creates an instance of the IBroadcastFilter object to hold the Sdlblb object. Announcement Listener checks that this announcement has not already been passed to the filters, and if not, it then hands that object to the filters. Each filter executes its own code to determine whether or not the announcement meets its criteria. The filter is called using the method IBroadcastFilter::Match.

If a filter returns a flag indicating it does not match, Announcement Listener asks the next filter in turn, until all the filters have been asked.

If a filter returns with the match flag set to true, Announcement Listener adds the announcement's unique identifier to a list, so that if the same announcement is rebroadcast later, Announcement Listener does not ask the filters again.

If a filter returns a flag indicating that it has found a match, the filter also returns a second flag that specifies whether Announcement Listener should schedule the launch of an application to receive the data at the expected time. In most cases, the filter makes this request. However, if the data is expected to arrive imminently, the filter can directly call an external process designed to receive the data. In this case, the filter sets the Schedule flag to "false," so that Announcement Listener does not schedule a future event. Because the match flag is true, Announcement Listener still treats the announcement as matched, and does not present the same announcement to the filters again.

If the Schedule flag is true, Announcement Listener calls another method in the filter called, IBroadcastFilter::GetDisposition. This method returns to Announcement Listener the information it needs to schedule a future task to receive the data. This information includes what application to launch, the working directory, the command line, and how far in advance of receipt of the data the application should be launched.

In this case, Announcement Listener provides the Task Scheduler with the announcement and the other information provided by GetDisposition. For more information, see Scheduling Data Reception.

After each announcement has been matched by a filter, or fails to be matched by any of the filters, the announcement is discarded.

Announcement Listener or the filter can take immediate action, such as starting file download if the file follows the announcement, or it can schedule an action using the Task Scheduler (a component of Windows 98).

Announcement Listener also accepts announcements that cancel a previous announcement.


Announcement Listener Components

The following sections describe components of Announcement Listener:

  • Announcement Listener System Service
  • Announcement Filters
  • Receiver Applications
  • Receiver Application Command Line
  • Scheduling Data Reception


Announcement Listener System Service

The Announcement Listener system service comprises a number of components that operate together to capture, filter, and process broadcast data.

The primary Announcement Listener system service adheres to the IDataListener interface. It runs constantly unless explicitly disabled or halted by the user, receiving announcements from sockets on well-known Internet Protocol (IP) address and port pairs, passing those announcements to its installed filters, and scheduling the receipt of any announcements that a filter selects.


Announcement Filters

Filters are used by Announcement Listener to distinguish between announcements that are of interest to a user and those that are not. Using filters to select what data to receive prevents Broadcast Architecture from wasting computer resources.

Announcement Listener maintains a list of filters. Each filter, when presented with an announcement, can register interest in the receipt of the data associated with the announcement. If a filter registers interest and requests that Announcement Listener schedule future reception, it must also provide the name of an application to receive that data.

A filter is an Automation server that supports a number of interfaces. For more information, see Creating an Announcement Filter. Applications may add, remove, enable, or disable filters in Announcement Listener through Automation, and users may do the same through the Announcement Filter Manager. Filters have persistent states, and multiple instances of a given filter may be running simultaneously with each instance matching different criteria.

Announcement Listener presents announcements sequentially to all the filters. However, once a filter registers interest in an announcement, that announcement and any rebroadcasts of it are not presented to any filter, to reduce the unnecessary overhead of calling filters that are not interested in the announcement. The exception is when the ListenAll property of a filter is set to TRUE; for more information, see the IBroadcastFilter:get_ListenAll method.


Receiver Applications

When an Announcement Listener filter registers interest in receiving a data stream, it must provide the name of an application for the actual capture (and possible storage) of that stream. The only defined interface between a filter and a receiver application is that of command line parameters, though obviously, if allied more tightly in their designs they can share richer communication.

Announcement Listener spawns a receiver application before the broadcast of the desired data stream and provides the receiver application with the IP address and port of that stream as a command line parameter. The receiver application is then solely responsible for interpreting the format of the data stream, storing the data stream if desired, launching other applications, and taking any other appropriate actions. For more information, see Receiver Application Command Line.

Broadcast Architecture includes a generic receiver application for the transfer of files. This application captures files broadcast in the Common Content Framework for Interactive Programming format, and saves them in a directory on the client computer system designated for this purpose.


Receiver Application Command Line

A receiver application is an executable application that is intended to be launched by the Task Scheduler at the appropriate time to receive the information previously announced. You can use the generic receiver application or write one of your own. For more information, see Receiver Applications.

At the appropriate time, the Task Scheduler launches the receiver application. The Task Scheduler provides three command line arguments to the receiver application. These arguments are prepended to the Parameters string provided by the IBroadcastFilter::GetDisposition or IDataListener::SubmitAnnouncement method. These command-line arguments are:

  • /J job_name — the task name in the IJobScheduler interface that launched this process. For example:
    /J BFTP_JOB_234
  • /IPD destination_address_and_port_of_multicast. For example:
    /IPD 224.45.38.92:3256
  • /IPL local_address_of_network_card_receiving_multicast. For example:
    /IPL 192.78.38.92

The destination address is the IP address to which the data is broadcast. The local address is the IP address of the network interface card that receives the data; this allows a distinction to be made between a satellite receiver card and any other type of network interface when more than one card is present.

For example, suppose the arguments supplied by a filter to Announcement Listener by IBroadcastFilter::GetDisposition are as follows:

WorkingDirectory = C:\Games\
Application = GameRecv.exe
Parameters = /o
AdvanceMinutes = 2

At the appointed time, Task Scheduler launches the specified receiver application with the following command line:

GameRecv /J "BFTP_JOB_234" /IPD 224.45.38.92:3256 / IPL 192.78.38.92 3A45F /o

In this case, Gamerecv.exe is an application designed to receive multicast data on the specified address, and /o is an additional parameter that is being passed to the receiver application.

The receiver application can be the final receiver of the data (as in the example preceding), or it can be a simple shell that launches the final receiver of the data (for more information, see Using the Generic File Receiver Application).


Scheduling Data Reception

Announcement Listener must maintain a time-ordered queue of pending broadcasts and start the receiver applications sufficiently before their broadcasts so that they are loaded and ready when the data becomes available. If an announcement precedes its broadcast by a significant length of time, some client computers may be rebooted during that span. This means that the queue for broadcasts must be persistent.

Task Scheduler is a resource included with the Microsoft® Windows® 98 operating system. Task Scheduler enables Announcement Listener to launch receiver applications at pre-specified times. The queue is stored on the hard disk, and thus persists across machine reboots. (Other components of the Broadcast Architecture also use the Task Scheduler for reminders of television shows.)

The Task Scheduler has a programmatic Component Object Model (COM) interface, as well as a simple user interface. Announcement Listener uses only the programmatic interface.


Creating an Announcement Filter

In order to respond to an incoming announcement, an appropriate filter must be created and installed on the client computer.

Announcement filters must implement a COM compatible in-processes server that implements a class that inherits from the IBroadcastFilter and IPersistStream classes. The filter implements methods in this class that Announcement Listener will call to process announcements.


Using a File Receiver Application

The following sections describe using a file receiver application:

  • Using the Generic File Receiver Application
  • Creating a Receiver Application
  • Retrieving Announcement Attributes


Using the Generic File Receiver Application

The Generic File Receiver is designed to capture a file or files that have been broadcast. The Generic File Receiver may also optionally spawn a second application, passing the file names of the received file or files to it, or attempt to launch the files themselves (using the file associations for the Microsoft® Windows® family of operating systems).

The Generic File Receiver expects to find the /J, /IPD, and /IPL options in the command line passed to it by the Task Scheduler, as described in Receiver Application Command Line.

In addition, the /s option may be used with the Generic File Receiver to spawn the received file. The /s string may be supplied in the Parameters string returned by IBroadcastFilter::GetDisposition. Without the /s option, the Generic File Receiver simply receives the file and saves it in the specified working directory.

For example, to launch the file received, the command line is:

GenRecv /J "BFTP_JOB_234" /IPD 224.45.38.92:3256 /IPL 192.78.38.92 /s

(The preceding example assumes that the Generic File Receiver has been named Genrecv.exe; in fact it has not yet been named.)

Any text on the command line of the Generic File Receiver beyond the /J, /IPD, /IPL, and /s options is treated as a new command line, with the name of the received file appended at the end of the command line arguments. For example, the command line:

GenRecv /J "BFTP_JOB_234" /IPD 224.45.38.92:3256 /IPL 192.78.38.92 Excel.exe

causes the Generic File Receiver to launch Microsoft® Excel with the file received. Assuming that the transmitted file was Sample.xls, this results in the following command line being launched:

Excel.exe Sample.xls

If a /s option appears with other arguments beyond the /J, /IPD, and /IPL on the command line, the /s are presented along with the other arguments as the new command line, rather than spawning the received file. For example:

GenRecv /J "BFTP_JOB_234" /IPD 224.45.38.92:3256 /IPL 192.78.38.92  Excel.exe /s

launches the following (assuming that the transmitted file was Sample.xls)

Excel.exe /s sample.xls

(In this case, /s is assumed to be a parameter intended for Excel.exe.)

If the Generic File Receiver runs successfully, it deletes its job from the Task Scheduler, even if there are later scheduled broadcasts (if there are no later scheduled broadcasts, the JOB_FLAG_DELETE_WHEN_DONE value causes the job to be deleted automatically, whether it succeeded or failed). If the Generic File Receiver fails and IJob::GetNextRunTime returns the value S_OK, then the job is left in the scheduler to run again.


Creating a Receiver Application

If the Generic File Receiver application proves insufficient for the needs of your application, you can create a custom receiver application.

The application must be able to appropriate process the /J, /IPD, and /IPL options in the command line passed to it by the Task Scheduler, as described in Receiver Application Command Line.

Typically, a receiver application may ignore the /J option. The application must open a Windows Sockets (WinSock) socket using the address specified by /IPD and bind it to the address specified by /IPL. The application can then receive data over the broadcast connection and process it any way that is desired.

The receiving application may access various attributes that were included in the original announcement, as described in Retrieving Announcement Attributes.


Retrieving Announcement Attributes

A receiving application, when spawned, may need to access any number of attributes from the original announcement. For example, when a stock ticker application is launched in response to announcement, it should display an appropriate title, depending on an attribute in the announcement (such as a = market:NYSE).

When the application is spawned, however, the original announcement is no longer available. Fortunately, the Task Scheduler stores the full text of the announcement, including all session attributes, in the user data for the task. The Task Scheduler supplies the name of the task that launched the receiving application in the command line passed to the receiving application. (For more information, see Receiver Application Command Line.)

The most convenient way to access the attributes in the task is to create a new broadcast announcement and fill it with the stored information from the task. Calling the ITask::GetUserData method in the Task Scheduler interface, and passing the result to the IBroadcastAnnouncement::Load method, fills an empty broadcast announcement with data from the Task Scheduler. The resulting announcement appears as though it had just been received by Announcement Listener over an announcement channel.

The application is now able to access the attributes using the same announcement interface that announcement filters use.


Specifying an Announcement Stream Source

Announcements are broadcast on one or more streams. Each stream is associated with a particular data service, and is broadcast on a separate Internet Protocol (IP) address and port. Announcement Listener can listen to more than one announcement stream at a time.

The names and addresses of the announcement streams are stored in the system registry, under the key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\TV Services\Announcements

The Registry Editor (RegEdit) provides access to the names and addresses of announcement streams, and enables new announcement streams to be added.

In the Announcements key, each announcement stream is represented by a value. The name of the value should reflect the name of the data service being announced. This name appears in dialog boxes and error messages. The data field consists of the IP address and port of the announcement stream, expressed in the format byte.byte.byte.byte:port, as shown in the following illustration.

In the example shown, a data service called "Webcast" is being announced on IP address 227.37.32.1, port 22701.

Typically, the installation program for a data service programmatically installs a new value into the Announcements key, reflecting the name of the service and the address and port of its announcement stream.


Announcement Listener Reference

The following sections provide reference material for Announcement Listener:

  • Filter Interfaces
  • Announcement Listener Interfaces


Filter Interfaces

Every broadcast filter installed in Announcement Listener must be an Automation server supporting the following interfaces: IBroadcastFilter and IPersistStream. A filter supporting the interfaces IGenericFilter and its helper interfaces IFields and IField will be shipped with a future release of the Broadcast Architecture, but other filters are not required to support these interfaces.

Filters must have the normal registry entries for Microsoft® ActiveX® components that share their functionality with other applications (local or in-process). In addition, they must register as supporting the component categories CATID_PersistsToStream and CATID_BpcFilter.

Dual Interfaces

You can write your filter in any language that can implement dual interfaces. Choosing a language involves many considerations: familiarity with the language, tools support, run-time performance, threading models, code complexity, and the size of the compiled code. Languages and products that can be used to write Automation server components include the Microsoft® Visual C++® development system, the Microsoft® Visual Basic® development system, and Java.

Announcement Listener Filter Interfaces

  • IBroadcastFilter
  • IFilterField
  • IFilterFields
  • IGenericBroadcastFilter
  • IPersistStream


IBroadcastFilter

The IBroadcastFilter interface has three purposes: to perform the actual filtration of broadcast announcements, to provide a user interface to a filter, and to provide methods and properties necessary for the enabling, disabling, or deletion of a filter.

Every filter must support Automation and the IBroadcastFilter interface. Each filter supplies the functionality for the methods in the table following, which are called by Announcement Listener.

Quick Info

Called by: | Announcement Listener
Interface definition: | Dual

Method | Description
Delete | Announcement Listener invokes this method to notify the filters of an announcement deletion message.
get_Enabled | Indicates whether Announcement Listener calls this filter. A filter may be disabled but still reside in the filter list.
get_Hidden | Returns a property that, if true, suppresses the display of the filter in the Filter Manager user interface. The filter still is accessible programmatically through the collection in the IDataListener. Hidden filters cannot be enabled, disabled, or removed by users. One use for a hidden filter is to listen for upgrades to the Broadcast Architecture software itself.
get_LastMatched | Property indicating the last time this filter selected an announcement. Used by the Filter Manager.
get_ListenAll | A property that, when true, causes all announcements to be presented to a filter, even if they have been matched previously by another filter. A filter with the ListenAll property set to TRUE receives all announcements, whether or not another filter has already registered to receive the associated broadcast data. This permits special filters to be created for monitoring or debugging.
get_Name | Returns the name of this instance of the filter. Used by the Filter Manager.
get_NumberMatched | The total number of announcements the filter has selected. Used by the Filter Manager.
GetDisposition | Returns to Announcement Listener the information it needs to schedule a future task to receive the data, including what application to launch, the working directory, the command line, and how far in advance of receipt of the data should the application be launched.
Match | Checks whether the announcement describes a data transmission that should be received, and if so, whether Announcement Listener should schedule a task to receive the data. Used by the Announcement Listener.
put_Enabled | Sets the Enabled property of the filter.
ShowProperties | Announcement Listener invokes this method to request the filter to display its properties (if any) in a dialog box.


IBroadcastFilter::Delete

IBroadcastFilter::Delete is the method by which a filter is notified of an announcement deletion. Filters that schedule their data reception through Announcement Listener need not respond.

However, filters that schedule their own data reception should authenticate the deletion packet and, assuming it is valid, remove any self-scheduled data receipts that were initiated by the announcement being deleted. Such filters must maintain a list of the origin lines (for example, o=) and source addresses from any announcements received. When a deletion is presented to the filter, the filter must ascertain that the deletion pertains to some announcement to which it matched, and remove the scheduled receipt of the data from any queue the filter maintains.

Certain security verifications are required to ensure that an announcement deletion is legitimate. To locate more information on the relationship between an announcement and a deletion notice for that announcement, see Further Information on Data Services for the Client.

If a filter schedules tasks with Announcement Listener, then Announcement Listener provides all authentication.

HRESULT Delete(
  IBroadcastAnnouncement *Announcement  // pointer to the object
                                        // containing the deletion
                                        // announcement, as specified
                                        // by SAP
);

Return Values

Returns an HRESULT indicating success or failure.


IBroadcastFilter::get_Enabled

This method retrieves the value of the Enabled property.

HRESULT get_Enabled(
  BOOL *pfEnabledRet  // pointer to flag indicating whether this
                      // filter is enabled
);

Return Values

Returns an HRESULT indicating success or failure.

Remarks

The Enabled property specifies whether Announcement Listener is to call this filter when a new announcement arrives. A filter may be disabled but still reside in the filter list.


IBroadcastFilter::get_Hidden

The Hidden property, if true, suppresses the display of the filter in the Filter Manager user interface. The filter is still accessible programmatically through the collection in the IDataListener. Hidden filters cannot be enabled, disabled, or removed by users through the user interface, although they can be manipulated programmatically. One use for a hidden filter is to listen for upgrades to the Broadcast Architecture software itself.

HRESULT get_Hidden(
  BOOL *lpfReturn  // pointer to flag that indicates this filter is
                   // hidden
);

Return Values

Returns an HRESULT indicating success or failure.


IBroadcastFilter::get_LastMatched

This method returns the LastMatched property through a pointer.

The LastMatched property contains a date representing the last time this filter selected an announcement. Used by the Filter Manager.

HRESULT get_LastMatched(
  DATE *lpdateReturn  // pointer to the LastMatched flag
);

Return Values

Returns an HRESULT indicating success or failure.

See Also

IBroadcastFilter::get_NumberMatched


IBroadcastFilter::get_ListenAll

This method returns the ListenAll property through a pointer.

The ListenAll property, when true, causes all announcements to be presented to a filter, even if they have been matched previously by another filter. A filter with the ListenAll property set to TRUE receives all announcements, whether or not another filter has already registered to receive the associated broadcast data. This permits monitoring or debugging filters to be written.

HRESULT get_ListenAll(
  boolean *lpfReturn  pointer to the ListenAll flag
);

Return Values

Returns an HRESULT indicating success or failure.


IBroadcastFilter::get_Name

The IBroadcastFilter::get_Name method returns the name of this instance of the filter. Used by the Filter Manager.

HRESULT Name(
  BSTR *lpbstrReturn  // out
);

Parameters

lpbstrReturn
Name of this instance of the filter.

Return Values

Returns S_OK on success.


IBroadcastFilter::get_NumberMatched

This method returns the NumberMatched property through a pointer.

The NumberMatched property contains the total number of announcements the filter has selected. Used by the Filter Manager.

HRESULT get_NumberMatched(
  long *lplReturn  // pointer to the number of matches
);

Return Values

Returns an HRESULT indicating success or failure.

See Also

IBroadcastFilter::get_LastMatched


IBroadcastFilter::GetDisposition

The IBroadcastFilter::GetDisposition method enables the filter to specify the information that Announcement Listener needs to schedule a future task to receive the data, including what application to launch, the working directory, the command line, and how far in advance of receipt of the data should the application be launched.

HRESULT GetDisposition(
  BSTR * WorkingDirectory,  // out
  BSTR * Application,    // out
  BSTR * Parameters,     // out
  long * AdvanceMinutes  // out
);

Parameters

WorkingDirectory
Working directory in which to launch the target application.
Application
File name of the application to be launched.
Parameters
String to be appended to the command line following the application name.
AdvanceMinutes
Number of minutes prior to the time the announced data arrives to launch the application.

Return Values

Returns an HRESULT indicating success or failure.

See Also

IBroadcastFilter::Match


IBroadcastFilter::Match

The IBroadcastFilter::Match method checks whether the announcement describes a data transmission that should be received, and if so, whether Announcement Listener should schedule a task to receive the data. If Match returns TRUE and the Schedule parameter is also TRUE, then Announcement Listener creates a task in the Task Scheduler in the Microsoft® Windows® 98 operating system. This task receives the associated data. If Match returns TRUE and the Schedule parameter is FALSE, the announcement is treated as if it had been matched and scheduled, but no task is created.

HRESULT Match(
  IBroadcastAnnouncement *Announcement,  // in
  BOOL AlreadyMatched,                   // in
  BOOL *Schedule,                        // out
  BOOL *lpfReturn                        // out, retval
);

Parameters

Announcement
Pointer to the object containing the announcement.
AlreadyMatched
Flag that indicates to a filter whether the announcement has already been matched by another filter. (This flag is of interest only to a filter designed for monitoring or debugging. For a filter that is not ListenAll, this parameter is always FALSE.)
Schedule
Pointer to a flag used by the filter to request Announcement Listener to schedule a task for future receipt of the data. Necessary scheduling information can be obtained by using the IBroadcastFiler::GetDisposition method.
lpfReturn
Pointer to a flag used by the filter to indicate that the filter has found a match on the announcement data.

Return Values

Returns an HRESULT indicating success or failure of the call.

See Also

IBroadcastFilter::GetDisposition


IBroadcastFilter::put_Enabled

This method stores the value of the Enabled property.

HRESULT put_Enabled(
  BOOL Enable  // flag indicating whether this filter is enabled
);

Return Values

Returns an HRESULT indicating success or failure.

Remarks

The Enabled property specifies whether Announcement Listener is to call this filter when a new announcement arrives. A filter may be disabled but still reside in the filter list.

Filters must shutdown any threads the filter is using when Announcement Listener calls put_Enabled with the Enable argument set to VARIANT_FALSE. This allows Announcement Listener to properly shutdown.


IBroadcastFilter::ShowProperties

IBroadcastFilter::ShowProperties is a method by which the Announcement Filter Manager may request a filter to display its properties with a dialog box. This method must be implemented by all filters, but the method need not necessarily display a dialog box.

Filters that contain properties that can be set by the user but cannot otherwise be edited can use this feature to display a dialog box through the Announcement Filter Manager. Hidden filters, and those filters with no editable properties, may implement this method with no action.

Filters that use this method to display a user interface should create a modal dialog box with the owner window set to the HWND parameter to the call. The filter must continue to service Automation requests, particularly calls to Match while the dialog box is displayed. This requirement implies that the call to ShowPropertiesDialog must return before the dialog box is displayed, because calling OleBlockServer is not acceptable.

This may be accomplished either by using a modeless dialog box or by spawning another thread which creates a modal dialog box.

The following code must be included in all filters, at a minimum:

// In the class definition of your IBroadcastFilter implementation
STDMETHOD(ShowProperties)(OLE_HANDLE Window);

// In the implementation file.
STDMETHODIMP
CGenericFilter::XFilter::ShowProperties(OLE_HANDLE Window)
{
    METHOD_PROLOGUE(CGenericFilter, Filter)
    try
    {
        return E_NOTIMPL;
    }
    CATCH_DUAL_EXCEPT()
}


IFilterField

This is the heart of the generic filter; the interface through which the numeric or regular expression to match a field in an announcement can be set or retrieved.

Following is a preliminary description of the interface.

enum BPC_FieldType {AddressField, PatternField, NumericField, UndefinedField};

interface IFilterField : IDispatch
{
[id(DISPID_VALUE), propget] HRESULT MatchString([out, retval] BSTR *MatchString);
[id(DISPID_VALUE), propput] HRESULT MatchString([in] BSTR MatchString);
[id(1), propput] HRESULT FieldType([in] BPC_FieldType FieldType);
[id(3), propget] HRESULT Name([out, retval] BSTR* lpbstrReturn);
};

When added, a field has type BPC_FieldType::UndefinedField. The filter then only requires that the field be present in an announcement, without regard to its content. If a field is given a type of BPC_FieldType:PatternField or BPC_FieldType:NumericField then the MatchString is interpreted as a regular expression to be matched, or a numeric expression to be evaluated for truth or falsehood, respectively.

The numeric expression evaluator accepts the following operators: <, >, >=, <=, ==, !=, +, -, /, *, ), (, &&, ||, &, ~, |, ^, and !. Their meaning is similar to the same in the C language. Anywhere that a question mark appears in the expression, it is replaced by the numeric value of the field. All operations are carried out with double precision floating point numbers.

The regular expression evaluator uses accept the same patterns as the one in the Visual C++ version 4.1 IDE. This should be specified more completely in a future version of this document.

If a field type is set to BPC_FieldType:AddressField, then the value of the field is parsed as an Internet Protocol (IP) address. A variety of formats may be supported for this type.


IFilterFields

This interface is the collection of fields in a generic filter that have been set to match announcement fields. With this collection, you can add or remove fields for matching or iterate through the fields currently used by the filter.

Following is a preliminary description of the interface.

interface IFilterFields : IDispatch
{
// The Index parameter is numeric index or the name
[id(DISPID_VALUE)]
HRESULT Item([in] VARIANT Index, [out, retval] IFilterField ** lppifReturn);
[id(1), propget]
HRESULT Count([out, retval] long *lplReturn);
[id(2)]
HRESULT Add([in] BSTR Name);
[id(3)]
HRESULT Remove([in] BSTR Name);
[id(DISPID_NEWENUM), restricted]
HRESULT _NewEnum([out, retval] IUnknown **pUnkRetVal);
};

The Item method can take either a BSTR for the field name, or a numeric index.


IGenericBroadcastFilter

The generic filter will be provided in future releases of the Broadcast Architecture software. It will be programmable to match any announcement field, either as a regular or numeric expression. The disposition of the broadcast (such as receiving application, working directory) may also be specified.

This interface is currently in development, pending decisions on the announcement protocol.

The current version of the generic filter allows matching for any arbitrary line. In contrast, the ISDP interface contains specified properties including telephone, address, start time, stop time, and others. With this interface, searching is not required; instead the generic filter will contain properties that roughly correspond to those of the ISDP interface, except that search strings, rather than values, are specified.

For example, the generic filter will include a Uniform Resource Locator (URL) match string that corresponds to the session URL string in the ISDP interface. The URL match string might contain http://www.microsoft.com/*.* to indicate all files at the Microsoft site. Each of these fixed properties will have a regular expression for matching.

For extensible attributes, the a field allows arbitrary fields. An arbitrary field can contain anything. The interfaces supports as many a lines as needed. The line may take either of the following forms:

a=flag
a=attribute:value

For example, the line a=difficulty:friendly specifies friendly as the value of the attribute difficulty.


IPersistStream

IPersistStream is a standard interface for saving and restoring the state of an object. Each filter, when created, may receive an IStream from which to initialize itself. Announcement Listener uses this interface to request filters to save their states into a different IStream on shutdown, and to restore their states from that IStream on start-up.

At a minimum, a filter must save the number of announcements it has matched, and the date of the last announcement it matched. Any other state persistence is entirely at the option of the filter.

To locate more information on the IPersistStream interface, see Further Information on Data Services for the Client.

QuickInfo

Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in objidl.h.


Announcement Listener Interfaces

Announcement Listener supports Automation so that other applications can share its functionality. Announcement Listener makes its methods available to other components through the following interfaces:

  • IBroadcastAnnouncement
  • IDataListener
  • IFilterCollection


IBroadcastAnnouncement

An IBroadcastAnnouncement object encapsulates the Session Announcement Protocol (SAP) and Session Description Protocol (SDP) sections of an announcement. This interface wraps the Component Object Model (COM) object ISDP, which in turn encapsulates the SDP COM object and some SAP fields.

This interface is currently in development, pending decisions on the announcement protocol.


IDataListener : IDispatch

This is the main interface of Announcement Listener. The methods can enable or disable the program in its entirety, return the collection of filters, or submit a broadcast announcement to the scheduling queue without calling any filters.

Method | Description
get_AutoStart | Retrieves the AutoStart property, which determines whether Announcement Listener is included in the system startup.
get_Filters | A pointer to the collection of filters that are installed in Announcement Listener.
get_Running | Determines whether the reception of announcements is enabled.
IsBpcTask | Returns TRUE if a task name from the Task Scheduler was created by Announcement Listener, and FALSE if it was not. Task Scheduler is a component of Windows 98.
put_AutoStart | Stores the AutoStart property, which determines whether Announcement Listener is included in the system startup.
put_Running | Enables or disables the reception of announcements from the announcement socket.
SubmitAnnouncement | Causes Announcement Listener to unconditionally schedule the receipt of a broadcast, without the announcement being sent to the public announcement address.


IDataListener::get_AutoStart

HRESULT AutoStart(
  boolean *AutoStart  // pointer to the Autostart property
);

Return Values

Returns an HRESULT indicating success or failure.


IDataListener::get_Filters

The IDataListener::get_Filters method retrieves a pointer to the collection of filters that are installed in Announcement Listener.

HRESULT Filters(
  IFilterCollection **ppFiltersRetVal  // Pointer to the collection
                                       // of filters
);

Return Values

Returns an HRESULT indicating success or failure.


IDataListener::get_Running

This method retrieves the value of the Running property.

HRESULT Running(
  BOOL *Run  // pointer to flag that indicates whether the
             // Announcement Listener is running
);

Return Values

Returns an HRESULT indicating success or failure.


IDataListener::IsBpcTask

Given the name of a task in the Windows 98 Task Scheduler, this method indicates whether the task was submitted by Announcement Listener. This method is not used by any other component of the Broadcast Architecture, but may be used by some other application.

HRESULT IsBpcTask(
  BSTR TaskName,      // in
  boolean *pfRetVal   // out, retval
);

Parameters

TaskName
String containing a Task Scheduler task name, such as BFTP_JOB_234.
pfRetVal
Pointer to a flag that is TRUE only if the task was created by Announcement Listener.

Return Values

Returns an HRESULT indicating success or failure.


IDataListener::put_AutoStart

HRESULT AutoStart(
  boolean AutoStart  // the Autostart property
);

Parameters

AutoStart
Boolean value. Setting the AutoStart property to FALSE causes Announcement Listener to remove itself from the system startup; setting the value for the property to TRUE adds the program to the system startup. Neither value affects the currently enabled or disabled state of the program.

Return Values

Returns an HRESULT indicating success or failure.


IDataListener::put_Running

This method stores the value of the Running property.

HRESULT Running(
  BOOL Run  // flag that indicates whether the Announcement Listener
            // is running
);

Return Values

Returns an HRESULT indicating success or failure.


IDataListener::SubmitAnnouncement

The IDataListener::SubmitAnnouncement method allows an application to schedule the reception of a broadcast without an announcement being sent to the public announcement address. This method has two primary uses: to allow announcements to be distributed by other means, such as the Internet or in e-mail, and to permit filters to store announcements for presentation to a user for approval.

For example, an application might consist of a filter to store announcements that may be of interest to a user, present them to the user at some later date, and register the announcement for receipt of its broadcast at that time. Announcements delivered by this mechanism are not presented to the filters, but scheduled unconditionally for the receipt of their broadcasts.

The input parameters to this method are equivalent to the output parameters of IBroadcastFilter::Match and IBroadcastFilter::GetDisposition.

In addition to the passed parameters, SubmitAnnouncement, must be able to access the local IP address by calling the IBroadcastAnnouncment::get_LocalAddress function. Therefore; applications that use SubmitAnnouncement, must call IBroadcastAnnouncment::put_LocalAddress prior to calling SubmitAnnouncement.

HRESULT SubmitAnnouncement(
  IBroadcastAnnouncement * Announcement,  // in
  BSTR WorkingDirectory,                  // in
  BSTR Application,                       // in
  BSTR Parameters,                        // in
  long AdvanceMinutes                     // in
);

Parameters

Announcement
Pointer to the object containing the announcement.
WorkingDirectory
Working directory in which to launch the target application.
Application
File name of the application to be launched.
Parameters
String to be appended to the command line following the application name.
AdvanceMinutes
Number of minutes prior to the time the announced data arrives to launch the application.

Return Values

Returns an HRESULT indicating success or failure.

See Also

IBroadcastFilter::GetDisposition, IBroadcastFilter::Match


IFilterCollection : IDispatch

The IFilterCollection interface represents the collection of filters that are installed in Announcement Listener. This object has methods to add a filter, remove a filter, and iterate through all filters. It has the usual methods and properties for a collection: Count, _NewEnum, and Item.

Method | Description
_NewEnum | Returns an IenumVARIANT of filters.
Add | Takes the Programmatic identifier of a filter as an argument and creates a new instance of the filter.
Count | Returns the number of currently installed filters in the collection.
Item | Returns a pointer to the indexed filter.
Remove | Removes the specified filter from the list.


IFilterCollection::_NewEnum

Returns an IenumVARIANT of filters.

HRESULT _NewEnum(
  IUnknown **ppUnk  // out, retval
);

Parameters

ppUnk
Address of an interface pointer where this method returns the IEnumVariant.

Return Values

Returns an HRESULT indicating success or failure.

See Also

IFilterCollection::Count, IFilterCollection::Item


IFilterCollection::Add

The IFilterCollection::Add method is the means by which Announcement Listener creates a new instance of a given filter.

Add takes the programmatic identifier (ProgID) of a filter as an argument (for example, BPC.GenericFilter for the generic filter). Using the programmatic identifier (ProgID), Add then looks up the corresponding class identifier (CLSID), and calls CoCreateInstance, which makes a running instance of the object. If the filter is an in-process server, it runs in the process of Announcement Listener.

HRESULT Add(
  BSTR ProgID,                    // in
  IBroadcastFilter ** NewFilter,  // out
  long *plRetVal                  // out, retval
);

Parameters

ProgID
Programmatic identifier of the filter to be added.
NewFilter
Pointer to the running filter than has been created as a result of the Add method.
plRetVal
Index into the collection. This index can later be passed back as an argument to Item or Remove.

Return Values

Returns an HRESULT indicating success or failure.

See Also

IFilterCollection::Remove


IFilterCollection::Count

The Count property returns the number of currently installed filters in the collection.

HRESULT Count(
  long *plRetVal  // out, retval
);

Parameters

plRetVal
Pointer to the number of filters.

Return Values

Returns an HRESULT indicating success or failure.

See Also

IFilterCollection::Item, IFilterCollection::_NewEnum


IFilterCollection::Item

This method returns a pointer to the indexed filter.

HRESULT Item(
  long Index,                         // in
  IBroadcastFilter ** ppFilterRetVal  // out, retval
);

Parameters

Index
Index of the filter from which to retrieve information.
ppFilterRetVal
Pointer to the indexed filter.

Return Values

Returns an HRESULT indicating success or failure.

See Also

IFilterCollection::Count, IFilterCollection::_NewEnum


IFilterCollection::Remove

The Remove method takes an index into the collection, and removes the specified filter from the list.

HRESULT Remove(
  long Index   // in
);

Parameters

Index
Index into the collection specifying the filter to remove.

Return Values

Returns an HRESULT indicating success or failure.

See Also

IFilterCollection::Add


Video Enhancements

The term interactive video refers to the combination of a video program and multimedia elements such as hypertext links, graphics, text frames, sounds, and animations. The following sections are directed to those who plan to create or display interactive video using Broadcast Architecture.

These sections provide an overview of the enhancement components and their interactions, instructions on using the enhancement components to create and receive enhancement streams, and reference information for the enhancement components:

  • About Enhancements explains what enhancements are and describes the various components of the enhancement system.
  • Using Enhancements explains how to create and transmit interactive shows.
  • Enhancement Reference contains reference material on the enhancement announcement format, on the triggers that initiate enhancement actions, and on objects used to create enhancement streams.

To locate additional information on enhancing video, especially on designing and creating enhancements, see Further Information on Data Services for the Client.


About Enhancements

The following sections describe the components and procedures used with enhancements:

  • Interactive Shows explains what an interactive show is and lists some of the features you can implement.
  • Enhancement Stream discusses the script used to synchronize enhancements with video.
  • Enhancements on the Client describes the components of the broadcast client that receive and display show enhancements.
  • Enhancements at the Head End describes the components at the head end that you can use to create and broadcast enhancement streams.


Interactive Shows

An interactive show is one in which the video is accompanied by interactive content. This content can take many forms, for example:

  • Simple text.
  • Images.
  • Recurring combinations of text and images, such as rotating advertisements.
  • Animated images.
  • Sound.
  • Links to World Wide Web content.
  • More elaborate content, such as interactive chat controls that enable viewers to discuss a show with other viewers.

Because Broadcast Architecture uses Hypertext Markup Language (HTML) and World Wide Web technology as the basis for enhancements, any type of content that can be delivered over the Web can also be used as a show enhancement.

An enhancement can incorporate functionality such as rotating content, hyperlinks, Java applets, and Microsoft® ActiveX® controls. Enhancements can even interact with Microsoft WebTV for Windows by scripting a dynamic-link library (DLL) that implements a ITVControl advise sink.

Note All ActiveX controls used in enhancements must be signed. Otherwise, the ActiveX control is not displayed or run by Microsoft® WebTV® for Windows®. This additional security is to prevent unauthorized controls from being downloaded and run as enhancements. To locate information on how to sign an ActiveX control, see Further Information on Data Services for the Client.


Enhancement Stream

The enhancement stream is a script that synchronizes enhancement events with specific times during the interactive show. An enhancement event causes an action to be performed by the broadcast client. The client's response to an enhancement event are actions such as receiving a file transmission, updating program data, or displaying new enhancement content to the user.

For example, an enhancement announcement might send data about a future interactive show to the client. Controls on the client handle the announcement event and update the show listing in the Guide database.

There are three types of enhancement events currently defined:

  • Enhancement announcements, which transmit information about an upcoming interactive show.
  • FTS transmissions, which use the File Transfer Service (FTS) protocol to download enhancement files and dependencies to the client.
  • Triggers, which command the client to perform predefined actions. For example, one type of trigger causes WebTV for Windows to display a new enhancement page.

When an enhancement stream is saved to a file, the enhancement events that the stream contains are stored as stream compiler statements. To locate more information on the stream compiler language, see Further Information on Data Services for the Client.


Enhancement Announcements

Enhancement announcements inform the broadcast client that a show is interactive. Such announcements provide details about the show's enhancements, such as each enhancement's identifier, the show that the enhancement enhances, and the page that contains the enhancement's starting point. An enhancement page is a Hypertext Markup Language (HTML) page; for more information, see Creating an Enhancement Page.

When an enhancement announcement filter receives an enhancement announcement, it stores the enhancement information in the Guide database. The presence of enhancement data in a show listing in the database indicates the show is interactive. Each time that a user tunes WebTV for Windows to a new channel, WebTV for Windows checks the database to see if the new show is interactive. If it is, and the user has enhancements enabled, WebTV for Windows displays the show as interactive.

There are several types of enhancement announcements. For more information, see the following topics:

  • Future Announcements
  • Current Announcements
  • Current Channel Announcements
  • Current Time-Slice Announcements

An announcement can be stored as a text file until it is ready to be broadcast. By convention, the .ann file extension is used for announcement files. For information about how to create these files, see Creating Enhancement Announcements.


FTS Transmissions

Enhancement files and their dependencies are transmitted to broadcast clients using FTS. FTS is a component of Microsoft® NetShow™ server that can send files using a transfer mechanism based on Internet Protocol (IP) multicast that includes forward error correction (FEC).

To locate more information about FTS, see Further Information on Data Services for the Client.


Triggers

Triggers are notifications that are sent to broadcast clients at specific times during an interactive show. Triggers instigate or trigger an action on a client. For example, you can use triggers to automatically change the content an enhancement displays, as in an advertisement rotator.

Triggers are passed to the Enhancement control, which handles Broadcast Architecture–defined triggers itself and which forwards user-defined triggers to the scripts that handle them.

For more information about the triggers currently defined by Broadcast Architecture, see Enhancement Triggers.


Dependencies

Enhancement pages, like World Wide Web pages, are typically composed of several files. For example an enhancement file, MyEnh.htm, might contain graphic images in Graphics Interchange Format (GIF) and Joint Photographic Experts Group format (JPEG), ActiveX controls, FutureSplash animations, and other such files that must be downloaded for the enhancement page to display properly. These additional files are MyEnh.htm's dependencies.

You must ensure that an enhancement's dependency files are stored on the broadcast client before that enhancement is displayed. Otherwise the enhancement will appear broken. There are several strategies for handling dependencies:

  • Allocate broadcast bandwidth to transmit the dependencies and the base page together, in a cabinet file.
  • Allocate broadcast bandwidth to repeatedly download the dependencies.
  • Use another data transmission method, such as Internet channel broadcasting, to get the files onto the user's computer.
  • Have the user explicitly download or install the dependency files, either from a Web site or a portable medium such as a CD-ROM.

The first method is the recommended method for ensuring that the dependency files are loaded onto the client when the enhancement page is displayed. For more information about using cabinet files to package dependencies with their base page, see Creating a Cabinet File and EnhEvent.onefile.

The stream compiler objects also provide functionality to automatically determine the dependencies of a event, and methods that enable applications to edit the dependency list. For more information, see Editing the Dependencies of an Event.


Enhancements on the Client

The enhancement client software is part of the Microsoft® Windows® 98 operating system and is installed when the user selects the Broadcast Data Services component. This software receives and handles enhancement streams. When this software is installed and the user tunes to an interactive show, the broadcast client displays the appropriate enhancement pages and responds to enhancement events.

The following topics provide an overview of the enhancement client architecture and its components:

  • Enhancement Client Architecture illustrates the reception and flow of enhancement data on the broadcast client.
  • Enhancement Control describes the object used to handle enhancements on the client.
  • Location of Enhancement Files on the Client discusses where to place and find enhancement files on the client.
  • Enhancement Filter covers the announcement filter that processes enhancement announcements.

For more information about the head-end components used to create and broadcast the enhancement stream, see Enhancements at the Head End.


Enhancement Client Architecture

On a broadcast client, all data including enhancements is received as a stream of digital data. From this incoming stream, the video and audio data are extracted and sent to one of two types of video control. Such video controls reside in the page displayed by WebTV for Windows or a World Wide Web browser. The two possible types of video control are Video controls and Enhancement Video controls.

At the same time video is received by its control, enhancements and triggers are received by an Enhancement control. An Enhancement control is an ActiveX control that responds to enhancement stream events. Like the video controls. the Enhancement control is hosted in an enhancement page displayed by WebTV for Windows or a World Wide Web browser.

The following illustration shows this process. Note that this diagram is simplified and does not display controls internal to Broadcast Architecture.

You can create enhancements that interact with Enhancement controls by embedding script or custom controls in the enhancement page. These Web applications can call methods of the Enhancement control and respond to the control's events. To locate more information about using the Enhancement control, see Further Information on Data Services for the Client.


Enhancement Control

An Enhancement control is an ActiveX control that can be embedded in enhancement pages to receive and respond to triggers.

When WebTV for Windows displays an interactive show, it tunes the Enhancement control to the Internet Protocol (IP) address and port specified in the enhancement data stored in the Guide database. (This enhancement data is stored as a result of a prior enhancement announcement.) The Enhancement control monitors this IP stream for triggers. When the control receives a trigger, it checks whether that trigger is defined by Broadcast Architecture or by a user.

The control handles Broadcast Architecture–defined triggers itself. For example, if a content provider transmits a Nav trigger, the Enhancement control causes WebTV for Windows to display new enhancement content. For each user-defined trigger, the control sends an event to its container Web page. Script embedded in that Web page can then handle the user-defined trigger event.

To locate more information about using the Enhancement control, see Further Information on Data Services for the Client.


Location of Enhancement Files on the Client

Enhancement files can be stored in either of two folders, the spool folder or the base page folder.

Spool Folder

The spool folder is where all enhancement files are received during a broadcast. The spool folder is created during the installation of Broadcast Architecture. The location of this folder is stored on the client in the following registry key:

HKLM\Software\Microsoft\TV Services\Enhanced Content.

For each interactive show episode for which data is received, the Enhancement control creates a subfolder, called an episode folder, within the spool folder. The control gives the episode folder a unique name, for example, "MyEnhShow.5". The control then saves the enhancement files for that show episode in the episode folder.

The episode folder can be further divided into subfolders. Files relating to a particular episode's enhancements are named relative to the episode folder. For example, if the Enhancement control receives the transmitted file Images\Logo.jpg, then the control creates a folder called Images within the episode folder, if it does not already exist. The control then writes the file Logo.jpg to that folder.

Base Page Folder

The base page folder is the folder that contains the Hypertext Markup Language (HTML) page that resides at the top level or base of the enhancement pages currently loaded into the user's Web browser. The base page is also known as the preload URL. The location of each enhancement's base page is stored in the Guide database. When WebTV for Windows tunes to an interactive show, it retrieves this information from the database and passes it to the Enhancement control.

The Enhancement control determines the base page folder, by examining the Uniform Resource Locator (URL) of the base page and extracting the path information. The control then uses that path as the base page folder. If a base page is broadcast along with other enhancements for a show episode, then the base page folder is the same as the episode folder. However, the base page can also reside in some other directory on the broadcast client.

When the Enhancement control receives a trigger to navigate to a file, the control first looks for that file in the episode folder, or a subfolder of the episode folder if one is specified. If the file is not found there, the control next looks in the base page folder, if that is different from the episode folder. An episode may use a combination of enhancement files from the episode folder, the base page folder, or both.

If the file the client is searching for is not found in either the episode or base page folder, the Enhancement control displays an error message if the control is created in Internet Explorer (authoring mode), and does nothing if the control is created in WebTV for Windows (normal mode).


Enhancement Filter

The enhancement filter is an Announcement Listener filter that processes enhancement announcements. Enhancement announcements contain data about an interactive show, such as the file name of the base page, the name of the enhancement, and the show reference of the interactive show.

Only one instance of the enhancement filter should run on a broadcast client at any time. Additional instances after the first do not receive enhancement announcements and slow performance. This functionality exists because the Announcement Listener compares the type of each incoming announcement against all registered filters. The presence of multiple enhancement filters thus increases the number of comparisons the Announcement Listener must perform.

When the enhancement filter receives an announcement, it calls an internal object of Broadcast Architecture to load the enhancement data into the Guide database. Components such as WebTV for Windows, and certain third-party applications, check for this information to determine whether a show is interactive and to locate its base page.

Note The data passed to the enhancement filter through announcements specifies only parameters for the enhancement to come. This data does not contain actual content, such as enhancement HTML files. Enhancement files are broadcast to the user's computer by means such as File Transfer Service (FTS) transmissions, Internet channel broadcasting, and so on.

There are several types of enhancement announcements. These types are described in the following topics.

Future Announcements

Future announcements contain information about an upcoming enhancement, either for a show, channel or timeslice. These announcements fully specify all data for the enhancements to come, including the Internet Protocol (IP) multicast address, port, ending time, base page, and show reference. The enhancement filter loads this data into the Guide database by calling an internal Broadcast Architecture object.

Current Announcements

Announcements for current broadcasts contain information about the enhancement for the show which the viewer is currently watching. If the viewer tuned to the show in the middle of the broadcast, they may not have received the initial enhancement trigger at the beginning of the show. Current enhancement announcements provide a method for WebTV for Windows and third-party applications to start an enhancement while the related show episode is in midstream.

Current announcements can also be used when a show's broadcast time is not known. For example, video and its enhancement stream (which includes the announcements) might be recorded to tape for later broadcast. Using current announcements ensures the announcements work no matter when the show is broadcast.

Current announcements expire immediately; in other words, their expiration date is the same as their transmission date. This functionality ensures the Announcement Listener re-receives each broadcast of the current enhancement announcement. Otherwise, the default behavior of the Announcement Listener is to ignore duplicate announcements.

Current enhancement announcements are different from future enhancements in that they specify the episode's ending time as the episode length plus 5 minutes, instead of as a fixed time. For example, a future enhancement announcement might specify the ending time as 1/26/98 12:00:00, whereas a current enhancement announcement might specify it as 35 minutes.

When the enhancement filter receives a current enhancement announcement, some further computation and data gathering must be performed. The enhancement filter calculates the episode's ending time and passes the connection information to the internal Broadcast Architecture object that loads the episode into the Guide database.

If the announcement does not specify the show reference for the episode, or the Uniform Resource Locator (URL) for the base page (in other words, the URL from which enhancements are preloaded, or the preload URL), an internal Broadcast Architecture object gets this information from the Enhancement control. When the enhancement information is complete, an internal object loads the enhancement data into the Guide database.

Current Channel Announcements

Current channel announcements contain information about an enhancement that enhances the current channel. Like current announcements, current channel announcements expire immediately and can derive some enhancement information from the client. To announce future channel enhancements, use a future announcement.

A channel enhancement enhances a particular channel. For example, MSNBC might create a channel enhancement that displays MSNBC-related content, such as which shows are up next, news items, or sports scores. This enhancement would be displayed any time the viewer tuned to MSNBC.

If an interactive show is broadcast over a channel that is enhanced, the viewer can choose to watch either the show or the channel enhancement.

Current Timeslice Announcements

Current timeslice announcements contain information about an enhancement that enhances the current channel for a set length of time. Like current announcements, current timeslice announcements expire immediately and can derive some enhancement information from the client. To announce future timeslice enhancements, use a future announcement.

A time-slice enhancement runs for the specified length of time regardless of which shows are displayed. An example of a time-slice enhancement is an enhancement that plays for the first four hours of Saturday morning cartoons. This enhancement continues to play even though individual cartoon shows start and end during that period. Broadcasters can use time-slice enhancements to package related shows together and create an extended viewing experience.

If an interactive show is broadcast over a channel that is enhanced, the viewer can choose to watch either the show or the channel enhancement.


Enhancements at the Head End

Interactive shows are broadcast by the content provider. Producers at the head end design and develop the enhancement stream for a show. This stream scripts the enhancement events (such as downloading HTML pages, displaying a new page, and so on) to synchronize to specific times during the show.

The head end broadcasts the television show, with its accompanying enhancement stream, to the broadcast client. The client handles the enhancement stream events and displays the show's enhancements.

The architecture of the enhancement head end is not defined by Broadcast Architecture. As long as the head end broadcasts the enhancement stream events using the correct formats, clients can display the enhancements. Typically, the head-end architecture consists of stream authoring tools and an application that broadcasts the enhancement stream over a Microsoft Multicast Router.

Because of this flexibility in head-end design, the production staff at the head end can choose an authoring environment that suits their procedures. For example, if their process is to write the enhancement stream directly in stream compiler syntax, the authoring tool might simply be a text editor. On the other hand, a content provider can develop custom tools to automate the stream authoring process. Similarly, those setting up the head end can create an application to broadcast the enhancement stream.

The Design Kit for the Microsoft® Broadcast Architecture compact disc provides several objects that you can use to build custom enhancement authoring and broadcasting tools. These objects are described in the following topics:

  • Stream Compiler Objects, which describes objects you can use to build custom stream authoring tools.
  • Enhancement Sender Object, which describes the object used to transmit enhancement events and files using Internet Protocol (IP). This transmission can occur across a broadcast medium such as a Microsoft® Multicast Router or a local area network (LAN).

For more information about the required formats for transmitting enhancement stream events, see Enhancement Announcement Format, Enhancement Triggers, and the File Transfer Service (FTS) documentation. To locate the FTS documentation, see Further Information on Data Services for the Client.


Stream Compiler Objects

The stream compiler objects are a set of Component Object Model (COM) objects that provide functionality to create, edit, and save enhancement streams. You can use these objects to create authoring tools to work with enhancement streams. For example, using these objects you can create tools such as a custom editor for enhancement streams or a stream player to view and test your interactive show.

Essentially, the stream compiler objects wrap the stream compiler syntax, exposing the syntax so its component parts can be easily accessed by applications. In addition, the compiler objects provide some syntax validation. While it is possible to write authoring tools that do not use the stream compiler objects, using them greatly simplifies the task.

The stream compiler's object library contains the following objects:

  • EnhEvent, an object that wraps information about a particular enhancement event, such as an announcement, File Transfer Service (FTS) transmissions, or trigger.
  • EnhEvents, a collection of EnhEvent objects. Using the EnhEvents object, you can manipulate the entire stream of events. You can rearrange events, search for a specific event, set default values, load or save the stream to a file, and so on.
  • Annc, an object that wraps an enhancement announcement.

Another object useful when writing enhancement tools is the enhancement sender object, ipsend. This object connects to the broadcast medium and can transmit all three types of enhancement events: announcements, FTS transmissions, and triggers.


EnhEvent Object

An EnhEvent object contains information about a single enhancement event, such as sending an announcement or downloading a file. Using EnhEvent objects, you can create enhancement authoring tools that programmatically get and set the parameters of events in the enhancement stream.

Each EnhEvent object in the enhancement stream corresponds to a line of stream compiler syntax. In essence, an EnhEvent object wraps a line of syntax, exposing the various keywords and parameters so that they can be easily accessed by applications such as authoring or syntax-validation tools.

The entire set of enhancement events for a show, also known as the enhancement stream, is stored as a set of EnhEvent objects in the EnhEvents collection. An EnhEvent object must be part of an EnhEvents collection. In other words, you do not create stand-alone instances of EnhEvent objects. Instead, you create EnhEvent objects by calling methods of the EnhEvents collection.

For more information on working with EnhEvent objects, see the following topics:

  • Creating an Enhancement Stream
  • Adding Events to an Enhancement Stream
  • Adding User-Defined Comments to an Event
  • Editing the Dependencies of an Event
  • Converting Events to Low-level Syntax


EnhEvents Collection

The EnhEvents collection represents the enhancement stream as a whole. It contains the complete set of EnhEvent objects that define the enhancement stream. Using EnhEvents, you can create enhancement authoring tools that programmatically add, edit, and delete events in the enhancement stream.

In addition to containing the EnhEvent objects, EnhEvents exposes properties to set global variables relating to the stream as a whole, such as the bandwidth required to transmit the stream. EnhEvents also provides utilities such as syntax validation and time format conversion.

For more information on working with the EnhEvents collection, see the following topics:

  • Creating an Enhancement Stream
  • Adding Events to an Enhancement Stream
  • Editing and Deleting Events in an Enhancement Stream
  • Including One Enhancement Stream in Another
  • Converting Events to Low-level Syntax
  • Loading or Saving an Enhancement Stream


Annc Object

The Annc object wraps an enhancement announcement. The fields of the announcement are stored as properties in the object. The Annc object also provides file-access methods that enable your application to save an announcement to a file or load an announcement from a file.

Saving an announcement to a file enables you to broadcast the announcement at a later time, as is typically the case. Announcements are saved as text files. By convention, announcement files have the extension .ann.

For more information see the following topics:

  • Creating Enhancement Announcements explains how to create announcement files.
  • Enhancement Announcement Format describes the SAP/SDP fields specific to enhancement announcements. These fields correspond to the properties of the Annc object.
  • Annc contains reference topics which describe the methods and properties of the announcement object.


Enhancement Sender Object

The enhancement sender object, ipsend, is an object that you can use to transmit the enhancement stream over a broadcast medium such as a Microsoft Multicast Router, other multicast router or LAN. The ipsend object supports three separate Internet Protocol (IP) connections, one each for enhancement announcements, triggers, and FTS transmissions.

For more information on working with ipsend, see Broadcasting an Enhancement.


Using Enhancements

By adding enhancements to video, you can make a presentation richer in content and more interactive. The following sections explain the technical processes involved in creating, transmitting, and receiving an interactive show:

  • Creating an Enhancement Page provides information on creating an enhancement page.
  • Creating an Enhancement Stream describes how to create a script that synchronizes the transmission and display of your enhancements with the interactive show.
  • Using the Stream Compiler Objects illustrates how to use the stream compiler objects to manipulate enhancement streams. This section covers such topics as adding events to an enhancement stream, merging enhancement streams, and so on.
  • Broadcasting an Enhancement describes how to use the ipsend object to broadcast enhancements to clients.
  • Creating a Cabinet File explains how to use the EnhCab object to create and populate cabinet files.
  • Monitoring the Status of an Enhancement Control describes how to monitor the status of an enhancement control running in the same process as an ipsend object.

For more information about creating custom tools to generate and edit the enhancement stream, see Building Enhancement Authoring Tools.


Creating an Enhancement Page

Enhancement pages are Hypertext Markup Language (HTML) files that format enhancement content, such as images and text, for display. If you want to develop applications that receive enhancements and you know how to create interactive World Wide Web pages, you already have most of the information you need. The interactive video supported by Broadcast Architecture is based on technologies you already know: HTML, Microsoft® ActiveX® controls, and Microsoft® Visual Basic® Scripting Edition (VBScript) or Microsoft® JScript™ development software.

To locate additional information about designing and creating enhancements for shows, see Further Information on Data Services for the Client.

Note All ActiveX controls used in enhancement pages must be signed. Otherwise the ActiveX control is not displayed or run by Microsoft WebTV for Windows. This additional security is to prevent unauthorized controls from being downloaded and run as enhancements. For information on how to sign an ActiveX control see, Further General Information.


Creating an Enhancement Stream

An enhancement stream is a script that synchronizes enhancement events with specific times in the interactive television show. An enhancement event causes the broadcast client to perform an action such as receiving a file transmission or displaying new enhancement content to the user. The enhancement stream script is written in stream compiler syntax and stored as a text file. If you are planning to broadcast an interactive show, you need to create an enhancement stream.

The enhancement stream coordinates enhancement actions with the video being broadcast. For example, your enhancement stream script can ensure that files are transmitted prior to their display, that triggers occur at specific times during the show, and that important files are repeatedly transmitted so they are always available to the viewer.

There are three methods that you can use to build an enhancement stream:

  • Write the stream explicitly using stream compiler syntax and save it as a text file. This method requires fluency in stream compiler syntax and advanced knowledge of the broadcast client system. You may still want to use a tool to validate your syntax, convert the stream to low-level syntax, or both. For more information about working with stream compiler syntax, see Converting Events to Low-level Syntax, which describes how to convert a stream to low-level format, or Further Information on Data Services for the Client, which directs you to additional syntax documentation.
  • Use the Enhancement Stream Editor to create an enhancement stream. This tool displays the enhancement stream as a time line and assists you in budgeting the available bandwidth for enhancement transmission. To locate more information on the Enhancement Stream Editor, see Further Information on Data Services for the Client.
  • Create a custom stream editor tailored to your needs, and use that to create an enhancement stream. For more information, see Building Enhancement Authoring Tools.

The order and composition of your enhancement stream depends on the content and structure of your interactive show. However, you should keep in mind the following guidelines when composing an enhancement stream:

  • Send an enhancement announcement for the interactive show before it begins and repeatedly during the show. Doing so loads the enhancement information into the Guide database, where it can be retrieved and used by WebTV for Windows and by third-party applications that use Guide database information.
  • Schedule dependencies to be broadcast before the enhancement page that requires them.
  • Ensure that your application broadcasts the files referred to by Nav triggers to the client before it broadcasts the triggers themselves. Doing so ensures that you only redirect Microsoft® WebTV® for Windows® to display files that are available.
  • Repeatedly transmit critical enhancement events. If users tune to an interactive show in the middle of the episode, they may miss events broadcast earlier in the show. Repeatedly broadcasting enhancement files and triggers enables WebTV for Windows to receive and display enhancements even when a user was tuned to another channel for part of the episode.


Using the Stream Compiler Objects

The stream compiler objects are a set of Component Object Model (COM) objects that provide functionality to create, edit, and save enhancement streams. You can use these objects to create enhancement stream authoring tools.

The following topics illustrate how to use the stream compiler objects to implement various types of stream-authoring functionality:

  • Adding Events to an Enhancement Stream explains how to use the stream compiler objects to add events to an enhancement stream.
  • Locating an Event in the Enhancement Stream explains how to find a particular event in the enhancement stream.
  • Editing and Deleting Events in an Enhancement Stream explains how to change or remove an event from the enhancement stream.
  • Creating Enhancement Announcements describes how to create the enhancement announcement files that are transmitted during an announcement event.
  • Adding User-Defined Comments to an Event explains how to add subevents to an event using the stream compiler objects.
  • Editing the Dependencies of an Event describes how to modify the dependencies files of an event. You can use this to set custom dependencies for the event, or to modify the dependency list generated by the stream compiler objects.
  • Including One Enhancement Stream in Another describes how to include enhancement streams within other enhancement streams. You can use this technique to combine enhancement streams, or to build a playlist that runs several shows.
  • Merging Enhancement Streams explains how to combine events from two or more enhancement streams into a single stream.
  • Converting Events to Low-level Syntax describes high-level and low-level stream syntax and explains how to convert an enhancement stream or event to low-level format.
  • Loading or Saving an Enhancement Stream explains how to read an enhancement stream from a text file and save the stream to disk.

For more information on building stream-authoring applications, see Building Enhancement Authoring Tools.


Adding Events to an Enhancement Stream

An enhancement stream comprises a set of events that occur during the show that is interactive. You create or extend a stream by adding events to it. These events can be represented either by lines of stream compiler syntax or by EnhEvent objects.

If you are writing a stream authoring tool, you can use the stream compiler objects to create the stream. Using these objects, the enhancement stream is saved to a text file in the stream compiler language. An alternative to using the stream compiler objects is to create and edit a text file containing lines of stream compiler languages. Because the stream compiler objects already implement much of the functionality required to create and save an enhancement stream, it is recommended that you use them to build your authoring tools.

Using the stream compiler objects, you can add events to the enhancement stream by calling either the EnhEvents.AddText or EnhEvents.Add method. Both methods create a new EnhEvent object and add it to the stream, as represented by an EnhEvents collection.

The methods differ, however, in how they initialize the new EnhEvent object. EnhEvents.AddText initializes the event using the stream compiler syntax specified when AddText is called, whereas EnhEvents.Add initializes the event using a specified starting time and EnhEvent.Name property value.

The following example demonstrates adding events to the stream using EnhEvents.AddText and EnhEvents.Add.

Dim evs as IEnhEvents
Dim e As IEnhEvent
Set evs = New EnhEvents

'Use AddText to add an event that downloads File1.htm thirty seconds
'after the show starts.
evs.AddText("30.0 ""File1.htm"";")

'Use Add to add an event that downloads File2.htm sixty seconds after
'the show starts.
evs.Add 60, "File2.htm"


Locating an Event in the Enhancement Stream

The stream compiler objects provide several ways to locate an event in the enhancement stream. You can locate the event most recently added to the stream or locate an event by its start time or handle.

To locate the most recently added event, call the EnhEvents.LastAdd method. This returns the event that was last added to the enhancement stream. The following example illustrates this where evs is an EnhEvents collection and e is an EnhEvent object variable.

Set e = evs.LastAdd

To locate an event by its start time, call the EnhEvents.FindTime method and specify the time of the event. The start time of an event is stored in the EnhEvent.Start property. The following example finds an event by its start time and stores the event in the object variable e.

'Find the event that starts at 00:05:42:00
Set e = evs.FindTime (342.0)

There are some considerations when finding an event by its start time. The start time of an event can change slightly as new events are added to the stream. This is because the stream compiler objects may have to rebudget the available bandwidth to fit the new events in. In addition, multiple events may have the same start time. If your application needs to be able to recall a specific event multiple times it is more robust to recall the event by its handle instead of its start time.

An event handle uniquely identifies the event within the stream. Unlike the start time, the handle of an event does not change. The event handle is stored in the EnhEvent.Handle property. To locate an event using its handle, call the EnhEvents.FindHandle method.

If you need to locate an event by some other criteria, such as locating an event by the value of its EnhEvent.Name property, you will have to implement a search through the stream explicitly. This is illustrated in the following example which searches the stream for an event by Name.

Dim FoundHandle As Long

'Search through the EnhEvents collection for the event
For Each e in evs
  If (e.Name = FindStr) Then
    'Insert code to utilize the found event.
    '...

    'Store a handle to the event for later recall. (optional)
    FoundHandle = e.Handle
  End If
Next e

Extending the preceding example, you could use the following to recall the event found previously and store it in the object variable e.

Set e = evs.FindHandle(FoundHandle)


Editing and Deleting Events in an Enhancement Stream

After your application has added events to the enhancement stream, it may need to modify or delete these events. To do this, you must first locate the event as described in Locating an Event in the Enhancement Stream.

Once you have located the event, you can edit the event by changing the values of its properties. The following example retrieves the last-added event in a stream and changes its Timeout property to 15 seconds.

Set e = evs.LastAdd
e.Timeout = 15

For a complete list of the properties that you can edit, see EnhEvent.

To delete an event from the enhancement stream, locate the event and then call its EnhEvent.Delete method. This is demonstrated in the following example.

'TODO: locate event
'delete the event from the stream
e.Delete

You cannot access the event once it has been deleted. To verify the event was deleted, check that the EnhEvents.Count property is decremented.


Creating Enhancement Announcements

Adding an announcement event to the stream is the first part of creating an enhancement announcement. This is demonstrated in the following example:

e.Text = "00:00:00.50 announce ( ""MyAnnc.ann"" ) ;"

Note that the announcement event references a file, in this example MyAnnc.ann. This file is a text file that contains the announcement's field and attribute values. By convention, announcement files use the .ann file extension. Before you can broadcast an announcement to the client, you must generate such an announcement file.

The stream compiler object library provides an object, Annc, that your application can use to create and edit announcement files.

To create an announcement file
  1. Create an instance of an Annc object.
  2. If you want to edit a pre-existing announcement, use Annc.Load to read the announcement's properties into the Annc object. If you are creating a new announcement, skip this step.
  3. Set the object's properties to reflect the field values you want to set in the announcement. For more information about the properties available see, Annc.
  4. Save the announcement to a file using Annc.Store. This persists the announcement to a text-based .ann file that can then be transmitted to broadcast clients.

Similarly, you can also use the files generated by the Annc object to transmit delete announcements. Delete announcements rescind previously-transmitted announcements. The following example illustrates creating a delete announcement event that undoes the announcement event of the previous example.

e.Text = "00:00:00.50 delannounce ( ""MyAnnc.ann"" ) ;"


Adding User-Defined Comments to an Event

You can add custom data strings to an event. These strings can be used either as comments or to store custom syntax to be processed internally by your authoring tool. The stream compiler objects delete these user-defined strings when the stream is converted to low-level syntax or saved to a file.

User-defined strings are stored in the event as microevents. A microevent is an event within an event.

For example, the following example adds an event that contains two microevents. The first microevent specifies that a file be downloaded, and the second stores a user-defined string. Note that the keyword userdef identifies the second microevent as a user-defined string. To locate more information about userdef and other stream compiler syntax, see Further Information on Data Services for the Client.

evs.AddText("0:32.0 { file1.htm userdef ""This is a user-defined string"" };")

You can access microevents using the EnhEvent.Attr and EnhEvent.Opcode properties. EnhEvent.Attr contains a collection of the microevent's text. For example, the following example extending the preceding one displays two message boxes, each containing the text of a microevent.

Dim e As IEnhEvent
Set e = evs.LastAdd()
Msgbox e.Attr(0)       'Displays "file1.htm"
Msgbox e.Attr(1)       'Displays "This is a user-defined string"

You can set or retrieve the type of microevents using EnhEvent.Opcode. This property contains a collection of flags identifying the microevent types. The preceding example sets e.Opcode(0) to EVOPdownload and e.OpCode(1) to EVOPuserdef. EVOPdownload is a numerical flag that specifies that the microevent is to download a file, and EVOPuserdef specifies a user-defined string.

If you change the type of a microevent, you typically must also change the corresponding text. This requirement comes from the fact that different stream compiler syntax is required for different kinds of events. To locate more information on stream compiler syntax, see Further Information on Data Services for the Client.

The number of microevents available in a event is enumerated by the property EnhEvent.AttrCount. In the previous example, e.AttrCount returns 2.

You can add a microevent to an event using either EnhEvent.Attr or EnhEvent.Opcode. To do so, set the value of a microevent with an index equal to the value of EnhEvent.AttrCount. Because microevent collections are zero-based, this index value is one greater than the value of the last microevent. Setting a value to this index adds a new microevent and increments EnhEvent.AttrCount. Note that you cannot add microevents at indexes greater than EnhEvent.AttrCount. You can only add one microevent at a time.

The following example adds a microevent to the event created preceding.

index = e.AttrCount

'Create a new microevent of type EVOPuserdef
'and increment e.AttrCount by 1.
e.Opcode(index) = EVOPuserdef

'Set the text of the new microevent
e.Attr(index) = "This is another user-defined string"

Note Microevents that follow user-defined strings should only other be user-defined strings. In other words, you should not follow a user-defined string microevent by a microevent of any other type. The stream compiler objects return a syntax error if the microevents following a comment are anything but additional user-defined strings.

For example, the following causes the stream compiler objects to return a syntax error because the second file transmission, File2.htm, microevent occurs after user comment.

evs.AddText("0:32.0 { file1.htm userdef ""A user comment"" file2.htm};")

Both of the following examples, however, are syntactically correct.

evs.AddText("0:32.0 { file1.htm file2.htm userdef ""A user comment"" };")
evs.AddText("0:32.0 { file1.htm userdef ""A user comment"" userdef ""Another comment""};")


Editing the Dependencies of an Event

Any event that depends implicitly on one or more other events to function correctly has dependencies. An example is an event that downloads an enhancement page that contains an image. If the image file is not also downloaded, the page will appear broken when it is displayed. The image file is a dependency of the page-download event.

The stream compiler objects can automatically calculate the dependencies of an event. In addition, they provide properties that your application can use to set or edit an event's dependencies.

For example, your application might edit a dependency list when there are two consecutive events that depend on the same image file. You could edit the dependencies of the second event to remove the reference to the shared image file since it will already have been downloaded as a dependency of the first event.

There are two ways in which your application can create a dependency list for an event:

  1. Call EnhEvent.Flatten on an event which does not have a dependency list. This causes the stream compiler objects to automatically calculate the event's dependencies.
  2. Explicitly set dependencies for an event using the EnhEvent.Depend array.

Once a dependency list has been generated, it is stored in the text of the event. For example, in the following, the file First.htm depends on three image files: Red.gif, Green.gif, and Yellow.gif.

before 00:00:20.00 "First.htm" only depends("red.gif" "green.gif" "yellow.gif");

The dependency list is stored in the event text to alert the stream compiler objects that dependencies have already been determined for this event and do not need to be re-calculated.

You can edit an event's dependency list using EnhEvent.Depend. Depend is an array of strings containing the path and filename of each dependency file. For example, the preceding event sets Depend(0) to "Red.gif", Depend(1) to "Green.gif", and Depend(2) to "Yellow.gif". A related property, EnhEvent.DependCount, returns the number of dependencies currently set for the event.

To delete a dependency from an event, set its path and filename to an empty string. When you do this, the stream compiler objects delete the empty dependency from the list and re-index the remaining array elements.

The following deletes all of an event's dependencies.

'Delete all the dependencies of an event.
While e.DependCount > 0
    e.Depend(0) = ""
Wend

Note that in the preceding example the index is always 0. Because the dependency array is re-indexed after each element is removed, incrementing the index would cause the array to go out of bounds.

When adding dependencies to an event, you can only add one dependency to the list at a time and only at the end of the array.

'Adding a new dependency to an event
e.Depend(e.DependCount) = "Another.gif"

If you set a value in the middle of the dependency array, it overwrites the previous value.

'Overwriting a previous dependency value.
e.Depend(1) = "Another.jpg"


Including One Enhancement Stream in Another

You can include pre-existing enhancement streams in the current stream. Doing so causes the entire contents of one stream file to be inserted into another stream. You can use this functionality, for example, to build up a playlist that runs several shows. You do so by including the stream files for all shows in one stream.

To include an enhancement stream, simply specify the include keyword followed by the file name of the stream you want to include. You can specify include either by adding an event to a stream using the EnhEvents.AddText method, or by editing the text of an existing event using the EnhEvent.Text property. In other words, you can add the included stream either as a new event or as part of an existing event.

For example, the following example uses the stream compiler objects to build a playlist that encompasses three shows, Show1, Show2, and Show3.

Dim evs as IEnhEvents
Set evs = New EnhEvents
evs.AddText("0 include ""Show1.str"";")
evs.AddText("30:0.0 include ""Show2.str"";")
evs.AddText("1:00:0.0 include ""Show3.str"";")

The times specified in the inserted streams are relative to the time specified in the event that includes them in the existing stream. For example, the events in Show2.str occur relative to 30:0.0, the events in Show3.str relative to 1:00:0.0.

You can also repeatedly include a stream. For example, the following example causes the contents of Stream1.str to be inserted into the current stream every 30 minutes until 3:31, or five times.

evs.AddText("1:30:00.0 include ""Stream1.str"" repeat 30:0.0 until 3:31:00.0;")

The timing of the events in Stream1.str is relative to the time specified during the include operation. In the previous example, the start times for each repetition are 1:30:00:00, 2:00:00:00, 2:30:00:00, and so on.

To test whether an event includes a stream file, you can use the EnhEvent.IsInclude property.

To locate additional information on include and other stream compiler syntax, see Further Information on Data Services for the Client.


Merging Enhancement Streams

Merging enhancement streams causes the two streams to be interleaved by event time. For example, if you have a stream with events A and B occurring at 15 and 30 seconds after start, and a second stream with events C and D occurring at 20 and 45 seconds after start, the merged stream has events in the order A, C, B, and then D.

This functionality can be useful if your application needs to combine events from different stream files. For example, if one stream contains only announcement events and the other only trigger events, you can merge the two streams to create a stream that contained both types of events.

Merging enhancement streams is different from including one stream in another. When you include an enhancement stream in another, the timing of the events in the included stream is relative to the time of the event that includes the stream. When you merge a stream into a pre-existing stream, the timing of events in the merged stream is relative to the starting time of the pre-existing stream.

To merge an enhancement stream into the current stream, call the EnhEvents.Load method and specify the file name of the stream that you want to merge into the current stream. The events in the new stream are merged with the events specified in the EnhEvents collection for the current stream. The following example demonstrates this functionality.

Dim evs As IEnhEvents
Set evs = New EnhEvents

'Load the first stream
'This example loads a pre-existing stream to simplify the code.
'You can also create a new stream and add events to it.
evs.Load("Stream1.str")

'merge Stream2 with Stream1
evs.Load("Stream2.str")

If you want the timing of the events in the merged stream to be relative to a time other than the starting time of the pre-existing or newly created stream, you can set the timing offset in the EnhEvents.LoadBias property. The following example merges a third stream into the previous example. The timing of events in the third stream is relative to the thirtieth minute of the show.

evs.LoadBias = evs.ParseTime("30:00.0")
evs.Load("Stream3")

The preceding example uses EnhEvents.ParseTime method to convert the time, formatted as a string, to a Double value. You can alternately specify the offset time in seconds. The following example performs processing identical to that of the preceding.

evs.LoadBias = 1800
evs.Load("Stream3")

Set LoadBias back to zero when you no longer require an offset, otherwise, all subsequently loaded streams will be offset by LoadBias seconds.

If you wish to load a second stream without merging it into the current stream, you can call EnhEvents.Clear to empty the stream of events before you load the second stream. This causes the second stream to replace the previously-loaded stream instead of merging with it.


Converting Events to Low-Level Syntax

You can write stream compiler language statements in either high-level syntax or low-level syntax. Writing the stream in high-level syntax enables you to compactly specify multiaction events. This makes the stream easier to create and read. If, however, you use ipsend to transmit the events ipsend transmits the events as low-level events. Because of this, you should convert the stream to low-level syntax before you transmit it.

Converting a stream to low-level syntax breaks each compound event into its constituent events. For example, the following stream uses high-level syntax to indicate that two files and their dependencies should be broadcast and that the second file, Second.htm, should be broadcast repeatedly for the first thirty minutes of the show.

before 00:00:20.00 "First.htm";
00:00:21.00 "Second.htm repeat 300 until 1800;

When this statement is converted to low-level syntax, it is broken into the following set of events, assuming that the red.gif, green.gif, and yellow.gif files are dependencies of the First.htm file:

00:00:04.98 "yellow.gif" only Group "7865584";
00:00:09.98 "green.gif" only Group "7865584";
00:00:14.99 "red.gif" only Group "7865584";
before 00:00:20.00 "First.htm" only depends("red.gif" "green.gif" "yellow.gif") Group "7865584,head";
00:00:21.00 "Second.htm" only Group "7865712,head";
before 00:05:21.00 "Second.htm" only Group "7865712";
before 00:10:21.00 "Second.htm" only Group "7865712";
before 00:15:21.00 "Second.htm" only Group "7865712";
before 00:20:21.00 "Second.htm" only Group "7865712";
before 00:25:21.00 "Second.htm" only Group "7865712";

Note The Group and depend microevents in the low-level version of the stream are added by the stream compiler objects when the stream is converted to low-level syntax. These microevents store information that enables the stream compiler objects to reassemble the stream into high-level format.

To convert an enhancement stream from high-level syntax to low-level syntax, your application can call EnhEvents.Flatten. The EnhEvents.UnFlatten method reverses the process, converting a previously-flattened stream back into its original high-level syntax.

Note that UnFlatten uses the Group values when rebuilding the events. If your application alters or changes these values, the UnFlatten method may fail or produce unexpected results.

For example, the following loads an enhancement stream from the file EnhStr.txt, converts the stream to low-level syntax, and then saves the low-level stream to the file EnhStrFlat.txt.

Dim evs As IEnhEvents
Set evs = New EnhEvents
evs.Load("C:\EnhTools\EnhStr.txt")
evs.Flatten
evs.Store("C:\EnhTools\EnhStrFlat.txt")

Note The Group information that the stream compiler objects use to re-assemble flattened streams is based on handle values and is not guaranteed to be unique if the stream is stored and then reloaded. Because of this, you should avoid unflattening streams loaded from a file.

In addition to converting the entire stream to low-level syntax you can convert a single event in the stream. To do this use the EnhEvent.Flatten method. Use this method instead of EnhEvents.Flatten when you only need to convert a single event. For example, if you wanted the stream compiler objects to generate a dependency list for a single event in the stream, you could use EnhEvent.Flatten and save the processing overhead of converting the entire stream.

To convert a single event back into high-level syntax, use EnhEvent.UnFlatten. This causes all events that were part of the original, high-level, event to be recombined into a single event. In other words, all events that have the same Group number as the event on which you called UnFlatten are converted back into a single high-level event.

Because EnhEvent.UnFlatten uses the Group information to rebuild the event, your application should not alter this information. If it does, UnFlatten may fail or produce unexpected results.

You can only call EnhEvent.Flatten and EnhEvent.UnFlatten for events that are part of an enhancement stream. Calling these methods on events that are not part of the enhancement stream causes the methods to return an error.


Loading or Saving an Enhancement Stream

Enhancement streams can be stored as lines of stream compiler syntax in a text file. By convention, such a file has the extension .str. Storing a stream is useful if your application needs a stream for later use, or needs to modify a previously created stream.

To save a stream to a file, your application calls the EnhEvents.Store method and specifies a file name for the stream. The EnhEvents collection then stores the stream in the specified text file. If the file does not currently exist, Store creates it. If the file exists, it is overwritten.

Your application can read an enhancement stream from a file by calling the EnhEvents.Load method. If your application loads an enhancement stream from a file into an EnhEvents object that already contains an enhancement stream (that is, one or more EnhEvent objects), the two streams are merged. You can delete an enhancement stream by calling the EnhEvents.Clear method.

For more information on merging streams, see Merging Enhancement Streams.


Broadcasting an Enhancement

Once you have created enhancement files, authored an enhancement stream, and converted the stream to low-level syntax, the next step is to broadcast your enhancements and their associated video to clients.

To broadcast enhancement data (such as announcements, files, and triggers) to clients, you can use the enhancement sender object, ipsend. Enhancements can be broadcast over any medium that supports the Internet Protocol (IP), including IP multicast routers and local area networks.

Broadcasting an enhancement consists of the following steps:

  1. Connecting to an IP broadcast protocol.
  2. Converting events to low-level syntax (This step is not necessary if the stream was written in low-level syntax.)
  3. Parsing an enhancement stream. (This step is not necessary if you use ipsend.SendEvent to transmit events.)
  4. Transmitting events.


Connecting to an IP Broadcast Protocol

The first step of transmitting an enhancement to broadcast clients is to establish connections to the transport protocol, which can be a Microsoft Multicast Router, a LAN, or any other IP broadcast protocol.

The ipsend object operates the same regardless of the broadcast system that transmits the IP data. The IP broadcast system can correspond to a Microsoft® Multicast Router, a LAN multicast system, or any other IP-supporting protocol. The ipsend object simply sends the IP data to the specified addresses.

There are two types of connection settings for the ipsend object: global settings that apply to every type of transmission and settings that apply to a specific type of transmission such as announcements, triggers, or file downloads.

The address and broadcast time-to-live values for the network interface card (NIC) are global properties. Set the NIC address by setting a value for the ipsend.Netcard property. Set the time-to-live for your IP broadcasts using ipsend.TTL.

Each type of transmission, announcements, triggers, and file downloads, uses a separate IP address and port. The ipsend object provides three methods that you can use to set these values: ipsend.ConnectAnnouncement, ipsend.ConnectTrigger, and ipsend.ConnectFTS.

The following example connects an ipsend object and prepares it to transmit the enhancement stream.

'Create a new ipsend object.
Dim isend As ipsend
Set isend = New ipsend

'Set the Netcard and TTL values
isend.Netcard = "233.24.344.12"
isend.TTL = 64

'Connect to the announcement IP stream
isend.ConnectAnnouncement "122.12.133.2", 102

'Connect to the trigger IP stream
isend.ConnectTrigger "122.12.133.8", 108

'Connect to the FTS IP stream
isend.ConnectFTS "122.12.133.3", 103


Parsing an Enhancement Stream

Parsing the enhancement stream determines whether a specific event is an announcement, trigger, or file transfer. This step is not required if you use ipsend.SendEvent to transmit the events.

If, however, you are using the ipsend.SendTrigger, ipsend.SendAnnouncement, and ipsend.SendFTSFile methods to transmit the stream, you must determine the type of each event before you transmit it.

Your application can parse and transmit individual events as demonstrated in the following function. This example assumes that a global instance of ipsend, isend, already exists and is connected to the outgoing IP stream objects.

Function SendThisEvent(e As IEnhEvent) As String

    If e.IsTrigger Then

        'Transmit the trigger
        '(For triggers, EnhEvent.Name contains the trigger data.)
        isend.SendTrigger e.Trigger + e.Name

    Else

        If e.IsAnnounce Then
            'Transmit the announcement
            '(For announcements, EnhEvent.Name contains the name and
            ' path of the announcement file)
            isend.SendAnnouncement e.Name
        Else
            'Transmit the file, using FTS
            '(For FTS events, EnhEvent.Name contains the
            'source file name.)
            isend.SendFTSFile e.Name
        End If

    End If

End Function

To use a function such as SendThisEvent in an application, you would create a timer routine that compares the starting time of the next event in an enhancement stream with the time elapsed during the current show. When the time for the event arrives, the timer routine calls SendThisEvent to broadcast the event.


Transmitting Events

The last step in broadcasting an enhancement is transmitting the events. The ipsend object transmits the enhancement events the same regardless of the broadcast system that transmits the IP data. The IP broadcast system can correspond to a Microsoft® Multicast Router, a LAN multicast system, or any other IP-supporting protocol. The ipsend object simply sends the IP data to the specified addresses.

Before you can transmit events using ipsend, you must connect to an outgoing IP broadcast protocol and convert the stream to low-level syntax. For more information about these steps, see Connecting to an IP Broadcast Protocol and Converting Events to Low-Level Syntax.

The ipsend object provides several methods that you can use to transmit events. The ipsend.SendEvent method automatically determines the type of the event and then transmits it. If you use this method to transmit events, you do not need to parse the stream.

In contrast, the rest of the transmission methods transmit only one type of event each. Before your application can call any of these methods, it must parse the stream to determine the type of each event. For more information, see Parsing an Enhancement Stream. These additional transmission methods are:

  • ipsend.SendAnnouncement
  • ipsend.SendDeleteAnnouncement
  • ipsend.SendFTSFile
  • ipsend.SendTrigger
  • ipsend.TriggerCAB
  • ipsend.TriggerFTS
  • ipsend.TriggerNavigate
  • ipsend.TriggerScript

For more information about transmitting each type of event, see the following topics:

  • Transmitting Announcements
  • Transmitting Triggers
  • Transmitting Files


Transmitting Announcements

An announcement is used to initialize the enhancement on the client. It informs the client that a particular show or channel is enhanced, specifies the IP address clients can monitor to receive triggers, and provides base page information.

Your application can broadcast an announcement by calling either ipsend.SendEvent or ipsend.SendAnnouncement.

To use SendEvent, pass in the event object you want to transmit. The following example illustrates how to transmit the event stored in the EnhEvent object, e.

isend.SendEvent e

When you call SendAnnouncement, you pass in the filename of a text file that contains the announcement data. By convention, it has the extension .ann.

For information on how to create announcement files, see Creating Enhancement Announcements.

The following examples demonstrate how to transmit an announcement using ipsend.SendAnnouncement.

'Transmit the announcement stored in event e.
'(For announcements, EnhEvent.Name contains the name and
' path of the announcement file)
isend.SendAnnouncement e.Name

'Transmit an announcement using hard-coded data.
isend.SendAnnouncement "MyAnn.ann"

If you need to rescind or delete a previously-sent announcement, your application can call ipsend.SendDeleteAnnouncement. Specify the same announcement file that you used when sending the original announcement.

'Rescind an announcement using hard-coded data.
isend.SendDeleteAnnouncement "MyAnn.ann"


Transmitting Triggers

Triggers change the display or operation of an enhancement on the client. For example, a trigger can display new content in a frame or a new base page. Triggers are also used to initialize data reception. For a list of the types of triggers you can transmit, see Enhancement Triggers.

The ipsend object provides three types of methods that you can use to transmit triggers. The first type, ipsend.SendEvent parses an event and transmits it. The second type, ipsend.SendTrigger, accepts a pre-formatted trigger string as the input parameter. You can use SendTrigger or SendEvent to transmit any of the trigger formats described in Enhancement Triggers.

The third type of method accepts trigger data and formats the string for you. This includes the methods: ipsend.TriggerCAB, ipsend.TriggerFTS, ipsend.TriggerNavigate, and ipsend.TriggerScript. Each of these methods transmits a particular type of trigger.

You can use SendEvent, SendTrigger, or the TriggerXxx methods to transmit a trigger to the client. Choose whichever is most convenient for your application. Note that the ipsend.TriggerXxx methods cannot transmit TVCrossover triggers or user triggers. To transmit these types of triggers you must use ipsend.SendTrigger or ipsend.SendEvent.

The following example illustrates how to use ipsend.SendEvent to transmit the event stored in the EnhEvent object, e.

isend.SendEvent e

The following examples use SendTrigger to transmit a trigger.

'Transmit the trigger stored in event e
'(For triggers, EnhEvent.Name contains the trigger data and
' EnhEvent.Trigger contains the trigger key.)
isend.SendTrigger e.Trigger + e.Name

'Transmit triggers using hard-coded data.
isend.SendTrigger "1 <CAB>Show.cab"
isend.SendTrigger "1 <FTS>123.32.111.98:198&MyShow&60"

The next examples demonstrate how to transmit triggers using the TriggerXxx methods.

isend.TriggerCAB "Show.cab"
isend.TriggerFTS "123.32.111.98", 198, "MyShow", 60
isend.TriggerNavigate "MyEnh.htm", "Left"
isend.TriggerScript "MsgBox ""Hello World!""", "VBScript"

When ipsend transmits a trigger, it automatically calculates the checksum value and adds this to the trigger string that it transmits. This value is used by the client to verify that the trigger is valid. If your application transmits the trigger by some means other than ipsend, it must calculate and add this value to the trigger string. For more information, see Trigger Checksum Value.


Transmitting Files

File transmission downloads enhancement files to the broadcast clients. Before your application transmits the files, it must transmit a Data trigger. This Data trigger informs clients that a file is about to be transmitted and tells them which IP address and port to monitor in order to receive the file.

Typically, the Data trigger event is added to the stream during the authoring process and is automatically transmitted by your application as it processes the stream. If, however, your tool transmits streams from a variety of authoring sources, you may find it useful to add functionality to check for the accompanying data event.

An enhancement file often requires one or more additional files, such as image files, to display correctly. You can ensure that an enhancement file arrives with its dependency files by packaging them together into a cabinet file. The ipenhsnd type library provides an object, EnhCab, which your application can use to create cabinet files. For more information, see Creating a Cabinet File.

Your can transmit files using ipsend.SendEvent or ipsend.SendFTSFile. These methods broadcast files using Microsoft® NetShow™ File Transfer Service (FTS). To limit the bandwidth FTS uses to transmit files, set a value for ipsend.Throttle.

To use SendEvent, pass in the event object you want to transmit. The following example illustrates how to transmit the event stored in the EnhEvent object, e.

isend.SendEvent e

The following examples demonstrate how to transmit a file using ipsend.SendFTSFile.

'Transmit the file stored in event e
'(For FTS events, EnhEvent.Name contains the
'source file name.)
isend.SendFTSFile e.Name

'Transmit a file using hard-coded data
isend.SendFTSFile "Art\Gallery.htm"


Creating a Cabinet File

The ipenhsnd type library, Ipensnd.dll, includes an object, EnhCab, that you can use to create and investigate cabinet files. Cabinet files compress and package files together. This conserves bandwidth and ensures that your enhancement pages arrive together with their dependencies.

EnhCab provides several cabinet utility methods. For example, you can call EnhCab.NewCabinet to create a new cabinet file, EnhCab.AddFile to add files to a cabinet, and EnhCab.EnumerateCabinet to count the files stored in a cabinet. For a complete list of the methods provided by EnhCab, see the EnhCab reference topic.

The following example uses EnhCab to create a cabinet file that contains three enhancement files.

Dim ecab As EnhCab
Set ecab = New EnhCab

'Create a the cabinet file
ecab.NewCabinet "Cab1.cab", 2000000, 2000000, 1

'Add two files to the new cabinet
ecab.AddFile "C:\file1.htm", "file1.htm"
ecab.AddFile "C:\file2.htm", "file1.htm"

'Close the cabinet file
ecab.CloseCabinet

'retrieve the number of files in the new cabinet
Dim numFiles As Long
ecab.EnumerateCabinet "C:\Cab1.cab", numFiles    'sets numFiles to 2

'retrieve the filename of the first file in the cabinet
Dim firstFile As String
ecab.Filename 0, firstFile    'sets firstFile to "file1.htm"

If you are using the stream compiler objects to generate the stream, you can also use EnhEvent.onefile. Setting this property to True causes the stream compiler objects to package the file with its dependencies into a cabinet file and transmit them together.


Monitoring the Status of an Enhancement Control

The ipsend object provides methods that enable your application to monitor the status of an Enhancement control running in the same process as the ipsend object. If your application is using an Enhancement control, for example to review a newly created interactive show, you can use this functionality to monitor when the control is created, connects to a data stream, handles a trigger, is destroyed, and so on.

In order for your application to be able to monitor the control status, it must set ipsend.ReportStatus to a non-zero value. This causes in-process enhancement controls to send status messages. By default, such messages are not sent.

Note If your application sets ReportStatus to a non-zero value, it must reset this value to zero when it no longer needs enhancement status reports or before it terminates. Otherwise, the ipsend object will not exit memory because of circular references to an internal status object.

Once your application has set ReportStatus to a non-zero value, it will receive ipsend.StatusChanged events whenever the enhancement control's state changes. You can implement an event handler in your application to process this event.

Your application can also check the status of the enhancement control using the ipsend.Status property. Once ReportStatus is set to a non-zero value, this property will contain the current status of the enhancement control running in the same process as ipsend.

Note If you have multiple enhancement controls running in the same process as ipsend, the ipsend object cannot distinguish between status change notifications for each enhancement control. To avoid confusion, it is recommended that you have only one enhancement control running in-process with ipsend.


Enhancement Reference

The following topics provide reference information about the enhancement-related objects and libraries:

  • Enhancement Announcement Format describes the format used in enhancement announcements.
  • Enhancement Triggers describes the types and formats of enhancement triggers.
  • Stream Compiler Object Library describes the programmable COM objects exposed by the compiler that creates and edits the enhancement stream.
  • ipenhsnd Type Library details objects you can use to transmit enhancement streams.
  • Enhancement Registry Entries describes registry entries on the client that your application can set to control how the broadcast client displays enhancement files.

Note The preceding object references are documented using syntax for the Microsoft® Visual Basic® development system. However, because the enhancement objects implement COM, you can use them from any COM-supporting language, including Java and the Microsoft® Visual C++® development system.


Enhancement Announcement Format

Enhancement announcements are formatted using Session Description Protocol (SDP). For more information, see Announcement Format. This topic discusses only the SDP fields used by enhancement announcements.

The following is a sample enhancement announcement for a future show:

v=0
o=enhfilt 248 56132 IN IP4 157.55.106.31
s=Time & Again Interactive
c=IN IP4 231.31.17.1
t=31557167 31449234
a=EnhID:{9E2E8B20-083E-11d1-898F-00C04FBBDEBC}
a=ShowRef:1997/7/29!26673/7175/9690!0:30!0!0!0!0!9690!9690!4096!7040!''!'MSNBC'!3!54!'Time & Again'
a=PreloadURL:show\default.htm
a=FutureEnh:
m=data 3456 udp 0

where

v =
Announcement protocol version.
o =
Owner of the announcement, in this case the enhancement filter, and session identifier.
s =
Name of the enhancement. This string should be used as the enhancement title in any user interface relating to the enhancement.
c =
Connection information.
t =
Time the session is active.
a =
Attribute fields, of which there can be zero or more. The enhancement announcement format specifies the following attribute fields:
a = EnhID
Identifies the announcement as an enhancement announcement and specifies a unique identifier for the enhancement.
a = ShowRef
Specifies the show reference of the interactive episode or episodes. This field is required for future announcements. If this field is not present, the filter assumes the announcement is for a current broadcast. For more information, see Show Reference Format.
a = PreLoad
Specifies the Uniform Resource Locator (URL) of the Hypertext Markup Language (HTML) file that contains the starting enhancement page. This field is optional for a future announcement and is not used for current announcements. If you do not specify a complete path, such as C:\MyEnhance\, the URL is resolved relative to C:\Program Files\TV Viewer\Layouts. For example, if you specify TVShow\TVShow.htm, this path is resolved to C:\Program Files\TV Viewer\Layouts\TVShow\TVShow.htm.
a=FutureEnh
Indicates that the announcement is for a future enhancement. This field is required for future enhancements and is not used for current enhancements.
m =
Specifies the media name and transport address.


Enhancement Triggers

Each type of trigger sent to the Enhancement control has a specific format associated with it. The trigger format transmitted by the ipsend object is a string that contains three parts: a key or numerical identifier, the trigger data, and a checksum value. The key is separated from the data by white space, typically a space or tab character. The checksum value is surrounded by square brackets. For more information, see Trigger Checksum Value.

The format of a trigger is as follows:

"Key TriggerData[checksum]"

For example, the following string might be specified in a Nav trigger:

"2 bpc://www.microsoft.com/default.htm[BA7E]"

Note The checksum value is automatically calculated by the ipsend object when a trigger is transmitted. You do not need to specify checksum values when setting triggers in an enhancement stream. Because this value is added transparently, the following trigger topics display the trigger format you use to specify a trigger in the enhancement stream — in other words, the trigger format without the checksum value.

The following table lists the trigger formats currently supported.

Key | Name | Description
0 | Error | No action is taken.
1 | Data | Receives data using the specified transfer protocol.
2 | Nav | Displays a page. If a target is specified, such as a <FRAME> or <DIV> tag set, the page is displayed in that target.
3 | Nav | Same as the previous trigger. This key value has been kept for compatibility with earlier versions.
4 | Script | Runs the specified script.
5 | TVCrossover | Fires a TVCrossover event.
6 – 999 | Reserved | Key values reserved for future trigger functionality.
1,000 and up | UserTrigger | Sends a user trigger event.


Trigger Checksum Value

When the broadcast client receives a trigger it needs to verify that the trigger is valid and has not been corrupted during transmission. To permit such validation, each trigger has a checksum value added to the end of the trigger string. The checksum value is represented as four hexadecimal digits surrounded by square brackets. For example:

"1 <CAB> bpc://Mydir/Mycab.cab [4356]"

The checksum value is calculated from the trigger string using a standard algorithm. When the client receives the trigger it re-calculates the checksum value from the trigger string and compares that value with the checksum value transmitted with the trigger. If the two values do not match, the client rejects the trigger as invalid.

If you are using the enhancement sender object to transmit triggers to the client, it automatically computes the checksum value and appends it to the trigger string. If you write your own application to transmit triggers to the client, you must implement functionality to calculate the checksum and add it to the trigger string. Otherwise, the client will reject the triggers sent by your application because they will not have a valid checksum value.

The method for computing the checksum value is as follows:

Checksum Algorithm

To compute the checksum, adjacent characters in the string (starting with the first character of the trigger data — not including the trigger key) are paired to form 16-bit integers; if there are an odd number of characters, the final character is paired with a byte of zeros. The checksum is computed so that the one's complement sum of all of these 16-bit integers plus the checksum equals the 16-bit integer with all 1 bits (-0 in one's complement arithmetic); in other words, the checksum is the one's complement of the one's complement sum of the 16-bit integers. This 16-bit checksum is transmitted as four hexadecimal digits in square brackets following the data portion of the trigger. Because the checksum characters themselves (including the surrounding square brackets) are not included in the calculation of the checksum, they must be stripped from the string by the receiver before the checksum is recalculated there.


Broadcast Architecture URLs

Broadcast architecture defines a new type of URL to locate enhancement files on broadcast clients. The new URL format provides better security than specifying the actual directory on the client machine. This is because Broadcast Architecture URLs are processed using the broadcast client's Internet Security Zone settings. The Internet Security Zone settings are set on the client using Internet Explorer.

The format of a Broadcast Architecture URL is:

"bpc://..."

For example the following URL:

"bpc://Msnbc/MyShow/MyFile.htm"

maps to the following location on the client machine:

"C:\Program Files\TV Viewer\Interactive Content\<random>\Msnbc\MyShow\MyFile.htm"

where <random> is a random string generated by the broadcast client. Adding a random string to the file path improves security on the client by ensuring that enhancement files can only be located using the Broadcast Architecture URL format and thus processed using the Internet Security Zone settings.


Data Trigger

Data triggers indicate that data, such as an HTML enhancement file, is about to be transmitted. They are formatted as shown following

"1 [<protocol>] ConnectionInformation"

where

protocol
Optional parameter that specifies the data transfer protocol. The default is FTS. The following table lists the currently-defined protocols:
Protocol | Description
FTS | Downloads a file using Microsoft® File Transfer Service.
CAB | Unpacks the specified cabinet file.

ConnectionInformation
Connection information. The format of this string depends on which protocol is used. For more information, see the remarks section.

Remarks

If the protocol is FTS, ConnectionInformation has the following format:

xxx.xxx.xxx.xxx:yyyy&dirname[&timeout]

where

xxx.xxx.xxx.xxx
IP address that the FTS data will be transmitted on.
yyyy
IP port.
dirname
Directory name in which the transmitted files should be saved. Note that this value cannot contain subdirectories. For example, "msnbc" is a valid value for dirname, but "msnbc\MyShow" is not.

To store a transmitted file in a subdirectory of dirname, specify the subdirectory when the file is transmitted.

timeout
Optional parameter that specifies a time-out interval, in minutes. After Timeout minutes have elapsed, the subdirectory is deleted. The default value is 120 minutes.

CAB:

If the protocol is CAB, ConnectionInformation is a Broadcast Architecture URL that specifies the cabinet file to unpack. For example: "bpc://msnbc/myshow/cabfile.cab"

Examples

Both of the following triggers cause the enhancement control to receive a file at IP address 233.43.170.18, port 1718.

"1 233.43.170.18:1718&MyShow"
"1 <FTS> 233.43.170.18:1718&MyShow"

The following trigger causes the enhancement control to unpack the cabinet file located at: "C:\Program Files\TV Viewer\Interactive Content\<random>\Msnbc\MyShow\MyFile.cab"

"1 <CAB> bpc://msnbc/myshow/myfile.cab"

where <random> is a random string generated by the broadcast client. Adding a random string to the file path improves security on the client by ensuring that enhancement files can only be located using the Broadcast Architecture URL format and thus processed using the Internet Security Zone settings.


Nav Trigger

Nav triggers cause the enhancement control to display the specified page.

"2 <location>[[targ: targetName]]"

where

location
Specifies the location of the enhancement page to be displayed. This location can be either a fully-specified Broadcast Architecture URL, or a location relative to the enhancement's base page.

If you are displaying a new enhancement base page, you should use a fully-specified Broadcast Architecture URL. This is because the new base typically will be located in a directory that is not a subdirectory of the old page. In other words, you typically cannot specify a relative path to a new base page.

targetName
An optional parameter that specifies the name of the target element in which to display the new content. The target element can be a set of <FRAME>, <IFRAME>, <SPAN>, or <DIV> tags.

If targetName is not specified, the enhancement control navigates the highest-level window of the Web browser to the specified URL. (This functionality produces the same result as setting TARGET="_top" in an HREF link.)

Remarks

Broadcast Architecture also supports the following alternative formats for Nav triggers:

"3 <location>[[targ:targetName]]"

where all parameters are the same as described preceding, but the key value is three. This format has been kept for compatibility with earlier versions of Broadcast Architecture.

"2 [&targetName&]location"

where all parameters are the same as described preceding. This is the ASF format used by Microsoft® NetShow™ server.

Using a Nav trigger, you can sequence complex interactive Web content without any scripting.

The Enhancement control's response to this trigger depends on the state of the Enhancement control's TargetSync property. When this property is set to False, the control does not navigate immediately to the specified URL but does save the URL. When this property is once again set to True, the control navigates to the URL most recently specified.

Examples

The following are examples of valid Nav triggers.

"2 <MyEnh.htm>[targ:Left]"
"2 <bpc://msnbc/myshow/file.htm>"
"2 MyDir\MyEnh.htm"
"2 &Left&MyDir\MyEnh.htm"

See Also

EnhEvent.PageName, EnhEvent.TargName


Script Trigger

Script triggers run the specified script statements on the broadcast client. They are formatted as shown following

"4 [<protocol>] script"

where

protocol
Is an optional parameter which specifies the scripting language to use. The default is Microsoft® JScript™ development software.

No other scripting languages are supported in the current version of Broadcast Architecture. Because the current version of the broadcast client does not recognize protocol, do not include this optional parameter in triggers you send.

script
Specifies the script to run on the client.

Remarks

When the Enhancement control receives a Script trigger, it runs the specified script as if it were embedded in the enhancement page. Using this trigger, you can greatly expand the functionality of the enhancement.

Examples

The following are examples of Script triggers that use JScript to print an alert box to the user.

"4 alert('You received an JScript trigger!')"


TVCrossover Trigger

TVCrossover triggers contain URL information. They are formatted as shown following.

"5 <URL>[[attr1:val1][attr2:val2] ... [attrN:valN]]"

where

URL
Specifies a Uniform Resource Locator.
attrN
Specifies the name of the Nth attribute. A TVCrossover trigger can contain zero or more attribute:value pairs.

This parameter is optional. The default value is "type".

valN
Specifies the value of the Nth attribute.
Checksum
The trigger checksum value. For more information see, Trigger Checksum Value.

Remarks

When the broadcast client receives a TVCrossover trigger, it fires a TVCrossover event, which can then be handled by scripts embedded in the enhancement page.

Examples

The following are examples of TVCrossover triggers. Note that the attributes that have the form [xxx] use the default name "type" and are equivalent to [type:xxx].

"5 <http://www.newmfr.com>[name:New]"
"5 <http://www.stdnetwork.com>[network]"
"5 <http://www.tvprogram.com>[program]"
"5 <http://advsponsor.net>[sponsor][name:Advertising Sponsor]"


UserTrigger Trigger

User triggers are custom triggers sent by the broadcast provider. They are formatted as shown following

"lKeyID Data"

where

lKeyID
Specifies the trigger identifier, whose value is defined by the content provider. This must be an integer greater than or equal to 1,000.
Data
Specifies the trigger information. The trigger information data is parsed and used by the event handler that processes the user trigger. The format of the trigger information is defined by the broadcaster.
Checksum
The trigger checksum value. For more information see, Trigger Checksum Value.

Remarks

When the broadcast client receives a UserTrigger trigger, it fires a UserTrigger event, which can then be handled by scripts embedded in the enhancement page.

Examples

The following examples illustrate how you could use user-defined triggers to transmit quiz show questions and answers. The user-defined trigger data can then be parsed and used by scripts on the enhancement page.

"3001 Q:What is the capital of Florida?_A:Tallahassee"
"3001 Q:Tomatoes are which kind of plant?_A:Fruit"

The following examples use a different user-defined syntax to pass the time of day to the enhancement page. This could be used, for example, to change the background image of a enhancement to reflect the current time.

"2049 Twilight"
"2049 Morning"
"2049 Afternoon"


Stream Compiler Object Library

The Stream Compiler Object Library, Stream.dll, contains a set of COM objects that provide functionality to create, edit, and save enhancement streams. You can use these objects to create enhancement stream authoring tools such as an enhancement stream editor or play-back application.

The stream compiler exposes the following objects:

Object | Description
EnhEvent | An enhancement event object.
EnhEvents | A collection of enhancement event objects.
Annc | An announcement object.


EnhEvent

The EnhEvent object stores information about an enhancement stream event.

Property | Description
Attr | A collection of the microevents within an event.
AttrCount | Number of microevents in the current event. This property enumerates the values stored in Attr.
Before | A value that indicates whether the compiler should download all dependencies of the event before the event's start time.
Depend | An array of the event's dependency files.
DependCount | Number of dependencies currently set for the event. This property enumerates the values stored in Depend.
Handle | A unique identifier for the event. This property is read-only.
HRef | Indicates whether HTML hyperlinks should be treated as dependencies for this event.
IsAnnounce | Indicates whether the event is an enhancement announcement.
IsInclude | Indicates whether the event includes another enhancement stream into the current stream.
IsTrigger | Indicates whether the event is a trigger.
Length | Length of the file, in bytes. This property is read-only.
Name | Name or text value of the event.
onefile | Indicates whether to transmit the file and all its dependencies as a single cabinet file.
Only | Indicates whether dependencies, such as images and animations, should be resolved for this event.
Opcode | Describes the operation type of a microevent, for example a trigger or downloading a file. The Opcode collection describes the types of the microevents stored in Attr.
PageName | Returns the portion of Name enclosed by angle brackets.
Priority | FTS priority value. This property is not yet implemented.
Repeat | The interval, specified in seconds, between repetitions of the event.
RestOfName | Returns the portion of Name outside of angle brackets.
Start | Start time of the event, in seconds.
TargName | Name of the navigational target specified in the event.
Text | Stream language text of the event.
Timeout | Time at which the event is garbage collected. This method is not implemented in version 1.0 of Broadcast Architecture.
Trigger | Numerical identifier that identifies the trigger type.
Until | Duration of the event repetition, in seconds.
XMitDuration | Time that it will take to transmit the event. This value is read-only.
XMitName | Filename of the file on the client. In other words, the destination filename. This property is read-only.

Method | Description
Delete | Removes the event from the EnhEvents collection.
Flatten | Flatten the event into low-level events.
UnFlatten | Unflatten the event from low-level events back into its original high-level event form.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


EnhEvent.Attr

The Attr property is an array of text of the subevents, or microevents stored within an event. The operation codes of these subevents are stored in the EnhEvent.Opcode array.

Syntax

object.Attr(index) [ = sAttr ]

Parts

object
Object expression that resolves to an EnhEvent object.
index
Long that indicates the 0-based index of the microevent. This value must always be less than or equal to EnhEvent.AttrCount. If you set index to a value higher than EnhEvent.AttrCount, Attr returns an error.
sAttr
String that receives the microevent string. The content of this string depends on the type of microevent. The type of microevent is stored in EnhEvent.Opcode.
Microevent Type | sAttr contains
Announcement | Announcement filename.
Delete Announcement | Announcement filename.
Download | Path and filename of the file.
Global | Assignment of the global variable.
Include | Stream filename.
Trigger | Trigger data.
User-defined | User-defined text.
Group | Handle and positioning information used to unflatten events converted into low-level syntax. The data is formatted as "HandleAsLong[,head]" where HandleAsLong is the original event's handle expressed as a Long. The optional keyword head identifies the original high-level event.

Remarks

Each event can contain one or more microevents. For example, the event set by the following code has three microevents, downloading File1.htm, triggering File2.htm to be displayed in the Left frame, and a comment.

evs.AddText("0:32.0 {File1.htm trigger(2 <File2.htm>[targ:Left]) userdef ""This is a comment"" };")

You can use Attr to add microevents to an event. Simply set either the text or the operation type for the microevent at the AttrCount index. This is demonstrated in the following example:

index = e.AttrCount

'Add a new file download microevent to an event.
'Note that this increments AttrCount.
e.Attr(index) = "File1.htm"

'Identify the type of microevent operation
e.Opcode(index) = EVOPdownload

For each microevent that you add, you must also specify an operation type such as a trigger, download, or user comment. To do this, set EnhEvent.Opcode at the same index as the new microevent. This is demonstrated in the preceding example.

You can only add one microevent at a time, attempting to set microevent values at indices higher than AttrCount results in an CTL_E_INVALID_PROPERTYVAL error.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.AttrCount, EnhEvent.Opcode

Examples

You could access the text of the three microevents programmatically by using the Attr collection. For example, if you set an event such as the one described in the Remarks section, then the following code

Open "MyFile.txt" for Output As #1
Write #1, "Index,"+Chr$(9)+"Opcode,"+Chr$(9)+"Attr"

For item = 0 to (e.AttrCount - 1)
  Select Case e.Opcode(item)
  Case EVOPdownload
    Write #1, item, "Chr$(9)+EVOPdownload", Chr$(9)+e.Attr(item)
  Case EVOPtrigger
    Write #1, item, "Chr$(9)+EVOPtrigger", Chr$(9)+e.Attr(item)
  Case EVOPuserdef
    Write #1, item, "Chr$(9)+EVOPuserdef", Chr$(9)+e.Attr(item)
  End Select
Next item

Close #1

writes the following output to MyFile.txt

"Index,  Opcode,       Attr"
 0,      EVOPuserdef,  "This is a comment"
 1,      EVOPtrigger,  "<File2.htm>[targ:Left]"
 2,      EVOPdownload, "File1.htm"

You can use Attr to set or change microevents. For example, the following code changes the file that is downloaded from File1.htm to File3.htm.

e.Attr(2) = "File3.htm"

To change the type of the event, such as from a file download to a trigger, change the corresponding value of EnhEvent.Opcode. For example, the following code changes the preceding microevent, Attr(2), into an announcement.

e.Attr(2) = "MyAnnc.ann"
e.Opcode(2) = EVOPannounce

If you did not set Opcode to EVOPannounce in the preceding example, the microevent would still be an FTS download and would download the file MyAnnc.ann instead of sending it as an announcement.


EnhEvent.AttrCount

The AttrCount property enumerates the number of microevents in the event. This property is read-only.

Syntax

[ lCount = ] object.AttrCount

Parts

object
Object expression that resolves to an EnhEvent object.
lCount
Long that indicates the number of microevents stored in Attr.

Remarks

The microevents enumerated by AttrCount are stored in EnhEvent.Attr. Because the operation types in EnhEvent.Opcode map one-to-one with the microevents in EnhEvent.Attr, the number returned by AttrCount also enumerates the operation types stored in EnhEvent.Opcode.

If you add a new microevent by calling either EnhEvent.Opcode or EnhEvent.Attr and specifying an index equal to the value of EnhEvent.AttrCount, the value of AttrCount is automatically incremented.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.Attr, EnhEvent.Opcode

Examples

The following example uses AttrCount to loop through the microevents stored in Attr and write the microevent data to a file.

Open "MyFile.txt" for Output As #1

For item = 0 to (e.AttrCount - 1)
  Write #1, Attr(item)
Next item

Close #1


EnhEvent.Before

The Before property indicates whether the compiler should ensure that all dependencies of the event are transmitted before the event's start time, as specified in EnhEvent.Start.

Note that verifying the event's readiness can include transmitting HTML hyperlink dependencies if Href is non-zero.

Syntax

object.Before [ = lBefore ]

Parts

object
Object expression that resolves to an EnhEvent object.
lBefore
Long that indicates whether the event should be verified before it is fired. If this value is non-zero, the event should be verified. If it is zero, it should not.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Dependencies


EnhEvent.Delete

The Delete method removes an event from the EnhEvents collection.

Syntax

object.Delete()

Parts

object
Object expression that resolves to an EnhEvent object.

Remarks

The Delete method deletes the instance of the EnhEvent object that it removes from the collection.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


EnhEvent.Depend

The Depend property contains an array of strings containing the path and filenames of the event's dependencies.

Syntax

object.Depend(lIndex) [ = sDepend ]

Parts

object
Object expression that resolves to an EnhEvent object.
lIndex
Long that specifies the index of the dependency within the array.
sDepend
String that specifies the path and filename of the dependency file at lIndex. If you set sDepend to an empty string ("") the file is removed from the event's dependency list, and the remaining values are re-indexed.

Remarks

You can use Depend to retrieve or set dependency files for an event. With it, your authoring tool can either use the dependency list automatically generated by the stream compiler objects or create a custom dependency list for the event.

If the dependency list for an event is empty, the stream compiler objects automatically calculate the dependencies for that event when the event or stream is converted to low-level format by EnhEvent.Flatten or EnhEvents.Flatten. If a dependency list already exists for the event, the stream compiler objects do not generate a new dependency list. Instead, they use the pre-existing dependency list.

To force the stream compiler objects to re-calculate dependencies for an event, you can use Depend to delete all of the items in the dependency list. Simply set the value of each item to an empty string (""). This is illustrated in the Examples section at the end of this topic.

Similarly, you can prevent the stream compiler objects from automatically calculating dependencies for an event, by creating a dependency list using Depend.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.DependCount, EnhEvent.Flatten, EnhEvent.UnFlatten, Editing the Dependencies of an Event

Examples

The following example deletes all of the items in an event's dependency list.

While e.DependCount > 0
    e.Depend(0) = ""
Wend

Note that in the preceding example, the 0th element of the array is always the one removed. Because the remaining dependencies are re-indexed each time a dependency is deleted, you cannot replace the second line with:

e.Depend(i) = ""

Because it would cause the loop to overrun the array.

The following example sets a dependency list for the event e.

e.Depend(0) = "First.gif"
e.Depend(1) = "Second.gif"
e.Depend(2) = "Third.jpg"

Because DependCount is incremented each time a dependency file is added to the list, the preceding example can also be written as:

e.Depend(e.DependCount) = "First.gif"
e.Depend(e.DependCount) = "Second.gif"
e.Depend(e.DependCount) = "Third.jpg"

Note that, as with EnhEvent.Attr, you cannot add more than one dependency at a time, and only to the end of the array. In other words, you can only add a dependency whose index value is equal to DependCount.


EnhEvent.DependCount

The DependCount method returns the number of dependencies for the event. This property is read-only.

Syntax

[ lDependCount = ] object.DependCount

Parts

object
Object expression that resolves to an EnhEvent object.
lDependCount
Long that contains the number of dependency files for this event.

Remarks

DependCount returns the number of dependencies listed in the EnhEvent.Depend array.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.Depend, EnhEvent.Flatten, EnhEvent.UnFlatten, Editing the Dependencies of an Event

Examples

The following example deletes all of the dependencies of an event. Note that this causes the stream compiler objects to recalculate the dependency list for this event when it is converted to low-level syntax.

While e.DependCount > 0
    e.Depend(0) = ""
Wend

The following example displays a warning if the user attempts to transmit a file that has more than 20 dependency files.

If e.DependCount > 20 Then
   Msgbox "Warning: sending this page will cause " + e.DependCount + " files to be transmitted."
End If


EnhEvent.Flatten

The Flatten method converts an event into its low-level component events. This method can cause the stream compiler to add new events and change event times slightly.

Syntax

object.Flatten()

Parts

object
Object expression that resolves to an EnhEvent object.

Remarks

You can only call EnhEvent.Flatten for events that are part of an enhancement stream. Calling EnhEvent.Flatten for events that have not been added to an enhancement stream causes the method to return an error.

You can use EnhEvent.Flatten to flatten a single event. This differs from EnhEvents.Flatten, which flattens the entire stream.

The event-level Flatten converts a single event to low-level format in exactly the same way as the stream-level Flatten converts the stream — dependencies and repetitions are resolved into individual events.

EnhEvent.Flatten does not affect microevents within an event. For example, if an event contained a file download and a user-defined comment, the microevents would not be expanded into two separate events.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.UnFlatten, EnhEvents.Flatten

Examples

The following example converts a high-level event into low-level format.

e.Flatten


EnhEvent.Handle

The Handle property is a unique identifier for the event. This property is read-only.

Syntax

[ lhandle = ] object.Handle

Parts

object
Object expression that resolves to an EnhEvent object.
lhandle
Long that uniquely identifies the event.

Remarks

EnhEvents.FindHandle searches the EnhEvents collection to return the event with the specified handle.

Examples

The following example uses EnhEvent.Handle to save a handle to an event in the enhancement stream, and then uses EnhEvents.FindHandle to recall the event.

'Declare variables
Dim Ev As IEnhEvents
Dim e As IEnhEvent
Dim lHandle As Long

'create the collection
Set Ev = New EnhEvents

'add an event to the collection
Ev.Add 15, "EventA"

'save a handle to EventA,
'(which is currently the last-added event)
lHandle = Ev.LastAdd.Handle

...

'recall EventA from the collection using the previously-saved handle
Set e = Ev.FindHandle(lHandle)

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


EnhEvent.HRef

The HRef property indicates when HTML hyperlink dependencies should be transmitted.

Syntax

object.HRef [ = lhref ]

Parts

object
Object expression that resolves to an EnhEvent object.
lhref
Long that specifies when dependencies should be resolved. This can a value in one of the following ranges:
Value | Description
< 0 | Transmit hyperlink dependencies before the event.
0 | Do not transmit hyperlink dependencies.
> 0 Transmit hyperlink dependencies after the event.

Values of lhref greater than 0 are not supported in version 1.0 of Broadcast Architecture.

Remarks

If this property is not set, the value in EnhEvents.HRef is used.

If EnhEvents.HRef value is also not set, the default is 0, which causes the compiler not to schedule transmission of hyperlink dependencies.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Dependencies, EnhEvents.HRef


EnhEvent.IsAnnounce

The IsAnnounce property indicates whether the event is an enhancement announcement.

Syntax

object.IsAnnounce [ = lAnnc ]

Parts

object
Object expression that resolves to an EnhEvent object.
lAnnc
Long that indicates whether the event is an announcement. If this value is non-zero, the event is an announcement. If it is zero, the event is not an announcement.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.IsTrigger, EnhEvent.Name


EnhEvent.IsInclude

The IsInclude property indicates whether the event includes a pre-existing enhancement stream into the current stream.

Syntax

object.IsInclude [ = lVal ]

Parts

object
Object expression that resolves to an EnhEvent object.
lVal
Long that indicates whether the event includes a stream. If this value is non-zero, the event includes a stream. If it is zero, it does not.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Including One Enhancement Stream in Another

Examples

The following example tests whether the most recently added event includes a stream. As written, the following example will always display a message box that reads "This is an include event."

evs.AddText("0:32.0 Include MyStream.str")
Set e = evs.LastAdd

If e.IsInclude = 0 Then
  MsgBox "This is not an include event."
Else
  MsgBox "This is an include event."
End If


EnhEvent.IsTrigger

The IsTrigger property indicates whether the event is a trigger.

Syntax

object.IsTrigger [ = lTrig ]

Parts

object
Object expression that resolves to an EnhEvent object.
lTrig
Long that indicates whether the event is a trigger. If the value is non-zero, the event is a trigger. If the value is zero, it is not.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.IsAnnounce, EnhEvent.Trigger

Examples

The following example searches through the enhancement stream until it finds a trigger event. When it finds a trigger, it stores the trigger's handle in an array.

Dim num As Integer
Dim TrigArray() As Long
ReDim TrigArray(0 To evs.Count - 1)

For Each e in evs
    If (e.IsTrigger) Then
        TrigArray(num) = e.Handle
        num = num + 1
    End If
Next e

The reason that the handle is stored instead of the trigger's index value, is that the handle uniquely identifies the trigger and does not change. Because the collection is sorted by start time, the trigger's index value can change as events are added or deleted.


EnhEvent.Length

The Length property specifies the length of the file, in bytes. This property is read-only.

Syntax

[ lLength = ] object.Length

Parts

object
Object expression that resolves to an EnhEvent object.
lLength
Long that receives the file length, in bytes. If the file cannot be opened, either because the file does not exist or because you do not have permissions, the length is 0.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.XmitDuration


EnhEvent.Name

The Name property specifies the name or text of the event. An example of using this property to store event text is a stock ticker enhancement where Name stores the stock name and price.

Syntax

object.Name [ = sName ]

Parts

object
Object expression that resolves to an EnhEvent object.
sName
String that contains the name of the event.

Remarks

The default content of Name varies with the type of event. See the following table for specifics.

Event Type | Content
Announcement | The path and filename of the file that specifies the announcement.
Trigger | The trigger data.
FTS data | The source filename.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


EnhEvent.onefile

The onefile property indicates whether to transmit the file and its dependencies as a single cabinet file.

Syntax

object.onefile [ = lonefile ]

Parts

object
Object expression that resolves to an EnhEvent object.
lonefile
Long that indicates whether to transmit the file and all its dependencies as a single file. If this value is non-zero, the file and dependencies are transmitted together in a cabinet file. If it is zero, they are not.

Remarks

You can use onefile to ensure that dependency files are downloaded with their base page.

If onefile is True when the stream is converted to low-level format, the stream compiler objects automatically add events to the stream that package the file and its dependencies into a cabinet file, transmit the cabinet file, and unpackage the cabinet file on the client.

Examples

The following adds an event to the stream, specifying onefile to be True.

evs.AddText = "00:00:00.0 trigger(3 ""<Mypage.htm>[targ:MyTarg]"");"
Set e = evs.LastAdd
e.onefile = True

The preceding produces the following enhancement stream language statement.

00:00:00.0 trigger(3 "<Mypage.htm>[targ:MyTarg]") onefile;

If your application converted the event to low-level syntax using EnhEvent.Flatten or EnhEvents.Flatten, the stream compiler objects would package Mypage.htm with its dependencies and replace the preceding high-level event with the following:

before -00:10:00.0 cabfile.cab;
-00:05:00.0 trigger(1 "<CAB> [bpc://MyShow/cabfile.cab]");
00:00:00.0 trigger(3 "<Mypage.htm>[targ:MyTarg]") only

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.Flatten, EnhEvents.Flatten


EnhEvent.Only

The Only property indicates whether the client application should transmit dependencies for the event.

Syntax

object.Only [ = lOnly ]

Parts

object
Object expression that resolves to an EnhEvent object.
lOnly
Long that indicates whether dependencies should be transmitted for the event. If this value is non-zero, dependencies should be not be transmitted. If it is zero, they should be.

Remarks

You set the Only property to non-zero to prevent the stream compiler from scheduling transmission of dependent files such as GIFs and FutureSplash animations. This is useful, for example, in cases where the dependencies already reside on the client machine, either transmitted by some other means such as Internet channel broadcasting, a previous event, or installed explicitly by the user.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


EnhEvent.Opcode

The Opcode property describes the operation type of a microevent. For example, whether it is a file download or trigger.

Syntax

object.Opcode(index) [ = iVal ]

Parts

object
Object expression that resolves to an EnhEvent object.
index
Long that indicates the 0-based index of the microevent. This value must always be less than or equal to EnhEvent.AttrCount. If you set index to a value higher than EnhEvent.AttrCount, Opcode returns -1.
iVal
Integer that specifies the operation type. This can be one of the following identifiers:
Opcode | Description
EVOPannouncement | The microevent sends an enhancement announcement.
EVOPdelannc | The microevent is a delete announcement which rescinds a previously transmitted announcement.
EVOPdownload | The microevent downloads a file.
EVOPglobal The microevent sets a global variable.

This functionality is not implemented in the current version of Broadcast Architecture.
EVOPinclude | The microevent includes a stream into the current stream.
EVOPtrigger | The microevent sends a trigger.
EVOPuserdef | The microevent is user-defined.
EVOPgroup | The microevent is one of a group of dependent files.

Remarks

The text of the microevents described by Opcode can be accessed using EnhEvent.Attr. For example, e.Opcode(0) returns the operation type of the microevent accessed by e.Attr(0). Because there is a one-to-one relationship between Opcode and EnhEvent.Attr, EnhEvent.AttrCount, which enumerates the number of microevents, also enumerates the number of property types stored in Opcode.

You can use Opcode to add microevents to an event. Simply set either the text or the operation type for the microevent at the AttrCount index. This is demonstrated in the following example:

index = e.AttrCount

'Add a new file download microevent to an event.
'Note that this increments AttrCount.
e.Opcode(index) = EVOPdownload

'Identify the text of the microevent
e.Attr(index) = "File1.htm"

You can only add one microevent at a time, attempting to set microevent values at indices higher than AttrCount results in a CTL_E_INVALIDPROPERTYVAL error.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.Attr, EnhEvent.AttrCount

Examples

You can use Opcode to either determine or set the type of a microevent. The following example counts the number of trigger microevents in an event.

For item = 0 to (e.AttrCount - 1)
  If e.Opcode(item) = EVOPtrigger Then
    numTrigger = numTrigger +1
  End If
Next item

If you want to set or change the type of a microevent, you typically need to set both the microevent text, available from EnhEvent.Attr, and the Opcode value. The following example changes the third microevent of an event to a announcement.

e.Attr(2) = "MyAnnc.ann"
e.Opcode(2) = EVOPannounce

Note that if you do not set the corresponding Attr property in the preceding example, the syntax of the new trigger microevent is incorrect.


EnhEvent.PageName

The PageName property returns the portion of EnhEvent.Name enclosed by angle brackets. This property is read-only.

Syntax

[ sPageName = ] object.PageName

Parts

object
Object expression that resolves to an EnhEvent object.
sPageName
String that receives the portion of Name enclosed by angle brackets (<>).

Remarks

This property is typically used to retrieve the filename from a trigger event. For example, if the enhancement stream contained the Nav trigger event, 00:20:05.0 trigger ("2 <MyEnh.htm>[targ:Left]");, your application could use PageName to extract the filename, MyEnh.htm, from the event.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.TargName

Examples

The following example retrieves the name of the enhancement page specified in event e and stores it in the variable sName.

'Declare a variable to receive the page name.
Dim sName As String

'Retrieve the page name and location from an event.
sName = e.PageName


EnhEvent.Priority

The Priority property specifies the FTS priority.

This property is not implemented in version 1.0 of Broadcast Architecture.

Syntax

object.Priority [ = lPriority ]

Parts

object
Object expression that resolves to an EnhEvent object.
lPriority
Long that specifies the priority. If this value is not set, the default is 5.

Remarks

The compiler uses the priority value during optimization, when it fills available bandwidth. This value is also used during an interleaved transmission of multiple files. The file with greater weight will be proportionally transmitted more often.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.Priority


EnhEvent.Repeat

The Repeat property specifies the number of seconds between repetitions of the event.

Syntax

object.Repeat [ = dRepeat ]

Parts

object
Object expression that resolves to an EnhEvent object.
dRepeat
Double that specifies the repeat interval, in seconds. A value of 0, indicates that the event should not be repeated. If this value is not zero, it must be greater than 0.1 seconds.

Values less than zero are not supported.

Remarks

Events are typically transmitted repeatedly so that if a user misses an enhancement transmission due to line noise or because they tuned to another channel, they will be able to receive a subsequent transmission.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.Until


EnhEvent.RestOfName

The RestOfName property returns the portion of EnhEvent.Name that is outside of angle brackets. This property is read-only.

Syntax

[ sRest = ] object.RestOfName

Parts

object
Object expression that resolves to an EnhEvent object.
sRest
String that receives the portion of the Name property outside of angle brackets.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


EnhEvent.Start

The Start property specifies the time of the event, in seconds. This is specified in relation to the start time of the episode that the event enhances.

Syntax

object.Start [ = dStart ]

Parts

object
Object expression that resolves to an EnhEvent object.
dStart
Double that specifies the start time of the event. This is expressed as the number of seconds after the episode's start time.

Remarks

Typically, the time specified by StartTime is the starting time of the event. However for some events, such as those where the stream syntax stored in EnhEvent.Text is of the form before time package; this time is the end time of the event.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.Text, EnhEvents.ParseTime, EnhEvents.TimeStr

Examples

The following examples set the start time of the event, where e is an EnhEvent object and evs is an EnhEvents collection.

'Set the start time.
e.Start = 342.0

'The following line also sets the start time to 342.0 but uses the
'ParseTime method to convert the time from STMPE format to a double.
e.Start = evs.ParseTime("00:05:42:00")

'Print the event start time in STMPE format
MsgBox evs.TimeStr(e.Start)

Note that you can use the EnhEvents.ParseTime method to convert a STMPE time into the double-string format required by Start. Similarly, you can use the EnhEvents.TimeStr method to convert the double-format time returned by Start to STMPE format. This is demonstrated in the preceding examples.


EnhEvent.TargName

The TargName method returns the name of the navigation target specified in the event.

Syntax

[ sTargName = ] object.TargName

Parts

object
Object expression that resolves to an EnhEvent object.
sTargName
String that receives the name of the navigational target. This is the name assigned to a set of <FRAME>, <IFRAME>, <SPAN>, or <DIV> tags.

Remarks

This property only returns a string for Nav trigger events. Other types of events will always return an empty string (""). The value returned is that specified in the targetName parameter of the Nav trigger.

For example, if the enhancement stream contained the Nav trigger event, 00:20:05.0 trigger ("2 <MyEnh.htm>[targ:Left]");, your application could use TargName to extract the target name, Left, from the event.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Nav trigger, EnhEvent.PageName

Examples

The following example retrieves the name of the navigation target from an event and stores it in the variable sTarg.

'Declare a string variable to receive the target name.
Dim sTarg As String

'Retrieve the target name from an event.
sTarg = e.TargName


EnhEvent.Text

The Text property contains the stream language text for the event.

Syntax

object.Text [ = sText ]

Parts

object
Object expression that resolves to an EnhEvent object.
sText
String that contains the stream language text of the event. To locate more information about stream compiler language syntax, see Further Information on Data Services for the Client.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.AddText

Examples

The following example sets the text of event e to that of a file download that transmits the file, MyShow.htm.

e.Text = "00:00:01:30 MyShow.htm ;"

The next example changes the event text to that of an enhancement announcement event.

e.Text = "00:00:00.50 announce ( ""MyAnnc.ann"" ) ;"

Note Before you can transmit an announcement event, you must build the announcement file, in this case MyAnnc.ann. For more information on how to do this, see Creating Enhancement Announcements.


EnhEvent.Timeout

The Timeout property indicates the number of seconds after the EnhEvent.Start time that the event should be deleted by the client application. This value overrides the value set in EnhEvents.TimeOut.

This property is not implemented in version 1.0 of Broadcast Architecture.

Syntax

object.Timeout [ = dTimeout ]

Parts

object
Object expression that resolves to an EnhEvent object.
dTimeout
Double that indicates the number of seconds after the start time that the event should be deleted. If this value is not set, the default is 0.

Remarks

If no value is specified for this property, the default value for the enhancement stream, specified in EnhEvents.TimeOut, is used.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.Priority, EnhEvents.Priority


EnhEvent.Trigger

The Trigger property contains an identifier that specifies the trigger type of this event. This property is only valid if EnhEvent.IsTrigger is non-zero.

Syntax

object.Trigger [ = lTrigger ]

Parts

object
Object expression that resolves to an EnhEvent object.
lTrigger
Long that specifies the type of trigger. For more information about trigger identifiers and format, see Enhancement Triggers.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.IsTrigger


EnhEvent.UnFlatten

The Unflatten method converts an enhancement event that has been converted into low-level format by EnhEvents.Flatten or EnhEvent.Flatten back into its original high-level format.

Syntax

object.UnFlatten()

Parts

object
Object expression that resolves to an EnhEvent object.

Remarks

You can only call EnhEvent.UnFlatten for events that are part of an enhancement stream. Calling EnhEvent.UnFlatten for events that have not been added to an enhancement stream causes the method to return an error.

EnhEvent.UnFlatten only converts events that have been previously converted to low-level format by the Flatten method. Calling UnFlatten on an event that has not been flattened causes the method to exit without modifying the event.

This method converts a single event within the enhancement stream back into high-level format. To convert the entire stream, use EnhEvents.UnFlatten.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.UnFlatten, EnhEvent.Flatten, EnhEvents.Flatten

Examples

The following converts an event back into its original high-level format.

e.UnFlatten


EnhEvent.Until

The Until property specifies the end time for a repeated event, in seconds. In other words, unless EnhEvent.Repeat is zero, the event will repeat for Until seconds.

Syntax

object.Until [ = dUntil ]

Parts

object
Object expression that resolves to an EnhEvent object.
dUntil
Double that specifies the number of seconds.

Remarks

The value of Until is ignored if EnhEvent.Repeat is zero.

If Repeat is nonzero and Until is not specified or is set to zero, the repetition continues for the duration of the show, as specified in EnhEvents.ShowLength.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


EnhEvent.XMitDuration

The XMitDuration property contains the time required to transmit the event. This property is read-only.

Syntax

[ dDuration = ] object.XMitDuration

Parts

object
Object expression that resolves to an EnhEvent object.
lDuration
Double that receives the number of seconds required to transmit the event.

Remarks

XmitDuration is calculated based on the redundancy, length, and available bandwidth. The following equation is used to calculate the time required to transmit the event:

XmitDuration = ((1 + 1/Redundancy) * Length ) / (Bandwidth/8)

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.XMitName, EnhEvent.Name, EnhEvent.Length, EnhEvents.Overhead, EnhEvents.Redundancy, EnhEvents.Bandwidth


EnhEvent.XMitName

The XMitName property indicates the name of the transmitted file at the destination. This property is read-only.

Syntax

[ sName = ] object.XMitName

Parts

object
Object expression that resolves to an EnhEvent object.
sName
String that receives the filename.

Remarks

The value of XmitName is created from the values of EnhEvents.ShowName and the filename of the transmitted file as follows:

XmitName = "ShowName/FileName"

For example, if the title of the show's enhancements is "My Interactive Show" and the file being transmitted is "File1.htm" the value of EnhEvent.XmitName is "My Interactive Show/File1.htm"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.XMitDuration, EnhEvents.ShowName


EnhEvents

The EnhEvents object is a collection of EnhEvent objects. Using the methods and properties of the EnhEvents interface you can create or parse an enhancement stream.

The EnhEvents object has the following properties and methods.

Property | Description
Bandwidth | Bandwidth of the transmission medium, in bits per second.
Count | Number of EnhEvent objects in the collection. This property is read-only.
DependLength | Length of a file and its dependencies, in bytes.
ErrorCount | Number of syntax errors in the enhancement stream.
ErrorList | Retrieves a syntax error from the error array.
FindHandle | Returns the event associated with the specified handle.
FindTime | Returns the event starting at the specified time.
FPS | Frames per second of the enhancement stream.
FrameName | Retrieves a name from frame name array.
HRef | Indicates when HTML hyperlink dependencies should be resolved.
Item | Retrieves the specified event from the collection.
LastAdd | Retrieves the event last added to the collection.
LeadTime | Specifies the amount of time, in seconds, to wait between downloading the last dependency of an trigger event before firing the trigger.
LoadBias | Specifies the time offset to use when loading or merging a file.
Overhead | FTS overhead for file transmission, in bytes.
ParseTime | Converts an extended time string in Society of Motion Picture and Television Engineers (SMPTE) format into a Double.
Priority | Default transmission priority for the enhancement stream. This property is not yet implemented.
Redundancy | FTS redundancy, stored as the reciprocal of the extra duration.
ShowLength | Length of the show associated with this enhancement stream, in seconds.
ShowName | Name of the show or episode associated with the enhancement stream.
Style | This property is reserved for future use.
TimeOut | Default time-out interval for the enhancement stream.
TimeStr | Converts a Double into an extended SMPTE time string.
Title | Title of the enhancement stream.

Method | Description
Add | Add a new event object to the enhancement stream.
AddEvent | Adds the specified event object to the enhancement stream.
AddText | Add an event to the enhancement stream by specifying stream language text.
Clear | Remove all objects from the enhancement stream.
Flatten | Convert the enhancement stream events from high-level syntax to low-level syntax.
Load | Load an enhancement stream from a file.
Store | Save the enhancement stream to a file.
UnFlatten | Convert a previously flattened stream back into high-level events.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


EnhEvents.Bandwidth

The Bandwidth property indicates the bandwidth of the transmission medium.

Syntax

object.Bandwidth [ = dBps ]

Parts

object
Object expression that resolves to an EnhEvents object.
dBps
Double that specifies the transmission rate, in bits per second. If this value is not set, the default is 9600.

Remarks

This value is used by the stream compiler during flattening and optimization of the stream.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.Length, EnhEvents.Overhead, EnhEvents.Redundancy, EnhEvent.XMitDuration


EnhEvents.Count

The Count property indicates the number of events in the enhancement stream. This property is read-only.

Syntax

[ lCount = ] object.Count

Parts

object
Object expression that resolves to an EnhEvents object.
lCount
Long that indicates the number of events.

Examples

The following example uses the count property to return the last event in the collection.

Set e = evs.Item(evs.Count - 1)

Note that because events are stored as a 0-based list, the index of the last item is Count – 1.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.Item


EnhEvents.DependLength

The DependLength property contains the length of a file and its dependencies, in bytes. This property is read-only.

Syntax

[ lLength = ] object.DependLength( sFilename )

Parts

object
Object expression that resolves to an EnhEvents object.
sFilename
String that contains the name of the file.
lLength
Long that receives the total number of bytes in the file and all its dependencies.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Dependencies, EnhEvent.Length, EnhEvent.XmitDuration


EnhEvents.ErrorCount

The ErrorCount property contains a count of the syntax errors in the enhancement stream. It counts the syntax errors discovered in the last call to EnhEvents.Load or EnhEvents.AddText. This property is read-only.

Syntax

[ lCount = ] object.ErrorCount

Parts

lCount
Long that receives the number of syntax errors.
object
Object expression that resolves to an EnhEvents object.

Remarks

The EnhEvents.ErrorList property contains an array of strings that describe the syntax errors. The error information includes the line number that contains the syntax error. The line number specifies the line in the enhancement stream file loaded by EnhEvents.Load.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

Examples

The following example displays a message box indicating the number of syntax errors currently in the enhancement stream.

Msgbox "Number of syntax errors:"+CStr(evs.ErrorCount)


EnhEvents.Errorlist

The Errorlist property retrieves a specific error from the syntax error array created during a call to EnhEvents.Load or EnhEvents.AddText. This property is read-only.

Syntax

[ sList = ] object.Errorlist( lIndex )

Parts

sList
String that describes the syntax error.
object
Object expression that resolves to an EnhEvents object.
lIndex
Long that indicates which element of the array to return.

Remarks

The ErrorList property contains an array of strings that describe the syntax errors. The error information includes the line number that contains the syntax error. The line number specifies the line in the enhancement stream file loaded by EnhEvents.Load.

To fix a syntax error, you would typically open and edit the stream syntax file in a text error such as Notepad.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.ErrorCount


EnhEvents.FindHandle

The FindHandle property returns a reference to the event that has the specified handle. This property is read-only.

Syntax

Set oEvent = object.FindHandle ( lHandle )

Parts

object
Object expression that resolves to an EnhEvents object.
lHandle
Long that contains the event handle. This value will be compared to each event's EnhEvent.Handle property until a match is found. If a match is not found, FindHandle returns an error
oEvent
EnhEvent that receives the event specified by lHandle.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.FindTime

Examples

The following example saves a handle to an event in the enhancement stream, and then uses FindHandle to recall that event.

'Declare variables
Dim Ev As IEnhEvents
Dim e As IEnhEvent
Dim lHandle As Long

'create the collection
Set Ev = New EnhEvents

'add an event to the collection
Ev.Add 15, "EventA"

'save a handle to EventA,
'(which is currently the last-added event)
lHandle = Ev.LastAdd.Handle

...

'recall EventA from the collection using the previously-saved handle
Set e = Ev.FindHandle(lHandle)


EnhEvents.FindTime

The FindTime property returns a reference to the event that starts at the specified time. This property is read-only.

Syntax

Set oEvent = object.FindTime( dTime )

Parts

object
Object expression that resolves to an EnhEvents object.
dTime
Double that specifies the start time. This value will be compared to each events EnhEvent.Start property until a match is found. If a match is not found, FindTime returns an error.
oEvent
EnhEvent object that receives the reference to the event with the start time specified by dTime.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

Examples

The following example looks up an event in the EnhEvents collection by start time.

'Declare variables
Dim Ev As IEnhEvents
Dim e As IEnhEvent
Dim lHandle As Long

'create the collection
Set Ev = New EnhEvents

'add events to the collection
Ev.Add 15, "EventA"
Ev.Add 45, "EventB"
Ev.Add 25, "EventC"

'find EventB in the collection by specifying
'its start time.
Set e = Ev.FindTime(45)


EnhEvents.FPS

The FPS property retrieves or sets the frames per second.

Syntax

object.FPS [ = dfps ]

Parts

object
Object expression that resolves to an EnhEvents object.
dfps
Double that indicates the frames per second.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.ParseTime


EnhEvents.FrameName

The FrameName property retrieves or sets the names of HTML frames. These values are stored in an array.

Syntax

object.FrameName( lIndex ) [ = sName ]

Parts

object
Object expression that resolves to an EnhEvents object.
lIndex
Long that indicates which element of the 0-based array to set or retrieve.
sName
String that contains the name of the HTML frame.

Remarks

For example, in a multiframe enhancement, you can use FrameName to store the names of the enhancement frames. Your application can then retrieve the name of a particular frame from the array, instead of explicitly referencing the frames by name.

Using the FrameName property instead of explicit frame names makes your application more portable and easier to maintain. If the names of the enhancement frames change, you will only have to update them once.

Examples

The following example uses FrameName to store the names of three HTML frames names. It then retrieves the name of the first frame to add a Nav trigger event.

'store the frame names in the array
evs.FrameName(0) = "Left"
evs.FrameName(1) = "Video"
evs.FrameName(2) = "Bottom"

evs.AddText("00:10:30:00 trigger ( 2 <NewEnh.htm>[targ:"+evs.FrameName(0)+"]") only;")

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


EnhEvents.HRef

The HRef property indicates when HTML hyperlink dependencies should be resolved.

Syntax

object.HRef [ = lHref ]

Parts

object
Object expression that resolves to an EnhEvents object.
lhref
Long that specifies when dependencies should be resolved. This can be a value in one of the following ranges:
Value | Description
< 0 | Resolve dependencies before the event.
0 | Do not resolve dependencies.
> 0 Resolve dependencies after the event.

Values of lhref greater than 0 are not supported in version 1.0 of Broadcast Architecture.

Remarks

This value can be overridden by individual events by setting the EnhEvent.HRef property. If neither value is set, the default is 0.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


EnhEvents.Item

The Item property returns the specified event from the enhancement stream. This property is read-only.

Syntax

Set oEvent = object.Item( lIndex )

Parts

object
Object expression that resolves to an EnhEvents object.
lIndex
Long that indicates the 0-based index of the event to retrieve.

Examples

The following example retrieves the first event in the enhancement stream. Because events are ordered in the collection by start time, this event is the first event that occurs.

Set e = evs.Item(0)

This could also be written as:

Set e = evs(0)

Note that because events are stored as a 0-based list, the index of the first item is 0.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.Count


EnhEvents.LastAdd

The LastAdd property returns a reference to the event that was last added to the enhancement stream. This property is read-only.

Syntax

[ Set oEvent = ] object.LastAdd

Parts

object
Object expression that resolves to an EnhEvents object.
oEvent
EnhEvent that receives the last event added to the collection.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.Handle, EnhEvents.Add, EnhEvents.AddText, EnhEvents.FindHandle, EnhEvents.FindTime

Examples

The following example displays a message box containing the text Second Event, because that was the event most recently added to the collection.

'Declare variables
Dim Ev As IEnhEvents
Dim e As IEnhEvent

'Create the EnhEvents collection
Set Ev = New EnhEvents

'Add two events to the collection
Ev.Add 35, "First Event"
Ev.Add 25, "Second Event"

'retrieve the last-added event
Set e = Ev.LastAdd

'display the name of the last-added event
MsgBox e.Name


EnhEvents.LeadTime

The LeadTime property specifies the time to wait after downloading a trigger event's dependency files before firing the trigger.

Syntax

object.LeadTime [ = dTime ]

Parts

object
Object expression that resolves to an EnhEvents object.
dTime
Double that specifies the number of seconds the transmitter should wait. This must be a positive value. The default value is 5.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Dependencies


EnhEvents.LoadBias

The LoadBias property specifies the time offset to use when loading or merging a file.

Syntax

object.LoadBias [ = dLoadBias ]

Parts

object
Object expression that resolves to an EnhEvents object.
dLoadBias
Double that specifies the time offset, in seconds. This value can be either positive or negative.

Remarks

By default, when you load or merge an enhancement stream, the timing of events in that stream are relative to the start time of the show. However, you can set the event times in the loaded stream to be relative to another time.

To do this, set an offset time for stream in EnhEvents.LoadBias. This causes the events in the loaded stream to be relative to the start time of the show + the time offset you specify.

For example, if you set EnhEvents.LoadBias to 30 and then load a stream, the timing of events in the loaded stream will be offset by thirty seconds. If the loaded stream originally specified that Event A start at time 00:00.0, that event now starts at 00:30.0.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Merging Enhancement Streams, EnhEvents.Load

Examples

The following example merges two streams together, offsetting the timing of events in the second stream by thirty minutes.

Dim evs As IEnhEvents
Set evs = New EnhEvents

'load the first stream
evs.Load("Stream1.str")

'set the offset time to thirty minutes
evs.LoadBias = 1800

'merge Stream2 with Stream1
'the events in Stream2 will be offset by thirty minutes
'relative to the start of Stream2
evs.Load("Stream2.str")


EnhEvents.Overhead

The Overhead property specifies the fixed overhead for FTS transmission, in bytes.

Syntax

object.Overhead [ = lOverhead ]

Parts

object
Object expression that resolves to an EnhEvents object.
lOverhead
Long that contains the FTS overhead, in bytes. The default value is 5120.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.Length, EnhEvents.Redundancy, EnhEvent.XmitDuration


EnhEvents.ParseTime

The ParseTime property converts a SMPTE time string into a Double. This property is read-only.

Syntax

[ dTime = ] object.ParseTime( sTime )

Parts

object
Object expression that resolves to an EnhEvents object.
sTime
String that specifies the time as an SMPTE time string. This can be one of the following formats, depending on the current frame rate.
SMPTE time format | Format | Example
30 frames per second | hh:mm:ss:ff | 01:00:30:15
drop frame (29.97 frames per second) | hh:mm:ss;ff | 01:00:30;15
fractional seconds | hh:mm:ss.dd | 01:00:30.5

dTime
Double that receives the time specified in sTime in numerical format.

Remarks

You can set the frame rate using EnhEvents.FPS.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.TimeStr

Examples

The following example sets the variable dTime to 342.0.

Dim dTime As Double
Dim evs As EnhEvents
Set evs = new EnhEvents

dTime = evs.ParseTime("00:05:42:00")


EnhEvents.Priority

The Priority property indicates the default priority for the events in the enhancement stream. This property is not yet implemented.

Syntax

object.Priority [ = lPriority ]

Parts

object
Object expression that resolves to an EnhEvents object.
lPriority
Long that indicates the default priority.

Remarks

This property can be overridden for an individual event by setting EnhEvent.Priority. If neither value is set, the default priority is 5.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


EnhEvents.Redundancy

The Redundancy property contains the FTS redundancy.

Syntax

object.Redundancy [ = lRedun ]

Parts

object
Object expression that resolves to an EnhEvents object.
lRedun
Long that indicates the FTS redundancy. The default value is 5.

Remarks

The value of Redundancy is the reciprocal of the amount of extra bandwidth used for forward error correction. For example, if you set the redundancy to 10, the amount of bandwidth allotted to forward error correction is 1/10, or 10%. In other words, an additional number of bytes, equal to 10% of the original file, will be transmitted for error correction.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.Overhead, EnhEvent.XmitDuration


EnhEvents.ShowLength

The ShowLength property specifies the length of the interactive episode, in seconds.

Syntax

object.ShowLength [ = dLength ]

Parts

object
Object expression that resolves to an EnhEvents object.
dLength
Double that indicates the show length, in seconds. The default value is 0.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.Timeout


EnhEvents.ShowName

The ShowName property is the name of the show or episode associated with the event stream.

Syntax

object.ShowName [ = sName ]

Parts

object
Object expression that resolves to an EnhEvents object.
sName
String that contains the name of the show. If this value is not set, the default is an empty string ("").

Remarks

This property is used to compute EnhEvent.XmitName.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.Title


EnhEvents.TimeOut

The TimeOut property indicates the default number of seconds after which events are deleted from the enhancement spool directory.

Syntax

object.TimeOut [ = dTimeout ]

Parts

object
Object expression that resolves to an EnhEvents object.
dTimeout
Double that indicates the number of seconds for garbage collection. The default value is 0.

Remarks

You can override this value for individual events by setting the EnhEvent.Timeout property.

The deletion of expired enhancements is automatically handled by the Enhancement control, EnhCtrl, on the client computer.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.ShowLength


EnhEvents.TimeStr

The TimeStr property converts a double into a SMPTE time string. This property is read-only.

Syntax

[ sTime = ] object.TimeStr( dTime )

Parts

object
Object expression that resolves to an EnhEvents object.
dTime
Double that specifies the time.
sTime
String that receives the time specified in dTime as an SMPTE time string, of the format "hh:mm:ss.dd".

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.ParseTime

Examples

The following example sets the variable sTime to "00:05:42.00".

Dim sTime As String
Dim evs As EnhEvents
Set evs = new EnhEvents

sTime = evs.TimeStr(342.0)


EnhEvents.Title

The Title property contains the title of the enhancement stream.

Syntax

object.Title [ = sTitle ]

Parts

object
Object expression that resolves to an EnhEvents object.
sTitle
String that contains the title. If this value is not set, the default is an empty string ("").

Remarks

Title specifies the title of the enhancement stream, not the interactive episode. The title of the interactive episode is stored in EnhEvents.ShowName.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


EnhEvents.Add

The Add method creates an event and adds it to the enhancement stream.

Syntax

[Set oEvent = ] object.Add( dTime, sName )

Parts

object
Object expression that resolves to an EnhEvents object.
dTime
Double that contains the start time of the event, in seconds. This value is used to initialize the EnhEvent.Start property of the new object.
sName
String that contains the event name. This value is used to initialize the EnhEvent.Name property of the new event.
oEvent
EnhEvent object that was added to the EnhEvents collection.

Remarks

The Visual Basic implementation of Add does not return a reference to the newly added event. However, you can retrieve the event from the collection by using the LastAdd, FindTime, or FindHandle properties. Once you have a reference to the object, you can edit its properties or delete it from the collection.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.AddText

Examples

The following example creates an EnhEvents collection and adds enhancement events to the collection.

'Declare variables
Dim Ev As IEnhEvents
Dim e As IEnhEvent

'Create the EnhEvents collection
Set Ev = New EnhEvents

'Add two events to the collection
Ev.Add 35, "EventA"
Ev.Add 25, "EventB"

'Add another event to the collection
'and store the event object in e.
Set e = Ev.Add(15, "EventC")


EnhEvents.AddEvent

The AddEvent method adds the specified event object to the enhancement stream.

Syntax

object.AddEvent( oEvent )

Parts

object
Object expression that resolves to an EnhEvents object.
oEvent
EnhEvent object to add to the enhancement stream.

Remarks

To use AddEvent, your application creates an EnhEvent object and adds it to the enhancement stream. The two methods, EnhEvents.Add and EnhEvents.AddText automatically create an EnhEvent object and add it to the stream.

You cannot add an event object to more than one stream simultaneously. Attempting to add an event that is part of a stream to another stream causes AddEvent to return an error.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.Add, EnhEvents.AddText, Adding Events to an Enhancement Stream

Examples

The following example uses the AddEvent method to add an event to the enhancement stream.

'Create the event object e
Dim e As IEnhEvent
Set e = New EnhEvent

'Initialize the properties of event e.
e.Text = "00:03:20.0 MyFile.htm only;"

'Add the event to the stream.
evs.AddEvent e

'Change the starting time of the event. Note that because
'the event e and the event in the stream are the same object
'both the stream and e object variable will reflect the change.
e.Start = 350


EnhEvents.AddText

The AddText method adds an event to the enhancement stream using the stream language.

Syntax

object.AddText( sText )

Parts

object
Object expression that resolves to an EnhEvents object.
sText
String that contains the stream language. This value is used to initialize the EnhEvent.Text property of the new event. If this string is empty (""), the event is not added.

To locate more information about stream compiler language syntax, see Further Information on Data Services for the Client.

Remarks

You can also use this method to set the value of enhancement stream global variables, namely BandWidth, Href, FrameName, Overhead, Priority, FPS, Redundancy, TimeOut, LeadTime, Style, ShowLength, and ShowName. The value of these global variables are wrapped by the EnhEvents properties of the same name.

For example, you can set the value of EnhEvents.Redundancy to 10 with the following:

evs.AddText("Redundancy = 10;")

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.Add, EnhEvent.Text

Examples

The following example adds a Nav trigger event to the enhancement stream. Note that because the only keyword is specified, the file NewEnh.htm is assumed to already exist on the client's computer and is not scheduled to be transmitted.

evs.AddText("00:10:30:00 trigger ( 2 <NewEnh.htm>[targ:Left]) only;")

The next example adds an announcement to the enhancement stream. Note that before you can transmit this event, you must build the announcement file, in this case MyAnnc.ann. For more information on how to do this, see Creating Enhancement Announcements.

evs.AddText("00:00:00.50 announce ( ""MyAnnc.ann"" ) ;")


EnhEvents.Clear

The Clear method removes all events from the enhancement stream. The event objects are destroyed.

Syntax

object.Clear()

Parts

object
Object expression that resolves to an EnhEvents object.

Remarks

If you load an enhancement stream from a file without first clearing the current enhancement stream, the two streams are merged.

For example, if you had a stream with events A and B occurring at 15 and 30 seconds, and a second stream with events C and D occurring at 20 and 45 seconds, the merged stream would have events in the following order: A, C, B, and D.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.Load


EnhEvents.Flatten

The Flatten method converts enhancement stream events from high-level syntax to low-level syntax. This method can cause the stream compiler to add new events and change event times slightly.

It is recommended that your application call Flatten before it transmits the enhancement stream.

Syntax

object.Flatten()

Parts

object
Object expression that resolves to an EnhEvents object.

Remarks

The Flatten method resolves high-level events into low-level ones. For example, if you had defined an FTS-download event for an HTML file that contained four GIFs, the Flatten method would turn this event into five FTS-download events, one for the main file and each image dependency.

The enhancement stream must be converted to low-level syntax before it can be transmitted by the ipsend object.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Converting Events to Low-level Syntax, EnhEvents.Store, ipsend

Examples

The following example loads an enhancement stream from the file EnhStr.txt, converts the stream to low-level syntax, and then saves the low-level stream to the file EnhStrFlat.txt.

Dim evs As IEnhEvents
Set evs = New EnhEvents
evs.Load("C:\EnhTools\EnhStr.txt")
evs.Flatten
evs.Store("C:\EnhTools\EnhStrFlat.txt")


EnhEvents.Load

The Load method loads an enhancement stream from a file into an EnhEvents collection.

Syntax

object.Load( sFilename )

Parts

object
Object expression that resolves to an EnhEvents object.
sFilename
String that specifies the filename.

Remarks

If there are syntax errors in the stream compiler syntax loaded from the file, these are enumerated in EnhEvents.ErrorCount. Additional information about the errors is stored in EnhEvents.ErrorList.

If you load an enhancement stream from a file without first clearing the current enhancement stream, the two streams are merged.

For example, if you had a stream with events A and B occurring at 15 and 30 seconds, and a second stream with events C and D occurring at 20 and 45 seconds, the merged stream would have events in the following order: A, C, B, and D.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.Store, EnhEvents.Clear

Examples

The following example loads the stream stored in the file Stream.txt into an events collection.

evs.Load("Stream.txt")


EnhEvents.Store

The Store method saves the enhancement stream to a text file. The stream is stored in stream compiler syntax language.

Syntax

object.Store( sFilename )

Parts

object
Object expression that resolves to an EnhEvents object.
sFilename
String that specifies the filename.

Remarks

If this file specified by sFilename does not currently exist, it is created. If the file exists, it is overwritten.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvents.Load

Examples

The following example stores the enhancement stream in a file named Stream.txt.

evs.Store ("Stream.txt")


EnhEvents.UnFlatten

The Unflatten method converts a enhancement stream that has been converted into low-level format by EnhEvents.Flatten or EnhEvent.Flatten back into its original high-level format.

Syntax

object.Unflatten()

Parts

object
Object expression that resolves to an EnhEvents object.

Remarks

EnhEvents.UnFlatten only converts streams that have been previously converted to low-level format by the Flatten method. Calling EnhEvents.UnFlatten on a stream that has not been flattened causes the method to exit without modifying the stream.

EnhEvents.UnFlatten converts the entire enhancement stream. To convert a single event, use EnhEvent.UnFlatten.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

EnhEvent.UnFlatten, EnhEvents.Flatten, Converting Events to Low-level Syntax

Examples

The following example converts a low-level stream back into its original high-level format.

'Convert the stream to low-level format.
evs.Flatten

'Additional code that operates on the low-level stream.
...

'Convert the stream back to high-level format.
evs.UnFlatten


Annc

The Annc object stores information about an enhancement announcement and can be used create enhancement announcement files. It has the following properties and methods:

Note that some of the properties of the Annc object must be set in order for the resulting announcement file to be valid. For other properties the default values are sufficient. The properties that you must set are labeled in the description column of the following table.

Property | Description
AnnouncementType | Specifies the type of announcement.
Channel | The channel on which the interactive show appears.
Netcard | The network interface card IP address.
Network | The call letters of the television network affiliate.
PreloadURL | The location of the starting page of the interactive show. You must set this value.
SessionID | The session identifier.
SessionVersion | The version number.
ShowLength | Length of the interactive show, in seconds.
ShowName | Name of the show being interactive.
ShowRef | Show reference of the show being enhanced.
ShowStart | The starting time and date of the interactive show.
Station | The name of the station broadcasting the interactive show.
Title | The title of the enhancement. You must set this value.
TriggerIP | The IP address and port to which the client tunes to receive triggers for the interactive show. You must set this value.
TTL | Time-to-live for the enhancement. You must set this value
TuningSpace | The name of the tuning space on which the client receives the interactive show.
UserID | The owner of the announcement.

Method | Description
Clear | Resets the announcement object's properties to their default values.
Load | Loads an announcement from a file.
Store | Saves an announcement to a file.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


Annc.AnnouncementType

The AnnouncementType property specifies the type of the announcement.

Syntax

object.AnnouncementType [ = lType ]

Parts

object
Object expression that resolves to an Annc object.
lType
Long that indicates the announcement type. This can be one of the following values. If AnnouncementType is not set, the default is anncCurrent.
Type | Description
anncNone | No announcement is set.
anncCurrent | Announces an enhancement for a show that is currently broadcast.
anncTimeSlice | Announces an enhancement that is on for a specified amount of time, regardless of whether that time period matches a show.
anncFuture | Announces an enhancement show that will be broadcast in the future.
anncChannel | Announces a channel enhancement.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


Annc.Channel

The Channel property specifies the channel number of the interactive show.

Syntax

object.Channel [ = lchannel ]

Parts

object
Object expression that resolves to an Annc object.
lchannel
Long that contains the channel number of the interactive show. This channel is located in the tuning space specified by Annc.TuningSpace. The default value is 0.

Remarks

This property is one of the components that the Annc object uses to create the show reference string stored in the Annc.ShowRef property.

You are not required to set this property in order for the announcement file created by Annc.Store to be valid. The default value is sufficient in many cases. For example, if you are creating an announcement for a currently-broadcast show, the client is already tuned to the proper channel and does not require this information.

Typically, this value is only set if you are creating a channel-specific future enhancement announcement.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Annc.TuningSpace, Annc.ShowRef

Examples

The following example sets the channel number for the announcement to 9.

ann.Channel = 9


Annc.Netcard

The Netcard property specifies the IP address of the network interface card used by the broadcast head-end.

Syntax

object.Netcard [ = sNetCard ]

Parts

object
Object expression that resolves to an Annc object.
SNetCard
String that contains the network interface card address. This string should be in standard IP dot notation: "xxx.xxx.xxx.xxx". The default value is an empty string.

Remarks

You are not required to set this property in order for the announcement file created by Annc.Store to be valid. The default value is sufficient in many cases.

Examples

The following example sets the network interface card IP address to "255.55.221.255".

ann.Netcard = "255.55.221.255"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Annc.TriggerIP


Annc.Network

The Network property contains the call letters of the network affiliate of the station broadcasting the interactive show.

Syntax

object.Network [ = sNetwork ]

Parts

object
Object expression that resolves to an Annc object.
sNetwork
String that contains the call letters of the television network affiliate. The default value is an empty string.

Remarks

The Network property stores the call letters of the network affiliate of the station. This affiliate can be the same as the station in some cases. In other situations, a national network is the affiliate for a local station.

This property is one of the components that the Annc object uses to create the show reference string stored in the Annc.ShowRef property.

You are not required to set this property in order for the announcement file created by Annc.Store to be valid. The default value is sufficient in many cases.

Examples

The following example sets the network affiliate to the MSNBC.

ann.Network = "MSNBC"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Annc.Station


Annc.PreloadURL

The PreloadURL property contains the filename and location of the starting page of the interactive show. This is the page that Microsoft® WebTV® for Windows® or the Web browser loads when the interactive show starts.

Syntax

object.PreloadURL [ = sPreloadURL ]

Parts

object
Object expression that resolves to an Annc object.
sPreloadURL
String that contains the filename and location. The default value is an empty string.

Remarks

You must set a value for PreloadURL. Otherwise the announcement file created by Annc.Store will not be valid.

Examples

The following example sets the preload URL.

ann.PreloadURL = "MyShow\FirstPage.htm"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


Annc.SessionID

The SessionID property contains the session identifier.

Syntax

object.SessionID [ = lSessionID ]

Parts

object
Object expression that resolves to an Annc object.
lSessionID
Long that contains the session identifier. This can be any non-zero integer. The default value is 1.

Remarks

The session identifier is used by the SAP/SDP protocol to track which authoring tool generated the announcement. You can either select an identifier for your authoring tool and set that value in SessionID, or use the default value.

In other words, you do not have to set the value of this property in order for the announcement file generated by Annc.Store to be valid. The default value is sufficient.

Examples

The following example sets the session identifier. Note that ann is an Annc object variable.

ann.SessionID = 2745

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Annc.SessionVersion


Annc.SessionVersion

The SessionVersion property contains the session version number.

Syntax

object.SessionVersion [ = lversion ]

Parts

object
Object expression that resolves to an Annc object.
lversion
Long that contains the version number. This can be any non-zero integer. The default value is 1.

Remarks

The version identifier is used by the SAP/SDP protocol for tracking purposes.

You do not have to set the value of this property in order for the announcement file generated by Annc.Store to be valid. The default value is sufficient.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Annc.SessionID


Annc.ShowLength

The ShowLength property specifies the duration of the interactive show, in seconds.

Syntax

object.ShowLength [ = dShowLength ]

Parts

object
Object expression that resolves to an Annc object.
dShowLength
Double that contains the length of the interactive show, in seconds. The default value is 0.

Remarks

You are not required to set this property in order for the announcement file created by Annc.Store to be valid. The default value is sufficient in many cases, such as announcements for current shows.

Examples

The following examples sets the show length to 30 minutes. Note that ann is an Annc object variable.

ann.ShowLength = 1800

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Annc.ShowStart


Annc.ShowName

The ShowName property specifies the name of the show being enhanced.

Syntax

object.ShowName [ = sName ]

Parts

object
Object expression that resolves to an Annc object.
sName
String that contains the name of the show being enhanced. The default value is an empty string.

Remarks

The ShowName property stores the name of the show being enhanced. This is typically not the same as the title of the interactive version of the show, which is stored in Annc.Title.

You are not required to set this property in order for the announcement file created by Annc.Store to be valid. The default value is sufficient in many cases.

Examples

The following example sets the name of the show being enhanced to "Time & Again". Note that ann is an Annc object variable.

ann.ShowName = "Time & Again"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Annc.Title


Annc.ShowRef

The ShowRef property contains the show reference that describes the interactive show.

Syntax

object.ShowRef [ = sShowRef ]

Parts

object
Object expression that resolves to an Annc object.
sShowRef
String that contains the show reference of the interactive show. For details about the format of this string, see Show Reference Format.

Remarks

The Annc object automatically updates the show reference when one of its component fields changes and vice versa. Thus you can either set the show reference string explicitly in ShowReference or you can set the values for the Station, Network, TuningSpace, ShowName, Channel, ShowStart, and ShowLength properties and the Annc object will build the corresponding show reference string and store it in ShowReference.

Typically you do not set the ShowReference property directly. Instead you set values for the component properties mentioned preceding. The Annc object automatically generates the show reference for you and stores the value in ShowReference.

Examples

The following example sets the show reference by setting its component properties.

Dim ann As Annc
Set ann = New Annc

'Set values for the show reference component properties.
ann.Station = "KZZZ"
ann.Network = "MSNBC"
ann.TuningSpace = "Broadcast"
ann.ShowName = "Time & Again"
ann.Channel = 9
ann.ShowLength = 1800

'Specify the announcement is for a future show
'(If the announcement is for a currently-broadcast show
' the show reference does not contain the start time and you can
' omit the following two lines.)
ann.AnnouncementType = anncFuture
ann.ShowStart = #2/4/1998 8:00PM#

'Store the show reference created by the Annc object
'in the string variable, MyShowRef.
MyShowRef = ann.ShowRef  'This sets the variable MyShowRef equal to
'"1998/2/4!0/0/0!20:0!0!0!0!0!0!0!0!0!'MSNBC'!'KZZZ'!'Broadcast'!'9'!'Time & Again'"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Show References, Show Reference Format, Annc.Station, Annc.Network, Annc.TuningSpace, Annc.ShowName, Annc.Channel, Annc.ShowStart, Annc.ShowLength


Annc.ShowStart

The ShowStart property specifies the starting time and date of the interactive show.

Syntax

object.ShowStart [ = dDate ]

Parts

object
Object expression that resolves to an Annc object.
dDate
Date that contains the date and time at which the interactive show starts. The default value is 12:00:00 A.M.

Remarks

You are not required to set this property in order for the announcement file created by Annc.Store to be valid. The default value is sufficient in many cases, such as announcements for current shows.

Examples

The following example sets the start time to 8:00 P.M. on February 4, 1998.

ann.ShowStart = #2/4/1998 8:00PM#

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Annc.ShowLength


Annc.Station

The Station property specifies the call letters of the broadcast station transmitting the interactive show.

Syntax

object.Station [ = sStation ]

Parts

object
Object expression that resolves to an Annc object.
sStation
String that contains the call letters of the station. The default value is an empty string.

Remarks

This property is one of the components that the Annc object uses to create the show reference string stored in the Annc.ShowRef property.

You are not required to set this property in order for the announcement file created by Annc.Store to be valid. The default value is sufficient in many cases.

Examples

The following example sets the Station property to a local broadcast station.

ann.Station = "KZZZ"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Annc.Channel


Annc.Title

The Title property specifies the title of the enhancement.

Syntax

object.Title [ = sTitle ]

Parts

object
Object expression that resolves to an Annc object.
sTitle
String that contains the title of the enhancement. The default value is an empty string.

Remarks

You must set a value for Title. Otherwise the announcement file created by Annc.Store will not be valid.

The Title property stores the title of the enhancement. This is typically different from the name of the show itself. The name of the show being enhanced is stored in Annc.ShowName.

The value of the Title property is used as the title of the enhancement in any user interface specifying the enhancement.

Examples

The following example sets a title for the interactive version of the show. The noninteractive show name is stored in Annc.ShowName.

ann.ShowName = "Time & Again Interactive"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Annc.ShowName


Annc.TriggerIP

The TriggerIP property specifies the IP address and port over which the broadcaster will transmit triggers for the interactive show.

Syntax

object.TriggerIP [ = sIP ]

Parts

object
Object expression that resolves to an Annc object.
sIP
String that contains the IP address and port the client should use to receive triggers for the interactive show. This string should have the format, "xxx.xxx.xxx.xxx:yyyy", where xxx.xxx.xxx.xxx specifies the IP address and yyyy the IP port. The default value is an empty string.

Remarks

You must set a value for TriggerIP. Otherwise the announcement file created by Annc.Store will not be valid.

Examples

The following example sets the trigger IP address and port.

ann.TriggerIP = "123.45.223.155:1850"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Annc.Netcard


Annc.TTL

The TTL property specifies the time-to-live for the enhancement.

Syntax

object.TTL [ = lTTL ]

Parts

object
Object expression that resolves to an Annc object.
lTTL
Long that specifies the time-to-live value. The default is 2.

The following table lists the threshold TTL values that define the scope of an IP multicast.
Threshold value | Description
0 | Restricted to same host
1 | Restricted to same subnetwork
32 | Restricted to same site
64 | Restricted to same region
128 | Restricted to same continent
256 | Unrestricted in scope

Remarks

You must set a value for TTL. Otherwise the announcement file created by Annc.Store will not be valid.

Examples

The following example sets time-to-live to continent scope.

ann.TTL = 128

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


Annc.TuningSpace

The TuningSpace property specifies the tuning space on which the broadcast clients will receive the interactive show.

Syntax

object.TuningSpace [ = sTS ]

Parts

object
Object expression that resolves to an Annc object.
sTS
String that contains the name of the tuning space used to receive the interactive show. For example "Cable". The default value is an empty string.

Remarks

This property is one of the components that the Annc object uses to create the show reference string stored in the Annc.ShowRef property.

You are not required to set this property in order for the announcement file created by Annc.Store to be valid. The default value, an empty string, means that the show reference built from this value applies to any tuning space.

Typically, this value is only set if you are creating a channel-specific future enhancement announcement.

Examples

The following sets the tuning space to analog television broadcasts.

ann.TuningSpace = "broadcast"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Annc.Channel


Annc.UserID

The UserID property specifies the owner of the announcement.

Syntax

object.UserID [ = sUser ]

Parts

object
Object expression that resolves to an Annc object.
sUser
String that identifies the WebTV for Windows user. This cannot be an empty string. If no owner is specified, the default value is "-".

Remarks

UserID is used as the first value in the owner field of the SAP/SDP announcement. For more information about enhancement announcements and the SAP/SDP protocol, see Enhancement Announcement Format and Announcement Format.

Examples

The following example sets the owner of the announcement to the enhancement filter.

ann.UserID = "enhfilt"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.


Annc.Clear

The Clear method resets the announcement object's properties to the default values.

object.Clear()

Parts

object
Object expression that resolves to an Annc object.

Examples

The following example clears the announcement object stored in the object variable ann.

ann.Clear

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Creating Enhancement Announcements, Annc.Load, Annc.Store


Annc.Load

The Load method loads an announcement from a text file into an announcement object.

Syntax

object.Load( sFilename )

Parts

object
Object expression that resolves to an Annc object.
sFilename
String that contains the path and filename of the file to load. By convention, announcement files use the extension .ann.

Remarks

Announcements can be stored as a text file and then broadcast to the client at a later time. The Annc.Load method loads the attributes of an announcement from an announcement file into an Annc object. The announcement can then be edited. After your application has made changes, the announcement can be saved to file using the Annc.Store method.

If you are loading announcement data into an Annc object that already has values set for its properties, Load clears the old values before it loads the announcement data into the object.

For more information about the format of announcement files, see Enhancement Announcement Format.

Examples

The following example loads the announcement stored in the file MyAnn.ann into the object variable, ann,

ann.Load "C:\EnhFiles\Announcements\MyAnn.ann"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Creating Enhancement Announcements, Enhancement Announcement Format, Annc.Clear, Annc.Store


Annc.Store

The Store method saves an announcement to a file. This file can then be broadcast to clients during an announcement event.

Syntax

object.Store( sFilename )

Parts

object
Object expression that resolves to an Annc object.
sFilename
String that contains the path and filename of the file in which to store the announcement. By convention, announcement files use the extension, .ann.

Remarks

Announcements can be stored as a text file and then broadcast to the client at a later time. The Annc.Store method saves the attributes of an announcement from an announcement object to an announcement file. The announcement can then be transmitted to clients during an announcement event.

For more information about the format of announcement files, see Enhancement Announcement Format.

Examples

The following example stores an announcement in the file MyAnn.ann. The values of the announcement's attributes are the values specified in the properties of the announcement object.

ann.Store "MyAnn.ann"

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in stream.idl.
Import Library: Included as a resource in stream.dll.
Unicode: Yes.

See Also

Creating Enhancement Announcements, Enhancement Announcement Format, Annc.Clear, Annc.Load


ipenhsnd Type Library

The ipenhsnd type library, Ipenhsnd.dll, provides objects your application can use to transmit enhancement stream events and files to broadcast clients. Included are cabinet utilities that enable your application to package and compress enhancement files for more efficient transmission.

The ipenhsnd type library contains the following objects:

  • ipsend, transmits enhancement stream events to broadcast clients.
  • EnhCab, creates and enumerates cabinet (.Cab) files.


ipsend

The ipsend object, provided by IPEnhSnd.dll, is the enhancement listener's counterpart at the head end. This objects transmits the enhancement events, triggers, announcements, and data, over the broadcast medium.

You can call the methods and properties of the ipsend object to programmatically control what is sent.

The ipsend object has the following properties, methods, and event.

Property | Description
AnnouncementAddress | IP address on which announcements are sent.
AnnouncementPort | IP port on which announcements are sent.
FTSAddress | IP address on which FTS transmissions are sent.
FTSPort | IP port on which FTS transmissions are sent.
NetCard | Specifies the network interface card used for transmission.
ReportStatus | Sets whether an enhancement control running in the same process as ipsend reports its status.
Status | Status of an enhancement control running in the same process as ipsend.
Throttle | Amount of bandwidth to use for FTS transmissions.
TriggerAddress | IP address on which triggers are sent.
TriggerPort | IP port on which triggers are sent.
TTL | Time-to-live for the transmission.

Method | Description
ConnectAnnouncement | Establishes a connection for transmitting announcements.
ConnectFTS | Establishes a connection for transmitting FTS files.
ConnectTrigger | Establishes a connection for transmitting triggers.
SendAnnouncement | Transmits an announcement.
SendDeleteAnnouncement | Transmits a delete announcement. A delete announcement removes enhancement data from the Guide database.
SendEvent | Parses and transmits an enhancement event.
SendFTSFile | Transmits an FTS file.
SendTrigger | Transmits a pre-formatted trigger.
TriggerCAB | Formats and transmits a Data trigger that unpacks a cabinet file.
TriggerFTS | Formats and transmits a Data trigger to download a file using FTS.
TriggerNavigate | Formats and transmits a Nav trigger.
TriggerScript | Formats and transmits a Script trigger.

Event | Description
StatusChanged | The status of an enhancement control running in the same process as ipsend changed.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.


ipsend.AnnouncementAddress

The AnnouncementAddress property is the IP address to use when sending announcements. This property is read-only.

Syntax

[ sIPAddr = ] object.AnnouncementAddress

Parts

object
Object expression that resolves to an ipsend object.
sIPAddr
String that receives the IP address. This address will be in the format xxx.xxx.xxx.xxx, for example 255.255.255.255.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.AnnouncementPort, ipsend.ConnectAnnouncement, ipsend.SendAnnouncement, ipsend.SendDeleteAnnouncement, ipsend.SendEvent


ipsend.AnnouncementPort

The AnnouncementPort property is the IP port to use when sending announcements. This property is read-only.

Syntax

[ iIPPort = ] object.AnnouncementPort

Parts

object
Object expression that resolves to an ipsend object.
iIPPort
Integer that receives the IP port.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.AnnouncementAddress, ipsend.ConnectAnnouncement, ipsend.SendAnnouncement, ipsend.SendDeleteAnnouncement, ipsend.SendEvent


ipsend.FTSAddress

The FTSAddress property specifies the IP address over which FTS transmissions are sent. This property is read-only.

Syntax

[ sIPAddr = ] object.FTSAddress

Parts

object
Object expression that resolves to an ipsend object.
sIPAddr
String that receives the IP address. This address will be in the format xxx.xxx.xxx.xxx, for example 255.255.255.255.

Remarks

The value returned by FTSAddress is set when you call ipsend.ConnectFTS.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.FTSPort, ipsend.SendFTSFile, ipsend.SendEvent


ipsend.FTSPort

The FTSPort property specifies the IP port over which FTS transmissions are sent. This property is read-only.

Syntax

[ iIPPort = ] object.FTSPort

Parts

object
Object expression that resolves to an ipsend object.
iIPPort
Integer that contains the port.

Remarks

The value returned by FTSPort is set when you call ipsend.ConnectFTS.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.FTSAddress, ipsend.SendFTSFile, ipsend.SendEvent


ipsend.NetCard

The NetCard property specifies the network card from which the enhancement stream, including triggers, FTS file transmissions, and announcements, is transmitted.

Syntax

object.NetCard [ = sNetcard ]

Parts

object
Object expression that resolves to an ipsend object.
sNetcard
String that contains the network card address. This address should be in the format xxx.xxx.xxx.xxx, for example 125.125.125.125.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.


ipsend.ReportStatus

The ReportStatus property specifies whether an enhancement control running in the same process as ipsend sends status reports to the ipsend object.

Syntax

object.ReportStatus = [ lStatus ]

Parts

object
Object expression that resolves to an ipsend object.
lStatus
Long that specifies whether enhancement controls report status. If this value is non-zero, the controls report status. If this value is zero, they do not. The default value is 0.

Remarks

The ReportStatus property is set by applications that need to determine the asynchronous state of an enhancement control. For example, a stream player could set this property in order to be able to track the status of the enhancement control it hosts to playback the stream.

If your application enables status reporting by setting ReportStatus to a non-zero value, it must disable status reporting before it releases the ipsend object. Otherwise, the ipsend object will not exit memory because of circular references to an internal enhancement status object.

If you have multiple enhancement controls running in the same process as ipsend, the ipsend object cannot distinguish between status change notifications for each enhancement control. To avoid confusion, it is recommended that you have only one enhancement control running in-process with ipsend.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.Status, ipsend.StatusChanged, Monitoring the Status of an Enhancement Control, Enhancement Control


ipsend.Status

The Status property specifies the current status of an enhancement control running in the same process as ipsend. This property is read-only.

Syntax

[ lStatus = ] object.Status

Parts

object
Object expression that resolves to an ipsend object.
lStatus
Long that indicates the current status reported by an enhancement control running in the same process as ipsend.

The following table lists the valid enhancement control status codes.
Status Code | Description
d_NOCONTROL | There is no enhancement control currently running in the same process as ipsend.
d_CONSTRUCTING | The control is being created.
d_INITIALIZING | The control is initializing.
d_CONNECTING | The control is connecting to a data stream.
d_READY | The control is running and is awaiting further commands.
d_READY_CONNECTED | The control is connected to a data stream and ready to receive enhancement stream events.
d_HANDLING_EVENT | The control is handling a stream event.
d_DESTRUCTING | The control is being destroyed.

Remarks

If you have multiple enhancement controls running in the same process as ipsend, the ipsend object cannot distinguish between status change notifications for each enhancement control. To avoid confusion, it is recommended that you have only one enhancement control running in-process with ipsend.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.StatusChanged, ipsend.ReportStatus, Monitoring the Status of an Enhancement Control, Enhancement Control


ipsend.Throttle

The Throttle property specifies the maximum bandwidth allotted to FTS transmissions.

Syntax

object.Throttle [ = lBandWidth ]

Parts

object
Object expression that resolves to an ipsend object.
lBandWidth
Long that specifies the allotted bandwidth, in bits per second.

Remarks

You can use this method to set an upper limit on the amount of bandwidth used to transmit FTS data. For example, if enhancements are transmitted to the client by being encoded in three VBI lines, the effective transmission bandwidth is approximately 9600 bits per second. You could set Throttle to 9600 to ensure that the transmission rate did not exceed the client's bandwidth.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.ConnectFTS, ipsend.SendFTSFile, ipsend.SendEvent

Examples

The following example limits the FTS bandwidth to 3200 bits per second, or the equivalent of transmission over a single VBI line.

isend.Throttle = 3200


ipsend.TriggerAddress

The TriggerAddress property specifies the IP address over which triggers will be sent. This property is read-only.

Syntax

[ sIPAddr = ] object.TriggerAddress

Parts

object
Object expression that resolves to an ipsend object.
sIPAddr
String that receives the IP address. This address will be in the format xxx.xxx.xxx.xxx, for example 255.255.255.255.

Remarks

The value returned by TriggerAddress is set when you call ipsend.ConnectTrigger.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.TriggerPort, ipsend.SendTrigger, ipsend.SendEvent


ipsend.TriggerPort

The TriggerPort property specifies the IP port over which triggers are sent. This property is read-only.

Syntax

[ iIPPort = ] object.TriggerPort

Parts

object
Object expression that resolves to an ipsend object.
iIPPort
Integer that receives the port.

Remarks

The value returned by TriggerPort is set when you call ipsend.ConnectTrigger.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.TriggerAddress, ipsend.SendTrigger, ipsend.SendEvent


ipsend.TTL

The TTL property specifies the time-to-live for the IP broadcasts sent by the ipsend object.

Syntax

object.TTL [ = lTTL ]

Parts

object
Object expression that resolves to an ipsend object.
lTTL
Long that specifies the time-to-live value. The default is 2. The following table lists the threshold TTL values that define the scope of an IP multicast.
Threshold value | Description
0 | Restricted to same host
1 | Restricted to same subnetwork
32 | Restricted to same site
64 | Restricted to same region
128 | Restricted to same continent
256 | Unrestricted in scope

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.


ipsend.ConnectAnnouncement

The ConnectAnnouncement method establishes a connection over which announcements can be sent.

Syntax

object.ConnectAnnouncement( sIPAddress, iIPPort )

Parts

object
Object expression that resolves to an ipsend object.
sIPAddress
String that contains the IP multicast address used to connect to the announcement stream. This address should be in the format xxx.xxx.xxx.xxx, for example 255.255.255.255.
iIPPort
String that contains the IP port.

Remarks

You should call this method before calling ipsend.SendAnnouncement.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.ConnectFTS, ipsend.ConnectTrigger, ipsend.AnnouncementAddress, ipsend.AnnouncementPort


ipsend.ConnectFTS

The ConnectFTS method establishes a connection for the transmission of FTS data.

Syntax

object.ConnectFTS( sAddress, iPort )

Parts

object
Object expression that resolves to an ipsend object.
sAddress
String that contains the IP address. This address should be in the format xxx.xxx.xxx.xxx, for example 255.255.255.255.
iPort
Integer that contains the IP port.

Remarks

You must call this method before calling ipsend.SendFTSFile.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.ConnectAnnouncement, ipsend.ConnectTrigger, ipsend.FTSAddress, ipsend.FTSPort, ipsend.Throttle


ipsend.ConnectTrigger

The ConnectTrigger method establishes a connection for sending triggers.

Syntax

object.ConnectTrigger( sAddress, iPort )

Parts

object
Object expression that resolves to an ipsend object.
sAddress
String that specifies the IP address. This address should be in the format xxx.xxx.xxx.xxx, for example 255.255.255.255.
iPort
Integer that specifies the IP port.

Remarks

You should call this method before calling ipsend.SendTrigger.

ConnectTrigger sets the values returned by ipsend.TriggerAddress and ipsend.TriggerPort.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.ConnectAnnouncement, ipsend.ConnectFTS


ipsend.SendAnnouncement

The SendAnnouncement method sends an enhancement announcement over the broadcast medium.

Syntax

object.SendAnnouncement( sAnncFilename )

Parts

object
Object expression that resolves to an ipsend object.
sAnncFilename
String that contains the source filename of the announcement. This file is a text file that specifies the announcement in SDP/SAP protocol. For more information, see Enhancement Announcement Format.

Remarks

Before you call this method, you must call ipsend.ConnectAnnouncement to establish a connection.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.SendTrigger, ipsend.SendFTSFile, ipsend.SendDeleteAnnouncement, ipsend.SendEvent


ipsend.SendDeleteAnnouncement

The SendDeleteAnnouncement method sends a delete announcement over the broadcast medium. A delete announcement removes data about a specific enhancement from the Guide database.

Syntax

object.SendDeleteAnnouncement( sAnncFilename )

Parts

object
Object expression that resolves to an ipsend object.
sAnncFilename
String that contains the source filename of the delete announcement. This file is a text file that specifies the announcement in SDP/SAP protocol. For more information, see Enhancement Announcement Format.

Remarks

This method deletes data for the enhancement specified in the file, sAnncFilename. Note that the content of this file is identical to the content of the file specified in the call to ipsend.SendAnnouncement. In other words, you can use the same file to delete enhancement data from the Guide database that you used to set it.

Before you call this method, you must call ipsend.ConnectAnnouncement to establish a connection.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.SendTrigger, ipsend.SendFTSFile, ipsend.SendAnnouncement, ipsend.SendEvent


ipsend.SendEvent

The SendEvent method parses and transmits an enhancement event.

Syntax

object.SendEvent( oEvent )

Parts

object
Object expression that resolves to an ipsend object.
oEvent
EnhEvent object that contains the event.

Remarks

SendEvent does not flatten the event. Your application should convert the event to low-level syntax before it calls SendEvent. For more information, see Converting Events to Low-level Syntax.

The event transmitted by SendEvent does not have to be part of an enhancement stream.

Examples

The following example transmits the enhancement event stored in the EnhEvent object, e.

evs.SendEvent e

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.SendAnnouncement, ipsend.SendDeleteAnnouncement, ipsend.SendFTSFile, ipsend.SendTrigger, ipsend.TriggerCAB, ipsend.TriggerFTS, ipsend.TriggerNavigate, ipsend.TriggerScript


ipsend.SendFTSFile

The SendFTSFile method sends FTS data.

Syntax

object.SendFTSFile( sSrcFilename )

Parts

object
Object expression that resolves to an ipsend object.
sSrcFilename
String that contains the name of the file at the transmission source or head end. This string can also contain a relative path to the file, for example, "Myshow/File1.htm". If sSrcFilename specifies a relative path, the client stores the file in the specified directory, as a subdirectory of the spool directory. This parameter cannot contain a fully-specified path.

Remarks

Before you call this method, you must call ipsend.ConnectFTS to establish a connection.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.SendAnnouncement, ipsend.SendTrigger, ipsend.FTSAddress, ipsend.FTSPort, Data Trigger, ipsend.Throttle, ipsend.SendEvent

Examples

The following example uses SendFTSFile to transmit the file, File1.htm, to the client. This file is stored on the client as "C:\Program Files\TV Viewer\Interactive Content\<random>\MyShow\File1.htm" where <random> is a random string generated by the broadcast client.

isend.SendFTSFile "MyShow\File1.htm"

The following causes File1.htm to be downloaded to the client and stored in the "C:\Program Files\TV Viewer\Interactive Content\<random>File1.htm" directory.

isend.SendFTSFile "File1.htm"


ipsend.SendTrigger

The SendTrigger method transmits a trigger to broadcast clients.

Syntax

object.SendTrigger( lKey, sData )

Parts

object
Object expression that resolves to an ipsend object.
lKey
Long that contains the trigger identifier. For more information about trigger identifiers and format, see Enhancement Triggers.
sData
String that contains the trigger data. The format of the data depends on the type of trigger sent.

When you call SendTrigger, it automatically calculates the trigger checksum value and appends it (and its enclosing brackets) to the end of the trigger string. Thus, you should not include a checksum value in the trigger string that you specify for sData.

Remarks

Before you call this method, you must call ipsend.ConnectTrigger to establish a connection.

This method differs from the ipsend.TriggerCAB, ipsend.TriggerFTS, ipsend.TriggerNavigate, and ipsend.TriggerScript methods in that it does not format the trigger string before transmission. Your application must ensure that the string specified by sData is formatted correctly as one of the formats specified in Enhancement Triggers.

SendTrigger is the only method you can use to transmit TVCrossover or user-defined triggers.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.SendFTSFile, ipsend.SendAnnouncement, Trigger Checksum Value, Enhancement Triggers, ipsend.TriggerCAB, ipsend.TriggerFTS, ipsend.TriggerNavigate, ipsend.TriggerScript, ipsend.SendEvent

Examples

The following examples use SendTrigger to transmit various types of enhancement triggers.

isend.SendFTSTrigger 1, "<CAB> bpc://msnbc/myshow/myfile.cab"
isend.SendFTSTrigger 4, "alert('You received a Script trigger!')"
isend.SendFTSTrigger 5, "<http://www.tvprogram.com>[program]"

The following example uses SendTrigger to transmit a trigger stored in a EnhEvent object, e.

isend.SendTrigger e.Trigger + e.Name


ipsend.StatusChanged

The StatusChanged event indicates that the status of an enhancement control running in the same process as ipsend has changed.

Syntax

Private Sub object_StatusChanged(lStatus As Long)

Parts

object
Object expression that resolves to an ipsend object.
lStatus
Long that indicates the current status reported by an enhancement control running in the same process as ipsend.

The following table lists the valid status codes for an enhancement control.
Status Code | Description
d_NOCONTROL | There is no enhancement control currently running in the same process as ipsend.
d_CONSTRUCTING | The control is being created.
d_INITIALIZING | The control is initializing.
d_CONNECTING | The control is connecting to a data stream.
d_READY | The control is running, but is not connected to a data stream.
d_READY_CONNECTED | The control is connected to a data stream and ready to receive enhancement stream events.
d_HANDLING_EVENT | The control is handling a stream event.
d_DESTRUCTING | The control is being destroyed.

Remarks

If you have multiple enhancement controls running in the same process as ipsend, the ipsend object cannot distinguish between status change notifications for each enhancement control. To avoid confusion, it is recommended that you have only one enhancement control running in-process with ipsend.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.ReportStatus, ipsend.Status, Monitoring the Status of an Enhancement Control, Enhancement Control


ipsend.TriggerCAB

The TriggerCAB method formats and transmits a Data trigger that unpacks a cabinet file on broadcast clients.

Syntax

object.TriggerCAB( sCabFilename )

Parts

object
Object expression that resolves to an ipsend object.
sCabFilename
String that contains the path and filename of the cabinet file to unpack.

Remarks

TriggerCAB differs from the SendTrigger method in that it formats the trigger string based on the parameters you pass in. SendTrigger requires a pre-formatted trigger string.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.TriggerFTS, ipsend.TriggerNavigate, ipsend.TriggerScript, Data Trigger, ipsend.SendTrigger, ipsend.SendEvent


ipsend.TriggerFTS

The TriggerFTS method formats and transmits a data trigger that sets up FTS data reception on broadcast clients.

Syntax

object.TriggerFTS( sIPAddress, iPort, sSubDir, lTimeout)

Parts

object
Object expression that resolves to an ipsend object.
sIPAddress
String that specifies the IP address on which the FTS will be transmitted. If this parameter is NULL or an empty string (""), TriggerFTS uses the values specified during the call to ipsend.ConnectFTS.
iPort
Integer that specifies the IP port.
sSubDir
String that specifies the directory name in which the transmitted files should be saved. Note that this value cannot contain subdirectories. For example, "MSNBC" is a valid value for sSubDir, but "MSNBC\InterNight" is not.

To store a transmitted file in a subdirectory of sSubDir, specify the subdirectory when the file is transmitted.

lTimeout
Long that specifies a timeout interval, in minutes. After lTimeout minutes have elapsed, the subdirectory is deleted. If this value is zero, TriggerFTS uses the default value of 120 minutes.

Remarks

TriggerFTS differs from the SendTrigger method in that it formats the trigger string based on the parameters you pass in. SendTrigger requires a pre-formatted trigger string.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.ConnectFTS, ipsend.TriggerCAB, ipsend.TriggerNavigate, ipsend.TriggerScript, Data Trigger, ipsend.SendTrigger, ipsend.SendEvent

Examples

The following initializes broadcast clients to receive FTS data on IP address 255.255.255.255, port 980. The client will store files received over that IP address and port in "C:\Program Files\TV Viewer\Interactive Content\<random>\MSNBC\", where <random> is a random string generated by the broadcast client.

isend.TriggerFTS "255.255.255.255", 980, "MSNBC", 120


ipsend.TriggerNavigate

The TriggerNavigate method formats and transmits a Nav trigger.

Syntax

object.TriggerNavigate( sURL, sTarget)

Parts

object
Object expression that resolves to an ipsend object.
sURL
String that specifies the location of the enhancement page to be displayed. This location can be either a fully-specified Broadcast Architecture URL, or a location relative to the enhancement's base page.

If you are displaying a new enhancement base page, you should use a fully-specified Broadcast Architecture URL. This is because the new base typically will be located in a directory that is not a subdirectory of the old base page. In other words, you typically cannot specify a relative path to a new base page.

sTarget
String that specifies the name of the target element in which to display the new content. The target element can be a set of <FRAME>, <IFRAME>, <SPAN>, or <DIV> tags. If there is no target because this is a base page navigation, specify sTarget as NULL or an empty string ("").

Remarks

TriggerNavigate differs from the SendTrigger method in that it formats the trigger string based on the parameters you pass in. SendTrigger requires a pre-formatted trigger string.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.TriggerCAB, ipsend.TriggerFTS, ipsend.TriggerScript, Nav Trigger, ipsend.SendTrigger, ipsend.SendEvent

Examples

The following example causes the client to display new enhancement content.

isend.TriggerNavigate "bpc://msnbc/InterNight/File1.htm", ""
isend.TriggerNavigate "MyEnh.htm", "Left"


ipsend.TriggerScript

The TriggerScript method formats and transmits a script trigger.

Syntax

object.TriggerScript( sScript, sLanguage)

Parts

object
Object expression that resolves to an ipsend object.
sScript
String that contains the script statements to run on the client.
sLanguage
String that specifies the scripting language used in sScript.

The current version of Broadcast Architecture only supports the default scripting language, Microsoft® JScript™. Because the current version of the client does not recognize sLanguage, you should specify an empty string ("") for this parameter.

Remarks

TriggerScript differs from the SendTrigger method in that it formats the trigger string based on the parameters you pass in. SendTrigger requires a pre-formatted trigger string.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

ipsend.TriggerCAB, ipsend.TriggerFTS, ipsend.TriggerNavigate, Script Trigger, ipsend.SendTrigger, ipsend.SendEvent

Examples

The following example transmits a trigger that displays a message box on the broadcast client's machine.

isend.TriggerScript "alert('You received an Script trigger!')", ""


EnhCab

The EnhCab object, included in IPEnhSnd.dll, provides cabinet file utility methods. Your application can call the methods of EnhCab to create, add files to, and enumerate cabinet files. Because cabinet files are compressed, packaging enhancement files into a cabinet file can result in more efficient transmission.

To locate additional information about cabinet files, see Further Information on Data Services for the Client.

The EnhCab object has the following methods.

Method | Description
AddFile | Adds a file to a cabinet file.
CloseCabinet | Closes a cabinet file and flushes it to disk.
EnumerateCabinet | Enumerates the number of files stored in a cabinet file.
FileName | Returns the filename of the file at the specified index in the cabinet file.
NewCabinet | Creates a new cabinet file.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.


EnhCab.AddFile

The AddFile method adds a file to a cabinet file.

Syntax

object.AddFile( sFile, sCabFileName )

Parts

object
Object expression that resolves to an EnhCab object.
sFile
String that specifies the path and filename of the file to add to the cabinet file.
sCabFileName
String that specifies name of the file as it appears in the cabinet file. This will be the name of the file when it is unpacked from the cabinet file.

Remarks

When you are adding files to a cabinet file, your application should ensure that the total size of files added does not exceed the value of lMediaSize specified when the cabinet was created. If your application needs to add additional files after the size limit is reached, it must create a new cabinet to hold the extra files.

The EnhCab object does not support linked cabinet files. In other words, you cannot store part of a file or folder in one cabinet and the rest in another cabinet.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

EnhCab.NewCabinet, EnhCab.CloseCabinet

Examples

The following example creates a new cabinet file, Cab1.cab, and stores two files in it.

'Create an instance of an EnhCab object
'and store it in the ecab variable
Dim ecab As EnhCab
Set ecab = New EnhCab

'Create the cabinet file
ecab.NewCabinet "Cab1.cab", 2000000, 2000000, 1

'Add files to the cabinet file
ecab.AddFile "C:\File1.htm", "File1.htm"
ecab.AddFile "C:\File2.htm", "File1.htm"

'Close the cabinet file and write it to disk
ecab.CloseCabinet


EnhCab.CloseCabinet

The CloseCabinet method closes the cabinet file, compressing the files stored within the cabinet and saving it to disk.

Syntax

object.CloseCabinet()

Parts

object
Object expression that resolves to an EnhCab object.

Remarks

Your application must call CloseCabinet in order to compress the files in the cabinet and save them to disk.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

EnhCab.NewCabinet, EnhCab.AddFile

Examples

The following example closes a cabinet file, Cab1.cab, after all files have been added to it.

'Add files until the cabinet is full,
'or all files have been added.
ecab.AddFile "C:\File1.htm", "File1.htm"
ecab.AddFile "C:\File2.htm", "File1.htm"
'...

'Close the cabinet file and save it to disk.
ecab.CloseCabinet


EnhCab.EnumerateCabinet

The EnumerateCabinet method counts the number of files stored within a cabinet file.

Syntax

object.EnumerateCabinet( sCab, lNumFiles )

Parts

object
Object expression that resolves to an EnhCab object.
sCab
String that contains the name of the cabinet file to enumerate.
lNumFiles
Long that receives the number of files in the cabinet.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

EnhCab.FileName

Examples

The following example counts the number of files stored in the cabinet file, Cab1.cab.

Dim ecab As EnhCab
Set ecab = New EnhCab

'Create a variable to receive the file count.
Dim numFiles As Long

'Count the number of files in the cabinet and
'store the value in the variable numFiles
ecab.EnumerateCabinet "C:\EnhancementFiles\Cab1.cab", numFiles

'Display a message box that informs the user of the file count
Msgbox "There are currently "+ CStr(numFile) + " files in the cabinet file."


EnhCab.FileName

The Filename method returns the filename of the file at the specified index in the cabinet file.

Syntax

object.Filename( lindex, sFileName )

Parts

object
Object expression that resolves to an EnhCab object.
lindex
Long that specifies the 0-based index of the file within the cabinet file.
sFileName
String that receives the name of the file stored at lindex.

Remarks

You can retrieve the number of files in a cabinet using the EnhCab.EnumerateCabinet method.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

EnhCab.EnumerateCabinet

Examples

The following example writes the filename of each file stored in Cab1.htm to a text file.

'Open the output file.
Open "FilesInCab.txt" for Output As #1

'Declare a variable to receive the filename
Dim fname As String

'Loop through the files stored in the cabinet file.
For (i = 0 to numFiles - 1)

  'Store the filename of the ith file in fname.
  ecab.FileName i, fname

  'Print the filename of the ith file to the output file.
  Write #1 fname

Next i

'Close the output file.
Close #1

Note that the variable numFiles contains a count of the number of files stored within the cabinet. To see an example of how to programmatically obtain a file count, see the Examples section of EnhCab.EnumerateCabinet.


EnhCab.NewCabinet

The NewCabinet method creates a new cabinet file.

Syntax

object.NewCabinet( sCab, lMediaSize, lFolderSize, iSetID )

Parts

object
Object expression that resolves to an EnhCab object.
sCab
String that contains the path and filename for the new cabinet file.
lMediaSize
Long that indicates the size, in bytes, available for the cabinet file on this media.
lFolderSize
Long that specifies the threshold size, in bytes, for creating a new folder. Files stored within a cabinet file are organized into folders. Each folder contains one or more files and is a compression unit. When a folder reaches lFolderSize, the EnhCab object compresses the files stored in that folder and creates a new folder within the cabinet.
iSetID
Integer that contains the cabinet set identifier.

Remarks

Once your application has created a new cabinet file, it can use the EnhCab.AddFile method to store files in the cabinet file.

QuickInfo

Windows NT: Unsupported.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in ipenhsnd.idl.
Import Library: Included as a resource in ipenhsnd.dll.
Unicode: Yes.

See Also

EnhCab.AddFile, EnhCab.CloseCabinet

Examples

The following example creates a new cabinet file, Cab1.cab, and stores two files in it.

'Create an instance of an EnhCab object
'and store it in the ecab variable
Dim ecab As EnhCab
Set ecab = New EnhCab

'Create the cabinet file
ecab.NewCabinet "Cab1.cab", 2000000, 2000000, 1

'Add files to the cabinet file
ecab.AddFile "C:\File1.htm", "File1.htm"
ecab.AddFile "C:\File2.htm", "File2.htm"

'Close the cabinet and write it to disk
ecab.CloseCabinet


Enhancement Registry Entries

The broadcast client uses the following registry entries to store information about enhancements. These values are stored in the registry key:

HKLM/Software/Microsoft/TV Services/Enhanced Content/

Name | Data type | Description
AcceptFullPaths DWORD Indicates whether the Enhancement control resolves the paths of trigger parameters relative to the spool directory.

Normally, the Enhancement control restricts paths to be relative to the spool directory. If AcceptFullPaths does not exist or is set to zero, the Enhancement control resolves the paths relative to the spool directory.

If this value is non-zero, the Enhancement control does not resolve the path. In other words, each path must contain a fully specified path, for example "C:\Program Files\TV Viewer\Temp Enhancement\MyEnhShow.5".

Authoring tools can set this key to enable the Enhancement control to read files from a folder other than the spool folder. This is useful when testing the enhancement stream locally.
Enhanced Content | String | Location of the spool directory on the client. By default, this value is set to C:\Program Files\TV Viewer\Temp Enhanced Content.


Enhancement Stream Language Reference

The reference information of the Enhancement Stream language is divided into the following three sections. For more information, click on the topic that is of interest to you.

Syntax Conventions. This section explains the lexical rules that you must follow to write valid Enhancement Stream language statements.

Reserved Variables. The reserved variables define a number of the characteristics of the show, such as the name, the title, the bandwidth you are broadcasting on, and the IP (Internet Protocol) addresses you will use for the broadcast—to name just a few.

Event Statements. These statements direct the activity of the assets and enhancements. They instruct announcements to be sent, direct files to be broadcast at specific times, and then summon those files to display at the appropriate place on the screen, at the appropriate time.


Syntax Conventions

In the course of writing a stream script, you will need to follow certain lexical conventions. Click on the topic that is of interest to you.

Arithmetic Expressions Syntax

Comments Syntax

Filename, Path, and URL Syntax

Keywords Syntax

String and Escape Sequence Syntax

Time Syntax

Trigger Types

Variables Syntax


Arithmetic Expressions Syntax

The Enhancement Stream language supports the following arithmetic operators. For more information, click on the operator of choice.

+ Operator

- Operator

* Operator

/ Operator

\ Operator

Mod Operator

^ Operator


+ Operator

Used to sum two numbers.

Syntax

result = expression1+expression2

The + operator syntax has these parts:

Part | Description
Result | Required; any numeric variable.
Expression1 | Required; any expression.
Expression2 | Required; any expression.

Remarks

When you use the + operator, you may not be able to determine whether addition or string concatenation will occur.

The following rules apply:

If | Then
Both expressions are numeric | Add.
Both expressions are String | Concatenate.
One expression is a numeric data type and the other is any data type except Null | Add.
One expression is a String and the other is any data type except Null | Concatenate.
One expression is an Empty data type | Return the remaining expression unchanged as result.
One expression is a numeric data type and the other is a String | A Type mismatch error occurs.
Either expression is Null | The result is Null.

Example

MyNumber = 2 + 2 ' Returns 4.
MyNumber = 4257.04 + 98112 ' Returns 102369.04.


- Operator

Used to find the difference between two numbers or to indicate the negative value of a numeric expression.

Syntax 1

result = number1-number2

Syntax 2

-number

The - operator syntax has these parts:

Part | Description
result | Required; any numeric variable.
number | Required; any numeric expression.
number1 | Required; any numeric expression.
number2 | Required; any numeric expression.

Remarks

In Syntax 1, the - operator is the arithmetic subtraction operator used to find the difference between two numbers. In Syntax 2, the - operator is used as the unary negation operator to indicate the negative value of an expression.

Example

MyResult = 4 - 2 ' Returns 2.
MyResult = 459.35 - 334.90 ' Returns 124.45.


* Operator

Used to multiply two numbers.

Syntax

result = number1*number2

The * operator syntax has these parts:

Part | Description
result | Required; any numeric variable.
number1 | Required; any numeric expression.
number2 | Required; any numeric expression.

Example

MyValue = 2 * 2 ' Returns 4.
MyValue = 459.35 * 334.90 ' Returns 153836.315.


/ Operator

Used to divide two numbers and return a floating-point result.

Syntax

result = number1/number2

The / operator syntax has these parts:

Part | Description
result | Required; any numeric variable.
number1 | Required; any numeric expression.
number2 | Required; any numeric expression.

Example

MyValue = 10 / 4 ' Returns 2.5.
MyValue = 10 / 3 ' Returns 3.333333.


\ Operator

Used to divide two numbers and return an integer result.

Syntax

result = number1\number2

The \ operator syntax has these parts:

Part | Description
result | Required; any numeric variable.
number1 | Required; any numeric expression.
number2 | Required; any numeric expression.

Remarks

Any fractional portion is truncated. However, if any expression is Null, result is Null. Any expression that is Empty is treated as 0.

Example

MyValue = 11 \ 4 ' Returns 2.
MyValue = 9 \ 3 ' Returns 3.
MyValue = 100 \ 3 ' Returns 33.


Mod Operator

Used to divide two numbers and return only the remainder.

Syntax

result = number1 Mod number2

The Mod operator syntax has these parts:

Part | Description
result | Required; any numeric variable.
number1 | Required; any numeric expression.
number2 | Required; any numeric expression.

Remarks

The modulus, or remainder, operator divides number1 by number2 (rounding floating-point numbers to integers) and returns only the remainder as result. For example, in the following expression, A (result) equals 5.

A = 19 Mod 6.7

Any fractional portion is truncated. However, if any expression is Null, result is Null. Any expression that is Empty is treated as 0.

Example

MyResult = 10 Mod 5   ' Returns 0.
MyResult = 10 Mod 3   ' Returns 1.
MyResult = 12 Mod 4.3   ' Returns 0.
MyResult = 12.6 Mod 5   ' Returns 3.


^ Operator

Used to raise a number to the power of an exponent.

Syntax

result = number^exponent

The ^ operator syntax has these parts:

Part | Description
result | Required; any numeric variable.
number | Required; any numeric expression.
exponent | Required; any numeric expression.

Remarks

A number can be negative only if the exponent is an integer value. When more than one exponentiation is performed in a single expression, the ^ operator is evaluated as it is encountered from left to right.

If either number or exponent is a Null expression, result is Null.

Example

MyValue = 2 ^ 2 ' Returns 4.
MyValue = 3 ^ 3 ^ 3 ' Returns 19683.
MyValue = (-5) ^ 3 ' Returns -125.


Comments Syntax

To write comments into a stream script, use the comments syntax. The Enhancement Stream language supports comments in the same way as the C++ programming language:

  • using the characters //
  • enclosing the comment text in between the characters /* and */

For a comment that extends through the end of the current line, you would use the characters // to begin the comment. For example:

endshow = 00:29:00:00; // End of show
timeout = endshow; // Files will be deleted at end of show

For a comment that continues for multiple lines, the sequence /* begins the comment and */ ends it.


Filename, Path, and URL Syntax

In general, file names should appear in quotation marks. (The syntax does permit unquoted names, however, provided the names obey the identifier rules for the C programming language and allow periods except as the first character.)

The file name may specify a subdirectory. For example:

00:12:19:00 "Images/Pretty.gif";

Only forward slash (/) is supported. References to higher-level directories are not supported ("../Myfile.htm" is invalid.)


Keywords Syntax

In addition to the basic syntax of event statements, the behavior of many events can be further customized through the use of keywords.

For more information, click on the keyword of choice in the following table:

Before. Indicates that the event in which the keyword appears should be completed before the time indicated.

Now. Indicates that the event in which the keyword appears should take place immediately.

Only. Indicates that any assets or enhancements named in the event in which the keyword appears should be handled alone; their associated dependencies should not also be acted upon by the event.

Repeat. Indicates that the event in which the keyword appears should be repeated at the interval indicated or the number of times specified.


Before

To broadcast an asset before a specified time, use the keyword, before. This keyword indicates that the event in which before appears should be completed before the time indicated. This is especially useful for broadcasting an enhancement and its dependencies to the client, ensuring that the enhancements will be present on the computer before they are triggered to display.

Applies To

All events.

Syntax

before event syntax ;

Example

The keyword before ensures that the asset and its dependencies are broadcast in time to be triggered 46 seconds into the show:

 before  00:00:46.00 trigger (3 "enhance" "fact1.htm");


Now

To broadcast an asset live, use the keyword, now. This keyword indicates that the event in which now appears should take place immediately. You would use this keyword in the course of live broadcasts, or to broadcast an enhancement that has been corrected or updated.

Applies To

All events.

Syntax

now event syntax ;

Example

The following statement causes the file "Scoreboard.htm" to be broadcast immediately:

now "Scoreboard.htm";

Obviously, time expressed in this form cannot be preceded by the keyword before.

A trigger can also be broadcast immediately. For example, the following statement sends the file immediately, and then sends the specified trigger, NavTarget, to display the file in the portion of the viewing area titled "Left:"

now trigger (3 "Left" "Segment7.htm");

To send a trigger only—that is, in the event the file targeted in the trigger has already been downloaded to the viewer's machine—use the keyword only, as in the following example:

now trigger (3 "Left" "Segment7.htm") only;


Only

To prevent dependencies from being broadcast with an asset, use the keyword, only. This keyword indicates that any assets or enhancements named in the event in which only appears should be handled alone; their associated dependencies should not also be acted upon by the event. In the case of a download event, this keyword is useful for managing bandwidth if the asset being broadcast has numerous dependencies.

When used in a trigger event, the keyword only can be used to keep the trigger from downloading again files that have already been downloaded.

Applies To

All events.

Syntax

event syntax only;

Example

In the following example, the file default.htm—without any of its dependencies—is broadcast at the 10:30:00 mark in the show:

00:10:30:00 "default.htm" only;

In the following example, the statement assumes that the file Left_07.htm and its dependencies already exist on the client, and transmits only the trigger itself, Navigate Target, causing the file and its dependencies to display in the frame titled "Left:"

00:10:30:00 trigger ( 3 "Left" "Left_07.htm") only;


Repeat

To repeat an event at a regular interval, use the keyword, repeat. This keyword indicates that the event in which repeat appears should be repeated at the interval indicated or the number of times specified. If a viewer tunes in late to a program, the files necessary to display the enhancements may not be available. For this reason, it is important to repeat the transmission of files as frequently as possible.

Applies To

All events.

Syntax

repeat interval until endtime ;

Examples

In the following example, the statement causes the file "Segment2.htm" to begin transmission thirty seconds into the program and be retransmitted every minute until the end of the show, as defined by the built-in variable ShowLength:

00:00:30:00 "Segment2.htm" repeat 60 until ShowLength;

This construct also works with the before keyword. For example, the following statement transmits "Segment5.htm" and its dependencies by 5:20 in the program, and repeats the transmission of the file and its dependencies once a minute until the end of the program:

before 00:05:20:00 "Segment5.htm" repeat 60 until ShowLength;

The repeat...until construct also works with trigger statements, and may appear in the same statement with or without a timeout override.


String and Escape Sequence Syntax

To write special characters into a stream script, use the string and escape sequence syntax. The Enhancement Stream language supports string concatenation, allowing you to build strings using combinations of string, numeric, and variable values.

Syntax

"TextString" + Variable + "EscapeSequence"

where TextString is an alphanumeric string of text enclosed in quotes, Variable is any value that is defined in a variable declaration, either numeric or text, and EscapeSequence is an escape sequence, enclosed in quotes. These three syntactic elements can be used in any order and combination.

Notes
  • Because escape sequences are treated as character constants, they must be enclosed in quotes, unless they have been defined as a variable. In such a case, you would state the variable name in the event statement, without quotes.
  • If an escape sequence immediately precedes or follows a text string, it is not necessary to state the escape sequence separate from the text string, it is included as part of the text string, sitting within the quotes. For more information, see Escape Sequences.

The ability to build strings is especially helpful if you want to write a stream script that serves as a template for many different scripts, or if you simply want to build greater flexibility into your event statements, such as triggers.

For example, you might be producing a series of interactive shows about the seven wonders of the ancient world, and each show follows a very similar format, where certain enhancements appear at a set pace and in a predetermined frame of TV Viewer or a Web browser. Since you intend to keep the general structure and presentation of the content similar from one show to the next, one of the major differences among episodes will be the content. From a stream script standpoint, this means a difference in the names of the HTML (Hypertext Markup Language) files that are broadcast.

To this end, then, you could instruct your enhancement production staff that the core name for all HTML files for the first episode on the pyramids at Giza should be Giza, such that all the HTML enhancements have a similar name:

Giza000.htm
Giza005.htm
Giza010.htm
Giza015.htm
Giza020.htm
etc.

Then in the stream script, you could identify this core file name value using a variable, such as wonder:

wonder = Giza

From then on, all your event statements could reference that variable, building the string using a combination of the variable and a text string, combining the two elements with a plus (+) sign:

before 00:00:20:20 trigger (3 "Side" wonder + "005.htm");
before 00:00:50:60 trigger (3 "Side" wonder + "010.htm");
before 00:01:18:40 trigger (3 "Side" wonder + "015.htm");

These trigger statements are identical to—and therefore are interpreted the same as—the following event statements:

before 00:00:20:20 trigger (3 "Side" "Giza005.htm");
before 00:00:50:60 trigger (3 "Side" "Giza010.htm");
before 00:01:18:40 trigger (3 "Side" "Giza015.htm");

By using the variable wonder rather than writing out the specific filename for each event, you can change the content of the stream script by simply redefining the variable. For the second show, then, about the Hanging Gardens of Babylon, you could redefine the variable wonder to match the core name of that show's HTML files, namely, Gardens.

wonder = Gardens

Escape Sequences

In the course of building strings, you can represent certain unprintable characters using escape sequences. Escape sequences are character combinations consisting of a backslash (\) followed by a letter or by a combination of digits. When writing statements in a stream script, you must use escape sequences to execute such text entities as tab characters, backspaces, and new lines. The Enhancement Stream language regards an escape sequence as a single character and will therefore consider one valid when used as a character constant.

For instance, you may want the title of the program, which appears in the channel listing in the Program Guide, to look something like this:

"Secrets of the Incas"
Premium Presentation

To define this title for your show, you would, of course, use the reserved variable Title. There are a couple of issues here, however, that you must address to get the title to appear as it does in the example. For one thing, the title uses quotes, and since the syntax for defining Title encloses your title in quotes already, you must use an escape sequence to represent the quotation marks around the text Secrets of the Incas. Moreover, the phrase Premium Presentation, which perhaps represents the level of enhancements the show will broadcast and, therefore, the cost of subscribing to the show, appears on its own line. So you would need an escape sequence to represent the new line.

The title in the stream script would end up looking like this:

Title="\x22Secrets of the Incas\x22\nPremium Presentation"

Escape sequences are used to provide literal representations of nonprinting characters and characters that would be difficult to edit and display in their raw form.

The Stream Compiler supports the following escape sequences:

Escape Sequence | Represents
\b | Backspace
\f | Formfeed
\n | New line
\r | Carriage return
\t | Horizontal tab
\xhh | ASCII character in hexadecimal notation, where hh is the hexadecimal value. For example, the registered trademark sign ® whose ASCII code is 0174, has a hexadecimal value of AE. The hexadecimal escape sequence for the registered trademark symbol would be /xAE .


Time Syntax

To specify time in event statements, you can follow several different formats, including seconds (and decimal fractions thereof), SMPTE (Society of Motion Picture and Television Engineers) time, and calculated expressions.

The following statements all produce the same results:

00:01:20:00 segment2.htm;

80 segment2.htm;

80.0 segment2.htm;

actI = 00:01:00:00;
actI + 20 segment2.htm;

Each of these statements causes the file Segment2.htm to begin transmission at one minute and twenty seconds into the program. The first version uses absolute SMPTE time. The second and third versions use seconds. In the fourth example, the first statement defines a constant called actI, which specifies the beginning of Act I in the show. Then the next line of code uses the addition operator + to add a 20-second offset to this time.

SMPTE Time

The Stream Compiler recognizes time expressed in SMPTE format. SMPTE time is a standard representation of time developed for the video and film industries.

SMPTE time is an absolute time format expressed in hours, minutes, seconds, and frames. Standard SMPTE division types are 24, 25, and 30 frames per second (FPS). Valid SMPTE time codes are 00:00:00:00 through 23:59:59:29 for the NTSC (National Television Standards Committee) non-drop frame standard, which has a frame rate of 29.97 frames per second.

The Stream Compiler supports three forms of SMPTE time:

SMPTE time format | Format | Example
30 frames per second | hh:mm:ss:ff | 01:00:30:15
drop frame (29.97 frames per second) | hh:mm:ss;ff | 01:00:30;15
fractional seconds | hh:mm:ss.dd | 01:00:30.5

The distinction is made by the punctuation character following the seconds. A colon indicates that the last pair of digits represent a frame (from 0 to 29), where frames are displayed at the rate of 30 per second. A semicolon indicates that the last pair of digits represent a frame (from 0 to 29), in drop-frame format. A period indicates that the final two digits represent a decimal fraction of a second (for example, .5 = 15 frames, or about half a second).

All representations of time that are expressed in hours, minutes and seconds (as opposed to seconds only) require the use of a colon separator, and must include digit(s) for the frame. "00:1" indicates one frame.

The Stream Compiler also accepts time expressed in whole or decimal seconds, which is not valid SMPTE. For example, both 342.0 and 342 mean exactly 00:05:42:00.

The built-in variable FPS enables you to set the frame rate.

Specifying Absolute Time

To express an absolute time in the form of "time-from-now," type the "+" symbol before the time expression. For example, both of the following expressions refer to the point in time one minute from now:

+60
+00:01:00:00


Trigger Syntax

In the Enhancement Stream language, a trigger is expressed in either of the following ways:

trigger ( integer "string-argument1" [ "string-argument2" ] )
or
trigger integer "arguments"

In the first form of the statement, the arguments to trigger are contained within parentheses. The first argument is the trigger-type integer, and the remaining arguments are quoted strings representing additional arguments. The number and meaning of these arguments depend on the trigger type, for example:

before 00:10:30.00 trigger (3 "Left" "Left_07.htm");

In the second statement, arguments is a single string which may contain non-printable characters in the form of escape sequences. The tab character is used to separate the fields required by that type of trigger. For example, the above statement could also be written as

before 00:10:30.00 trigger 3 "Leftt\Left_07.htm";

The character combination "\t" is an escape sequence which represents the tab character.


Variables Syntax

In the Enhancement Stream language, there are two kinds of variables: reserved and user-defined variables.

For more information, click on the topic of choice.

Reserved Variables

User-Defined Variables


Reserved Variables

Reserved variables define the general broadcast characteristics of your interactive show.

For more information, click on the reserved variable of choice.

Bandwidth Bandwidth in bps (bits per second) that is available for the enhancements and events.

FPS Frames per second.

FrameName The names of the interactive show's frames, as defined by the frameset tag residing in the show's main HTML (Hypertext Markup Language) page.

HRef Used to specify that you want HREFs (hypertext references) within an asset to be downloaded as dependencies of that asset.

LeadTime Number of seconds between complete transmission of a file and a trigger that depends upon it.

Overhead A fixed number of bytes you want reserved from your bandwidth for downloading files.

Redundancy Allows for the correcting of errors that might occur in the course of a file transferring to the viewer's computer using the FTS (File Transfer Service) protocol.

ShowLength The length of the interactive show in hours, minutes, and frames.

ShowName Used to name the directory on the viewer's computer where an interactive show is broadcast.

Timeout Default time after which any files downloaded will be deleted from the viewer's computer.

Title Used to distinguish one version of an interactive show from another version, as distinguished by say, language, or level of enhancements.


Bandwidth

To set the bandwidth of an interactive show, use the reserved variable, Bandwidth.

Bandwidth value affects such things as the speed of file downloads and, consequently, the length of time needed to perform the download. For example, if you have your bandwidth set for 100,000 bps (bits per second) and change it to 9600 bps, a file and its dependencies that must be downloaded by the 2:00 minute mark in the show will need to begin downloading sooner than under the higher bandwidth setting.

These changes in calculations are handled by the Stream Compiler (stream.dll) when it compiles your stream script from the high-level format to the low-level format. This low-level format, which is suitable for broadcast, contains all the proper download calculations based upon your bandwidth and lead time settings and the size of the files and their dependencies.

If the Stream Compiler determines, after compiling your stream script, that your interactive show cannot be broadcast within the specified time and the bandwidth, it will notify you with an error message. In such a case, you can choose one or more of the following three options:

  • Begin the show earlier, during which file downloads take place transparently to the viewer.
  • Edit out/trim down some of your enhancements.
  • Increase your bandwidth, which would mean you would need to change the transmission carrier method that you use to broadcast the show.

Applicable Signal Carriers

The most common signal carriers are as follows, although the Enhancement Stream language will recognize any bps value that you specify:

BPS Rate | Script Notation
2400 | Bandwidth = 2400.000000;
9600 | Bandwidth = 9600.000000;
19200 | Bandwidth = 19200.000000;
28800 | Bandwidth = 28800.000000;

Syntax

Bandwidth = bps ;

where bps is an integer representing bits per second.


FPS

To set the rate of frames per second for an interactive show, use the reserved variable, FPS.

Syntax

FPS = x ;

Where x is an integer denoting the rate of frames per second that the interactive show runs at, which most commonly will be one of these four values:

Value | Description
24 | Used for many film-based systems, most notably as the feature film frame rate.
25 | Used in most European and many Middle East and Asian countries for broadcast systems. It is also commonly used in non-broadcast applications in the same regions.
29.97 | Used to describe the frame rate used in NTSC television systems and is the rate normally known as "30 drop frame."
30 | Used as the video frame rate in many countries, including the United States, for monochrome television broadcasting. It is still used as a time code rate by some recording studios as they believe the increased scanning rate of automated studio equipment may give an enhanced performance.

Example

FPS = 29.97;


FrameName

To specify the names of frames for an interactive show, use the reserved variable, FrameName.

If your interactive show makes use of frames, you will want to set up your stream script such that it recognizes the frames of the show.

Syntax

FrameName(x) = "name" ;

where x is an integer, the value for the first frame being 0 (zero), and where name is the name of the frame as defined within the Frameset tags, in the HTML (Hypertext Markup Language) file where the frames are defined.

Note The name must be enclosed in quotes.

Example

In this example, three frames are defined:

FrameName(0) = "Side";
FrameName(1) = "Main";
FrameName(2) = "MenuBar";

These frame names would need to correspond to the name parameters of the Frameset tag, which resides in the HTML file where the frames are defined. For example, the Frameset tag in the HTML file might look something like this.

<frameset cols="100%" rows="*,100">
     <frameset cols="250,*">
          <frame name="Side" src="quiz01.htm" scrolling="auto" marginwidth=0>
          <frame name="Main" src="video.htm" scrolling="auto">
     </frameset>
     <frame name="MenuBar" src="menu01.htm" scrolling="auto">
</frameset>


HRef

To specify that you want hypertext references (HREFs) within an asset to be downloaded as dependencies of that asset, use the reserved variable, HRef.

This setting applies to the downloading of those HTML (Hypertext Markup Language) files that have jumps to other HTML files (in which case the jump, defined using the HTML tag <A>, makes use of the parameter HREF to define the destination of the jump). In the course of an interactive show, when an HTML file is downloaded ahead of time, its dependencies (files that appear within it, such as animations and graphics) are also downloaded. But HREF—that parameter in an HTML jump that specifies the destination of the jump—is a different matter.

To make this more clear, it might help to look at an example of HTML code that uses an HREF parameter. In the following HTML code, the anchor tag that makes the text "Restless savannah nights" clickable, includes the HREF parameter, which defines the destination of the jump, namely, nocturnal.htm.

For more information about the nocturnal habits of lions, see <A HREF="nocturnal.htm">Restless savannah nights</A>.

Technically, the destination file nocturnal.htm is not a dependency of the HTML file it appears in, but you can choose to have it treated as such using in your stream script the reserved variable HRef. If you exclude the HRef reserved variable altogether, thereby choosing not to have HREFs downloaded as dependencies, they will be downloaded when the trigger fires to display the parent HTML file that the they appear in.

Syntax

HRef = parameter ;

where parameter can be one of the following two options:

After When an HTML file is downloaded, any HTML files referenced in jumps within that "parent" file are downloaded immediately after the parent is downloaded.

Before When an HTML file is downloaded, any HTML files referenced in jumps within that "parent" file are downloaded immediately before the parent is downloaded.

To not have HREF destination files downloaded as dependencies of a parent HTML file, simply do not include the HRef reserved variable in your stream script.

Example

HRef = after;


LeadTime

To specify lead time for an interactive show, use the reserved variable, LeadTime.

The reserved variable LeadTime ensures that files downloaded to a viewer's computer finish downloading before they are triggered to appear in TV Viewer or a browser. The value you place in this variable indicates the number of seconds that you want as a buffer between the finish of a file download to the viewer's computer and the activating of that file in the show.

Syntax

LeadTime = x ;

where x is an integer representing seconds.

Example

The following illustrates a lead time of five seconds:

LeadTime = 00:00:05.00;


Overhead

To set the overhead of an interactive show, use the reserved variable, Overhead.

In the context of the Enhancement Stream language, Overhead refers to a fixed number of bytes you want reserved from your bandwidth for downloading files.

Syntax

Overhead = x ;

where x is an integer that represents the number of bytes that you want reserved for file transfer overhead.

Example

In the following example, 2560 bytes are reserved for file transfer overhead:

Overhead = 2560.000000;


Redundancy

To set the rate of redundancy for file transfers over the course of an interactive show, use the reserved variable, Redundancy. The purpose of redundancy is to allow for the correcting of errors that might occur in the course of a file transferring to the viewer's computer.

The value of Redundancy is the reciprocal of the amount of extra bandwidth used for forward error correction. For example, if you set the redundancy to 10, the amount of bandwidth allotted to forward error correction is 1/10, or 10 percent. In other words, an additional number of bytes, equal to 10 percent of the original file, will be transmitted for error correction.

Syntax

Redundancy = x ;

Where x is the reciprocal of the amount of extra bandwidth used for forward error correction. The following table provides some values that you can insert in the Redundancy reserved variable, based on percentages of the file's total byte size.

Percent | Value of Redundancy
1% | 100
2% | 50
5% | 20
7% | 14.3
10% | 10
15% | 6.66
20% | 5
25% | 4
33% | 3.33
40% | 2.5
45% | 2.22
50% | 2

Example

In the following example, the redundancy is set to 20, meaning that an additional number of bytes, 1/20th (or 5 percent) of the original file, will be transmitted for error correction:

Redundancy = 20;


ShowLength

To specify the length of an interactive show, use the reserved variable, ShowLength.

Syntax

ShowLength = hh:mm:ff ;

where hh is an integer denoting hours, mm is an integer denoting minutes, and ff is an integer denoting frames.

Example

In the following example, the show is 30 minutes long:

ShowLength = 00:30:00.00;


ShowName

To specify the name of an interactive show, use the reserved variable, ShowName. The value for this setting names the directory of your interactive show when it is broadcast to the viewer's computer. All interactive shows are deposited into their own directory within the Spool directory. For example, if the name of the show was The Vanishing Serengeti, the directory that the show would be broadcast to would be C:\Windows\Spool\The Vanishing Serengeti.

Syntax

ShowName = "text" ;

where text is the name you want for the interactive show.

Note The text of the show name must be enclosed in quotes.

Example

ShowName = "The Vanishing Serengeti";


Timeout

To specify how long the files of an interactive show remain on a viewer's computer, use the reserved variable, Timeout.

Files created for an interactive show are generally needed only for the duration of a specific program. To prevent these files from accumulating over time and quickly filling the viewer's hard disk, a garbage collector removes files when their timeout value has been exceeded.

The timeout value is an absolute time relative to the beginning of a program (0 seconds or 00:00:00.0 in SMPTE time code).

By default, all files transmitted by the Stream Compiler are given a default timeout value which can be set by the built-in variable Timeout.

Syntax

Timeout = hh:mm:ff ;

where hh is an integer denoting hours, mm is an integer denoting minutes, and ff is an integer denoting frames.

Examples

The Timeout value you set is active upon only those files that come after the occurrence of the Timeout line of text. For example,

00:01:56.40 "storm010.htm" ;
Timeout = 00:31:00.0;
00:02:10.20 "storm020.htm" ;
00:03:06.60 "storm030.htm" ;

At 31 minutes into the show, files storm020.htm and storm030.htm will be deleted from the viewer's hard drive, but not storm010.htm, since it appears before the occurrence of Timeout. This is useful if there are certain files you want to leave on the viewer's computer after the show is over.

Conversely, if Timeout appears as one of the first statements in the list, then all subsequent transmitted files are assigned a timeout value causing them to expire 31 minutes after the show begins. In most cases, it is sufficient to specify a global timeout in this way.

The default value of Timeout can be changed to a different value at any point in the list of statements. Statements specified subsequent to the change in the value of Timeout will transmit files with the new timeout value.

Timeout can also be overridden for individual files, without changing the default timeout value, by appending the following phrase to a statement that causes the file to be transmitted:

Timeout = time ;

where time is an expression of time relative to the start of the program. For example, the following statement causes the file Test4.htm and all its dependencies to be completely transmitted by 1:20 (relative to start of program), and to be deleted after the tenth minute of the program, instead of at the default timeout time:

before 00:01:20.00 "Test4.htm" timeout 00:10:00.0;

The Timeout override applies to all files and their dependencies listed in the statement.


Title

To specify the title of an interactive show, use the reserved variable, Title.

In the event that you have created multiple enhancement streams that the viewer can choose from, the title gives you a means of distinguishing one enhancement stream from another.

You might choose to design a single interactive show to be produced in a number of different versions. These versions might be based on language, where you have produced the same show in English and Spanish. Or you might provide varying levels of enhancements and advertise three levels of the same show: basic, advanced, and premium. All of these would be variations of the same show, which you have scheduled to broadcast at 8:00pm, July 22nd. Which version the viewer sees is up to the viewer.

Each version of the show would have its own stream script. What would make one stream script different from another would be the IP (Internet Protocol) addresses and assets it uses, and perhaps the events that it fires. You further distinguish one stream script from another by using the Title parameter.

The title you set for the stream script should correspond to the title set in the announcement, for when a viewer receives an announcement and subscribes to your show, the show title that the viewer will see in the Microsoft® Windows® Program Guide will be the title included with the announcement. The Announcement parameter for a show's title is

s = showtitle

Syntax

Title = "text" ;

where text is the name you want to appear for the title.

Note The value of text must be enclosed in quotation marks.

Example

Title = "The Vanishing Serengeti - Premium";


Event Statements

The Enhancement Stream language supports three different kinds of event statements. For more information, click on the event type of interest.

Announcements. Inform a viewer's computer of either an upcoming interactive show or an interactive show that is currently being broadcast.

Data Downloads Events that broadcast files to the viewer's computer for later use.

Triggers Events that manipulate the components of an interactive show once they have been downloaded to the viewer's computer.


Announcement Events

The broadcasting of an interactive show begins with an announcement, a declaration of information that is essential to displaying the show and getting it underway. Similarly, as is the case in the course of watching standard television, viewers might tune in to your interactive show after it has already begun, or might switch away for a few minutes and then come back to your show. A current enhancement announcement event gets the show going and, in the event the viewer joins the show in progress, allows the viewer's computer to receive and display whatever files currently comprise the show.

All the data necessary for beginning a show or catching up in midstream is contained in the enhancement announcement file that you have generated for the show. This enhancement announcement file is a simple text file that provides a viewer's computer with detailed information regarding an interactive show such as, among other things, the enhancement identifier, the show that it enhances, relevant IP (Internet Protocol) addresses, and the starting page.

By inserting a current enhancement announcement event into your stream script that points to this announcement file, and by repeating this announcement event as often as your bandwidth will allow, you ensure that viewers can switch to your show and watch it even though it is already in progress.

Syntax

timestamp announce "filename" repeat hh:mm:ss.ff until hh:mm:ss.ff ;

where timestamp is the point in the show when or before when the announcement is to take place, filename is the enhancement announcement file that contains the relevant announcement data of the interactive show, and where hh are hours, mm minutes, ss seconds, and ff frames.

Example

In this example, the enhancement announcement file show042.ann is broadcast prior to the first half second of the show, and at the half second mark is then executed. Furthermore, the process of downloading and executing of this file is repeated once every minute until the end of the show:

before 00:00:00.50 announce "show042.ann" repeat 00:01:00.00 until 00:30:00.00 ;

Remarks

Current announcements expire immediately; in other words, their expiration date is the same as their transmission date. This ensures the Announcement Listener rereceives each broadcast of the current enhancement announcement. Otherwise, the default behavior of the Announcement Listener is to ignore duplicate announcements.


Data Downloads

A data download is an event in which the stream script sends instructions to have whatever file or files you specify broadcast to the viewer's computer. Once there, the files can be triggered to display, or be used for whatever purposes they were designed for.

Syntax

keyword1 timestamp datafile keyword2 ;

where

keyword1
is an optional parameter, such as now or before. For more information, see Keywords Syntax.
timestamp
is an optional parameter indicating, in an acceptable time format, the point in the show when the event will take place. For more information, see Time Syntax.
datafile
is the name of the file.
keyword2
is an optional parameter, such as only, or repeat x until y. For more information, see Keywords Syntax.

Examples

A data download event statement can be combined with keywords and other Enhancement Stream language conventions to give greater detail to how you want the download to behave. For instance, to have a data file download before a certain point in the interactive show, you would use the keyword before.

before 00:04:32.60 Rhineland.htm ;

Furthermore, you can have a file download repeatedly over the course of the show. This is useful in the case of a live broadcast where certain information is periodically updated. In this example, the file tally.htm is rebroadcast every 2 minutes until the end of the show.

before 00:03:48.10 tally.htm repeat 00:02:00:00 until 00:30:00:00;


Trigger Types

To write trigger events, use the syntax appropriate for the trigger you want to write. There are two categories of triggers: reserved triggers, which are built into Microsoft Broadcast Architecture, and user triggers, which the enhancements producer can create in the event that the reserved triggers are not adequate to support enhancements created for the interactive show.

A trigger is an event statement in the stream script describing an event scheduled to take place in a HTML (Hypertext Markup Language) page—known in the stream script as an asset—at a certain point in time in an interactive show. Triggers are executed by the Enhancement control, which carries out the instructions of the triggers.

Each type of trigger sent to the Enhancement control has a specific format associated with it. The basic trigger format is a string that contains two parts, a key or numerical identifier, and the trigger data. The key is separated from the data by white space, typically a space or tab character. Optionally, a trigger string can also have keywords at the beginning and end of the string, and can also have a timestamp located prior to the trigger and Key parameters. Like other parameters in a trigger string, these are delimited from other parameters with white space.

The syntax of a trigger is as follows:

keyword1 timestamp trigger (Key "TriggerData") keyword2 ;

where

keyword1
is an optional parameter, such as now or before. For more information, see Keywords Syntax.
timestamp
is an optional parameter indicating, in an acceptable time format, the point in the show when the event will take place. For more information, see Time Syntax.
Key
is the trigger identifier number that specifies what kind of a trigger it is.
TriggerData
is information describing the file or other show element that the trigger is acting upon.
keyword2
is an optional parameter, such as only, or repeat x until y. For more information, see Keywords Syntax.

For example, the following string might be specified in a NavBase trigger:

 00:00:46.00	trigger (2 "http://www.microsoft.com/default.htm") repeat 00:01:00.00 until 00:30:00.00 ;

List of Triggers

The Enhancement Stream language, along with the Microsoft Enhancement Author and the enhanced video controls, supports several types of triggers for different purposes. With the exception of user triggers, all the triggers in the following list are reserved triggers. The number that precedes the trigger name is the numeric reference for that trigger, and is the designation you use in a stream script when you write a trigger statement.

1 Data. Receives data using the transfer protocol you specify, either compressed cabinet (CAB) or File Transfer Services (FTS).

2 Nav. Displays the specified page either in the top-level viewing area or in a specific target portion of the viewing area, as defined by the following tags: <FRAME>, <IFRAME>, <SPAN>, <DIV>.

4 Script. Executes a script that is embedded in the base page of the interactive show.

5 TVCrossover. Runs the specified Microsoft JScript script.

6 - 999. Reserved. Key values reserved for future trigger functionality.

1000 and up User-Defined triggers. Execute user-defined trigger events.


Data

To transmit data to a viewer's receiver using File Transfer Services (FTS), or to unpack a compressed cabinet (CAB) file, use the trigger Data.

The Data trigger serves one of the two following purposes:

  • When a compressed cabinet (CAB) file is specified, the Enhancement control unpacks the specified CAB file. This trigger is sent following the transmission of a CAB file using a Data Download event. For more information, see Data Downloads.
  • When FTS is specified, the Data trigger causes the client to tune to a specified IP (Internet Protocol) address and port to receive FTS data. The enhancement files and their dependencies are transmitted using FTS. A component of Microsoft® NetShow™ server, FTS can send files using a multicast transfer mechanism that includes forward error correction. NetShow is a component of Microsoft® Site Server. All files transmitted on the specified IP address and port are placed into the show's temporary folder, which resides within the Spool folder.

Syntax

trigger (1 "[<protocol>] ConnectionInformation") ;

Where

1
is the key denoting that the trigger is Data.
protocol
is an optional parameter that specifies the data transfer protocol. The default is FTS. The following lists the currently-defined protocols:

FTS. Downloads a file using Microsoft File Transfer Service.
CAB. Unpacks the specified cabinet file.

ConnectionInformation
Specifies the nature of the connection, depending on the protocol used.

If the protocol is CAB, ConnectionInformation is a Broadcast Architecture URL (Uniform Resource Locator) that specifies the cabinet file to unpack. For example: bpc://msnbc/myshow/cabfile.cab .

If the protocol is FTS, ConnectionInformation is a string that contains the IP address and port that the FTS data will be transmitted on. This address and port must be in the following format:

xxx.xxx.xxx.xxx:yyyy dirname [ timeout]

where

xxx.xxx.xxx.xxx
is the IP address.
yyyy
specifies the port.
dirname
specifies the directory name in which the transmitted files should be saved. Note that this value cannot contain subdirectories. For example, "msnbc" is a valid value for dirname, but "msnbc\MyShow" is not.
To store a transmitted file in a subdirectory of dirname, specify the subdirectory when the file is transmitted.
timeout
is an optional parameter that specifies a timeout interval, in minutes. After Timeout minutes have elapsed, the subdirectory is deleted. The default value is 120 minutes.

Remarks

If the protocol of the Data trigger is FTS, the base page of the interactive show must contain the enhancement control EnhCtrl. The control is defined as an HTML (Hypertext Markup Language) object and looks like this:

<!-- Here is the EnhCtrl control -->
<OBJECT CLASSID="clsid:3A263EF8-D768-11D0-911C-00A0C91F37E3"
WIDTH=0 HEIGHT=0 ID=EnhCtrl>
</OBJECT>

The control's presence in the enhancement creates a running instance of EnhCtrl so that it can direct the FTS data that the broadcast is sending, based upon the IP address and port defined in the trigger. If you already have created an instance of EnhCtrl in one of your enhancements, you should not create a second one.

Examples

The following trigger causes the enhancement control to unpack the cabinet file located at: "C:\Program Files\TV Viewer\Interactive Content\<random>\Msnbc\MyShow\MyFile.cab"

00:10:26:00 trigger (1 "<CAB> bpc://msnbc/myshow/myfile.cab") ;

In this example using the FTS protocol, the event dictates that prior to the 1 minute and 27 second mark in the interactive show, the enhancement control will receive a file at IP address 233.43.170.18, port 1718:

before 00:01:27.00 trigger (1 "<FTS> 233.43.170.18:1718 MyShow") ;


Nav

To display a page in either the base page or a specific target of the interactive show, use the trigger Nav.

The Nav trigger serves one of the two following purposes:

  • Navigates the highest-level window of the browser to the specified URL (Uniform Resource Locator). (This produces the same result as setting TARGET="_top" in an HREF link.) In such a case, this trigger can be used to reset the entire interactive show. However, it is not normally needed, because the Program Guide contains the base URL for each show, and updates the container automatically when the viewer changes channels or when a new show begins on the same channel.
  • Causes the file specified by a URL to be loaded into the screen area specified by target. The screen area that is targeted is defined in the HTML (Hypertext Markup Language) base page using any of the following tags: <FRAME>, <IFRAME>, <SPAN>, <DIV>. Using this type of trigger, it is possible to sequence complex interactive content without any scripting.

By default, this trigger type causes both the enhancement and its dependencies to display on the consumer's receiver, such as a WebTV® Plus set-top box or a broadcast-enabled computer. If the enhancement and dependencies of the trigger have not yet been broadcast to the viewer's receiver prior to the trigger firing, they are broadcast when the trigger fires and are then displayed in the specified frame.

Syntax

trigger (2 "<URL> [targ:target]") ;

Where

2
is the key denoting that the trigger is Nav.
URL
is a string indicating the location of the HTML page that is to be displayed. This location can be either a fully specified URL, or a URL relative to the spool directory, C:\Program Files\TV Viewer\Enhspool\.
target
is an optional parameter indicating the name of the screen area that the enhancement will appear in. When this parameter is absent, the event will display the specified URL in the highest-level window of the browser.

Remarks

Broadcast Architecture also supports the following alternative formats for Nav triggers:

trigger (3 "target URL") ;

Where all parameters are the same as described preceding, but the key value is three. This format has been kept for compatibility with earlier versions of Broadcast Architecture.

trigger (2 "[target] URL") ;

Where all parameters are the same as described preceding. This is the ASF (Advanced Streaming Format) format used by NetShow.

Examples

In this example, the main HTML page of the interactive show, default.htm, has already been downloaded and is resident in the show's folder, Tales of the Thames\. This trigger is set to fire every 60 seconds until the end of the show.

00:05:32.20 trigger (2 "<Tales of the Thames\default.htm>") repeat 00:01:00.00 until 00:30:00.00 ;

The following statement causes the file "Left_07.htm" and its dependencies to be broadcast by 10:30, and then triggered at 10:30 to appear in the screen area labeled "Left":

trigger (2 "<Left_07.htm> [targ:Left]");

Assuming the HTML file Left_07.htm has only one dependency—one that makes reference to the dependency file banner.gif—the following three statements collectively are equal to the single statement above (provided the necessary bandwidth is available):

00:10:19:00 "banner.gif";
00:10:26:00 "Left_07.htm";
00:10:30:00 trigger (2 "<Left_07.htm> [targ:Left]") only;


Script

To execute a script residing in an asset, use the reserved trigger, Script.

A Script trigger runs the specified JScript statements on the broadcast client. They are formatted as shown:

trigger (4 "<protocol> script") ;

Where

4
is the key denoting that the trigger is Script.
protocol
is an optional parameter which specifies the scripting language to use. The default is Microsoft JScript. No other scripting languages are supported in the current version of Broadcast Architecture.
script
specifies the script to run on the client.

Remarks

When the Enhancement control receives a Script trigger, it runs the specified script as if it were embedded in the enhancement page. Using this trigger, you can greatly expand the functionality of the enhancement.

Examples

The following is an example of an Script trigger that prints an alert box to the user.

00:05:32.20	trigger (4 "<JScript> alert(\'You received a Script trigger!\')") ;


TVCrossover

To activate a TV Crossover Link, use the reserved variable, TVCrossover.

TVCrossover triggers contain URL (Uniform Resource Locator) information. They are formatted as shown.

trigger (5 "<URL>[[attr1:val1][attr2:val2] ... [attrN:valN]]") ;

Where

5
is the key denoting that the trigger is TVCrossover.
URL
specifies a Uniform Resource Locator.
attrN
specifies the name of the Nth attribute. A TVCrossover trigger can contain zero or more attribute:value pairs.

This parameter is optional. The default value is "type".

valN
specifies the value of the Nth attribute.

Remarks

When the broadcast client receives a TVCrossover trigger, it fires a TVCrossover event, which can then be handled by scripts embedded in the enhancement page.

Examples

The following are examples of TVCrossover triggers. Note that the attributes that have the form [xxx] use the default name "type" and are equivalent to [type:xxx].

trigger (5 "<http://www.newmfr.com>[name:New]") ;
trigger (5 "<http://www.stdnetwork.com>[network]") ;
trigger (5 "<http://www.tvprogram.com>[program]") ;
trigger (5 "<http://advsponsor.net>[sponsor][name:Advertising Sponsor]") ;


User-Defined Triggers

To trigger an event that is not covered by the reserved triggers of the Enhancement Stream language, you create and broadcast a User-Defined Trigger.

User-defined triggers open up essentially unlimited possibilities for control over your interactive show. Because user triggers can invoke subroutines that you create in Microsoft Visual Basic Scripting Edition (VBScript) or JScript, you can perform any type of action, including client-side decision branches and dynamic generation of HTML (Hypertext Markup Language), based on receipt of a particular trigger message.

User-defined triggers may be numbered from 1000 to 2,147,483,647. They can be used for any purpose desired by the enhancements producer. A user-defined trigger command requires the keyword trigger followed by the integer key and the string.

trigger (lKeyID "Data") ;

Where

lKeyID
specifies the trigger identifier, whose value is defined by the content provider. This must be a integer greater than or equal to 1,000 and less than or equal to 2,147,483,647.
Data
specifies the trigger information. The trigger information data is parsed and used by the event handler that processes the user trigger. The format of the trigger information is defined by the broadcaster.

Remarks

When the broadcast client receives a User-Defined trigger, the Enhancement control fires a UserTrigger event, which can then be handled by scripts embedded in the enhancement page.

Examples

The following examples illustrate how you could use User-Defined triggers to transmit quiz show questions and answers. The user-defined trigger data can then be parsed and used by scripts on the enhancement page.

trigger (3001 "Q:What is the capital of Florida?_A:Tallahassee") ;
trigger (3001 "Q:Tomatoes are which kind of plant?_A:Fruit") ;

The following examples use a different User-Defined trigger syntax to pass the time of day to the enhancement page. This could be used, for example, to change the background image of an enhancement to reflect the current time.

trigger (2049 "Twilight") ;
trigger (2049 "Morning") ;
trigger (2049 "Afternoon") ;


Internet Channel Client

Internet channel broadcasting is an architecture that enables World Wide Web sites to be collected, packaged, and then broadcast to multiple subscribers simultaneously.

Currently, the Web operates on a one-to-one basis. Each user who wants to view a site must create a separate connection to that site. If too many users try to access a site at the same time, the server is unable to handle all of the requests. In contrast, Internet channel broadcasting operates on a one-to-many basis. Web sites are broadcast to many users at once and stored in each user's cache until the user is ready to view them.

The Microsoft® Internet Channel Client is a component of the Microsoft® Windows® 98 operating system. This client receives broadcast updates of Web sites that the user has subscribed to and stores the updated files in the Web browser cache. The client extends the Microsoft® Internet Explorer subscription model to a one-to-many broadcast architecture.


Broadcast Server Architecture

The following sections provide an overview of the type of server architecture used to transmit broadcast data over a broadband network to broadcast clients in the home. The head end in this discussion is the physical infrastructure that gathers, coordinates, and broadcasts data over such a network.

The head-end server architecture relies on the following three software components to deliver broadcast data to transport mediums such as cable systems, satellite uplinks, or terrestrial antennas:

  • Content server application . This application, written by a content provider and running on a computer at the head end, gathers, schedules, and sends data to the Microsoft® Multicast Router (MMR), as described in Writing Content Server Applications.
  • Microsoft Multicast Router (MMR). This program routes data from the content server application to the virtual interface (VIF). The MMR can forward Internet Protocol (IP) multicast packets directly to the virtual interface, or it can forward packets embedded in a Transmission Control Protocol (TCP) stream from the content server application.
  • Output system software. This software is a dynamic-link library (DLL) file that the MMR calls to send data to the transport medium. Each transport medium requires a unique virtual interface DLL. A single MMR program can use more that one virtual interface DLL to enable it to send data on multiple transport media.


Content Server Application

A content server application generates a data stream that is sent to the broadcast client. An example of a content server application is the Microsoft® Internet Channel Server, which sends World Wide Web pages. This application collects Hypertext Markup Language (HTML) pages from the Web, using a mechanism based on Internet Explorer version 4.0 channels. Then, the server encapsulates the pages in Transmission Control Protocol/Internet Protocol (TCP/IP) packets and passes them to the MMR.

There are many factors to consider when developing a content server application. Such factors include the amount of data to send, how often the data should be resent, and the security the data requires. For information on how these and other factors affect the design of a content server application, see Writing Content Server Applications.


Microsoft Multicast Router

The Microsoft® Multicast Router (MMR) receives data from the content server application and routes it to the virtual interface. The MMR program is divided into two parts that are covered in the following sections.

  • The Router Service Program is a server process that handles network packets.
  • The Router Manager is a program that you use to control the router service program.

For more information about using the MMR, see Working with the Microsoft Multicast Router.


The Router Service Program

The router service program (Mrouter.exe) is the program that listens for packets coming from the content server application and forwards broadcast data to the virtual interface.

There are two possible ways for a content server application to send data to the MMR. The first is by sending IP multicast packets using an IP address on which the MMR expects data. The MMR passes these packets directly to the virtual interface for transmission. The content server is responsible for sending data at times and speeds that are acceptable to the transmission medium. For example, if the virtual interface is designed to send data to a vertical blanking interval (VBI) data inserter, the content server application must send the data at a rate slow enough for the VBI data inserter to keep up. In addition, if there is another content server application using the same virtual interface, both content server applications must be designed so that they do not send data at the same time.

The second way for a content server to send data to the MMR is through a TCP/IP tunnel. A TCP/IP tunnel is a TCP/IP connection between two applications that is used to carry other network data. In the case of the MMR, this data is UDP packets destined for the virtual interface. The advantage of using a TCP/IP tunnel is that it gives the MMR an opportunity to send messages back to the content server application. These messages tell the content server application when it is sending too much data or sending data at the wrong time.


The Router Manager

The router manager (Mmradm.exe) is a program that lets you monitor the status and set parameters for the router service program. Mmradm.exe does not have to run on the same computer as the router service program. The only requirement is that a network connection exists between Mmradm.exe and the system running Mrouter.exe.


Output System Software

The virtual interface is a dynamic-link library (DLL) file that contains routines that the MMR can call to send packets to the broadcast hardware. The MMR keeps a list of which packets go to which virtual interface. For example, you can use Mmradm.exe to setup the MMR to send all packets arriving through a certain tunnel to the VBI virtual interface. The virtual interface copies the packets to the VBI device and signals the MMR when it can accept more data. To read about how to write a virtual interface module, see Sample Virtual Interface DLL.


Writing Content Server Applications

Before establishing a data service using Broadcast Architecture, a content provider must generally create or acquire computer software to manage the delivery of the data from its source to its audience. This topic discusses some of the design and programming issues that a development team needs to address when creating a data service system.

The best programming strategy depends to some extent on what kind of data is involved, as is discussed in two sections reviewing the possible kinds of broadcast data:

  • Broadcast Data Categories
  • Broadcast Data Characteristics

The section Main Office Software describes the software that content providers must write or acquire to process and broadcast data.

Also, where appropriate, a content provider must establish an online server for managing viewer subscriptions, purchases, and responses. Although the needs of such a server should be taken into account when planning development, the specific functions of any given server are beyond the scope of this document.


Broadcast Data Categories

Data intended for the Broadcast Architecture falls into three general categories:

  • Internet channel broadcasting
  • Interactive television
  • Subscription data

The first two categories are handled using special-purpose tools supplied with the Microsoft® NetShow™ server. The Microsoft® Internet Channel Server handles the first category, and most interactive television broadcasts will initially be created in existing television studios and transmitted as analog NTSC streams carrying the enhancement data in the vertical blanking interval (VBI). For more information on Internet channel broadcasting, see Microsoft® Internet Channel Client and Internet Channel Server. For more information on VBI enhancements, see Serial VBI.

The third category, subscription data, here means any content other than World Wide Web content and television enhancements that the user of a broadcast client chooses to receive. The choice to subscribe need not carry a price, and the choice may not even necessarily be explicit. For example, tuning to a given channel at a given time might be interpreted as expressing interest in receiving related data.

Subscription data can take many different forms, including the following:

  • Digital video for sale or rental
  • Computer software, including games
  • High-resolution still images or animations
  • Digital magazines or newspapers
  • Digital mail-order catalogs or advertisements

Because subscription data can vary so much in format, audience, and purpose, custom software is required to manage its broadcast.


Broadcast Data Characteristics

Data suitable for broadcast falls into many different categories and can have a variety of formats. The following general characteristics of different data have important implications for the software needed to generate, transmit, and receive the corresponding broadcast streams:

  • Value. How much is the data worth? A very high value probably justifies better encryption, more error correction, and more frequent transmission. Low value may allow higher compression and less frequent transmission.
  • Precision. How much of the data's value depends on its complete and accurate transmission? When a software program is transmitted, for example, every bit must be correctly received and verified, or the data is useless. When a bitmap graphic is transmitted, on the other hand, a good deal of data can usually be lost without compromising the value of the image. Note that because the client cannot notify the host of lost data in Broadcast Architecture, incomplete and damaged data is always discarded. Partial data and data containing irrecoverable errors is simply not received.
  • Transience. Some data loses its value soon after it is transmitted, for example stock prices or enhancements to a television show. Other data loses value very slowly, for example a software program or reference work.
  • Urgency. How important is it that viewers receive the data within a given time-frame? Urgency can be understood as a function of value and transience, but it also has a psychological component deriving from viewers' perceptions. For example, a user purchasing a new software program expects it to come shortly after she pays for it. If, on the other hand, the user purchases regular updates to her encyclopedia articles, she does not expect an immediate response.
  • Expiration. How long may a viewer keep the data? Transient data is usually used immediately upon reception and discarded, but other data may be kept indefinitely. The viewer's rights to store and use data are often limited by licensing agreements, as in the case of software rentals, pay-per-view programs, or limited subscriptions.
  • Segmentation. How is the data divided up, particularly from a subscription standpoint? A viewer might sign up for a persistent stream of information, as in the case of a stock-price or news service; for individual files, as in the case of downloading software; or perhaps for filtered subsets of a complex data stream.
  • Homogeneity. How homogeneous is the data? Stock price data, at one extreme, usually consists of small, uniform data objects that all have exactly the same size and format. A news stream, at the other extreme, might consist of many different types of data objects of radically different sizes and formats.

Analyzing a data service in terms of these characteristics is useful in determining what software is needed in the content provider's studio, at the broadcast head end, and on the home computer in order to manage the data most effectively.


Main Office Software

The software tools for content development typically run on computers located in the content provider's own facilities and vary widely with the type, source, and design of the content itself. Some of these tools are off-the-shelf commercial products, while others are special-purpose applications.

Some of the tasks content providers may need to perform follow:

  • Creating Content Data
  • Assembling Content Data
  • Storing and Cataloging Content Data
  • Synchronizing Enhancements with Television
  • Scheduling Broadcasts
  • Specifying Announcements
  • Forwarding Content Data to the Microsoft Multicast Router


Creating Content Data

Much content data used to enhance television will probably be created from scratch, using existing World Wide Web design and programming tools. To locate more information on creating content data, see Further General Information.


Assembling Content Data

This step may involve collecting data from the World Wide Web, from a data warehouses, or files on a corporate network. It is important to develop an efficient strategy for collecting data to be broadcast, whatever its source.


Storing and Cataloging Content Data

The first step in processing broadcast data is to catalog it. This is true whether the data is analog television, digital video, or any other form of digital data. This task can be accomplished using a database that contains information about what data is available and where to find it.

The diagrams following provide a schematic representation of two possible systems that catalogs content. The first diagram, following, illustrates cataloging and storing digital television or audio content. The content librarian system is a computer that an operator uses to collect the digital content, characterize it with key words and descriptive text, and store the content data and related information.

The following diagram illustrates cataloging and storing analog television content. In this case the content data is not directly available to the content librarian system, so the content lookup database must include identifying information. This information could include the title of the video, a tape ID, or a description.

The following diagram illustrates cataloging and storing other digital content. This system is similar to the digital audio and video system. The difference is that the content data comes from other sources source as web page gatherers or image libraries.


Synchronizing Enhancements with Television

The step of synchronizing television enhancements to shows is primarily relevant for digital enhancements to television and audio programming.

One way to synchronize digital broadcast data with television is to embed hidden triggers in the broadcast data stream. A program running on the broadcast client can check for triggers and display the appropriate digital enhancements when they arrive. To take advantage of this technique, a content provider must insert appropriate triggers in the broadcast data stream and settle on a way to associate each trigger with corresponding enhancement data.

In early implementations of Broadcast Architecture, digital enhancements for television will usually be stored in the vertical blanking interval (VBI) of analog television signals. However, in later implementations of Broadcast Architecture, there may be alternate, richer data steams broadcast in parallel with the television show across digital channels.

Furthermore, even early implementations of Broadcast Architecture may broadcast in advance of a show one or more digital files of subscription data, so these files are available when the show airs. This last possibility is particularly attractive to advertisers because it allows more graphics and information to be transmitted than would fit in the VBI bandwidth available..

Tools to synchronize such ancillary enhancements with television should update the content lookup database so that the link between the television show and the enhancements is recorded in that database. This link can be used to make sure that the enhancements for a particular show get transmitted in time to be used during the show. The following diagrams show such a synchronization process. The first illustration shows how digital data is combined with enhancements. First, an enhancement creation system sends the enhancements to the synchronization workstation. This workstation uses information in the content lookup database to combine the television data from the content storage array with the enhancement data. Then the synchronization workstation returns the combined data and any separate enhancement streams, to the content storage array.

In following illustration enhancements are synchronized with analog television. The enhancement creation system, synchronization workstation, and content lookup database function in the same way as the previous illustration. The difference is in the source of the video data and how the final output is stored. With analog video, only the separate enhancement streams are stored in the content storage disk array. The synchronization workstation gets video from a video tape or other video feed and passes it to a VBI system. At the same time, the synchronization workstation passes the VBI triggers and enhancements to a VBI bridge that, in turn, passes the data to the VBI system. The VBI system combines the video with the VBI data and outputs the NTSC television with triggers and enhancements.


Scheduling Broadcasts

In some cases, scheduling when broadcast data is transmitted can be trivial. In the case of a stock ticker service, for example, the data is transmitted as soon as it arrives. In many cases, however, scheduling is an extremely complex task, particularly if bandwidth is limited. Trade-offs may need to be made balancing value, urgency, precision, and data size. For example, if a data file is large, you may have to send it less often, sacrificing speedy delivery and the amount of error correction data that can be sent. Tools to facilitate this process will be extremely useful. Some considerations regarding creating such tools follow.

When the decision is made to broadcast a specific content file, relevant information must be placed in the content lookup database. This information includes the data service over which the broadcast is to occur, any authentication information required to secure bandwidth on that data service, the time or times of broadcast, the amount of bandwidth required for the broadcast, and any other information needed to ensure that the broadcast goes out over the right channel at the right time.

A scheduling system should also take into account any dependencies recorded in the content lookup database, allowing an operator to schedule these dependencies at the same time. For example, if a television show required some enhancements to be preloaded, the scheduling system should transmit such enhancements before the show.

Because scheduling is a common and repetitive task, as much as possible of the relevant scheduling information should be stored in a scheduling database. Applications running on the head end can retrieve this information automatically to support scheduling of individual content files.

The following diagram illustrates the components of this kind of scheduling process.


Specifying Announcements

Not only does a broadcast need to be scheduled, but its announcement strategy needs to be determined, and its announcement text specified.

Typically, two types of announcement are available for every broadcast: a global announcement and a local announcement. A global announcement is usually issued infrequently over a broad range of tuning space, so as to alert client machines that a given content file will be broadcast over a given channel at a given time.

A local announcement, on the other hand, is usually sent frequently for a short period before a broadcast occurs, over the same channel on which the broadcast will occur. Its purpose is to alert a client that the broadcast is imminent and to provide any last-minute tuning information that may be needed.

Both types of announcement must be formatted as Session Announcement Protocol (SAP)/Session Description Protocol (SDP) pairs

The following diagram illustrates an announcement generation system. For more information on the use of a scheduling database, see Scheduling Broadcasts; for more information on the use of a content lookup database, see Storing and Cataloging Content Data.

An announcement generation system should enable an operator to choose the timing and frequency of both global and local announcements, to specify associated Internet Protocol (IP) addresses for each type of announcement, and to determine the content of each type of announcement. This information can then be stored in the content lookup database in SAP/SDP format, ready to use.

For more information on how Broadcast Architecture works with announcements, see Announcement Listener.


Forwarding Content Data to the Microsoft Multicast Router

A content server program forwards a file to be broadcast to the Microsoft® Multicast Router at times, and on IP addresses indicated in the content lookup database.

The information used to determine what time and IP address to use might include:

  • The data service and channel on which the stream of data from the file should be broadcast.
  • Bandwidth assurance information: Should bandwidth be reserved, or can this stream be broadcast opportunistically?
  • Bandwidth requirements: If bandwidth needs to be reserved, how much and for how long?
  • The specific IP multicast address to be reserved, if one is necessary.
  • The time or times this stream should be broadcast.
  • The global announcement associated with this stream, if any, along with a specification of when, how many times, and at what intervals the announcement should be sent.
  • The local announcement associated with this stream, if any, along with a specification of when, how many times, and at what intervals the announcement should be sent.
  • Stream reuse information: Should this stream be saved for future broadcast or deleted after sending?

The content server application is responsible for such things as error checking, and error correction, encryption, key generation, and key encryption, when this is appropriate.

The content service provider communicates with the Microsoft Multicast Router (MMR) through TCP/IP. Using TCP/IP lets the content server application run on any computer that has a TCP/IP network connection to the MMR computer.


Working with the Microsoft Multicast Router

The Microsoft® Multicast Router (MMR) is a network server application that provides services to forward network traffic from a local computer network to a variety of unidirectional broadcast encoders. Network administrators can configure the MMR using a Microsoft® Management Console (MMC) snap-in. In addition applications can configure the MMR by using the Msbdnapi.dll Component Object Model (COM) object. The following section describes how to write programs that use the Msbdnapi.dll COM object.


Microsoft Multicast Router Programming

The following topics describe how to write programs that use the MMR:

  • About the Microsoft Multicast Router
  • Using the Microsoft Multicast Router


About the Microsoft Multicast Router

The Microsoft® Multicast Router (MMR) enables content servers to send data over your broadcast head end. The MMR is made up of a router program (Mrouter.exe), which routes Internet Protocol (IP) packets to a virtual interface (VIF). Each type of transmission uses a VIF. For example, to send data in the vertical blanking interval of a television signal, the MMR uses Vbi_out.dll.

System administrators can set up routes that tell the MMR which IP messages to send to which VIF by using an MMC snap-in. For more information on administrating the MMR, see Further Server Information. Applications can also create routes on the MMR by using the Msbdnapi.dll COM object. In addition to creating routes, applications can use Msbdnapi.dll to reserve bandwidth by telling the MMR when and how much data it would like to send. Msbdnapi.dll also includes an interface so that applications can reserve an IP address at a particular time. Applications can reserve an IP address in advance, send an announcement to clients that data will be sent on that IP address, and send the data at the announced time. This procedure lets client systems plan their downloading.


Using the Microsoft Multicast Router

Applications can configure the MMR using a COM based API implemented in Msbdnapi.dll. The include file Msbdnapi.h includes all the definitions needed to access the interfaces in this COM object. For details on how applications use Msbdn.dll to configure the MMR, see Configuring the Microsoft Multicast Router.

Once an application has configured the MMR, it can send data to it in TCP/IP packets. The MMR uses the configuration information to determine how to route the TCP/IP packets. For information on sending data to the MMR, see Sending Data to the Microsoft Multicast Router.


Configuring the Microsoft Multicast Router

Msbdnapi.dll is an in-process server. Each process that accesses Msbdnapi.dll is separate from all others. Therefore routes, address reservations, and bandwidth reservations created using Msbdnapi.dll only apply to the process that created them. The MMR recognizes each process by having each process set a GUID called an application ID. Applications should need to create unique GUIDs for each instance of the application using CoCreateGUID. Msbdnapi.dll keeps track of the application ID and sends it to the MMR when it is required.

Applications should delete reservations and routes that they are no longer using. This frees resources for other applications that use the MMR.

Msbdnapi.dll uses remote procedure calls (RPC) to access the MMR. Using RPCs allows applications that access the MMR to be on a different computer than the MMR. The only requirement is that the computers be connected by a network that supports RPCs. There are several reasons for such an approach, including reducing the load on the computer running the MMR and allowing data to be sent to the MMR from different locations.

There are four interfaces implemented in Msbdnapi.dll. The first interface is called IBdnApplication and allows applications to set and retreive application IDs. The application ID must be set before accessing any of the other interfaces in Msbdnapi.dll.

The next interface in Msbdnapi.dll is IBdnHostLocator. Applications use this interface to find a specific Microsoft® Address Reservation Server (ARS). The Address Reservation Server maintains a database of static IP addresses that are used for multicast data. The database includes reservations which contain information about what process has requested what IP address at what times. The IBdnHostLocater interface allows applications to give the name of a particular ARS or to search the network for any ARS.

The third interface in Msbdnapi.dll is IBdnAdressreserve. Applications use this interface to access the ARS to make, query, or delete IP address reservations.

The last interface in Msbdnapi.dll is IBdnRoute. This interface is for retrieving information from the MMR and setting up routes and bandwidth reservations. Routes are instructions that tell the MMR what IP packets get sent to what virtual interface. Bandwidth reservations are requests by a specific process to send a certain amount of data at a certain speed at a certain time.


Sending Data to the Microsoft Multicast Router

The MMR listens for packets to appear on one of the TCP/IP addresses in its routing table. When it sees such a packet, the MMR checks whether there is bandwidth available and, if so, forwards the packet to the virtual interface (VIF) specified in the routing table.


MSBDN Reference

This section documents Microsoft Broadcast Data Network (MSBDN) functions. A content server application running at a broadcast system head end uses these functions to schedule and transmit data across a Microsoft® Multicast Router (MMR) to the broadcast network. The MMR provides COM-based interfaces to classes that control the function of the MMR. Applications can use these interfaces to schedule bandwidth, reserve an IP address, and manage routes. Once the application has configured the MMR, it uses Windows Sockets (WinSock) to send data to the MMR for forwarding. For an overview of programming programs that access the MMR, see Using the Microsoft Multicast Router.

This section describes the COM interfaces used to control the MMR. The following table lists the interfaces available.

Interface | Description
IBdnAddressReserve | Manages reservations of IP addresses.
IBdnApplication | Informs the MMR that a new instance of an application needs to make address reservations.
IBdnHostLocator | Searches for or specify a particular Microsoft® Address Reservation Server.
IBdnRouter | Manages bandwidth reservations and route information.

For an overview of the head-end server architecture within which the MSBDN functions operate, see Broadcast Server Architecture.

For more information about how to design a content server application, see Writing Content Server Applications.


Data Types for the Multicast Router

The Microsoft Multicast Router (MMR) and the associated Address Reservation Service (ARS) use several structures for organizing data. These structures are defined in the file Msbdnapi.h. The following topics describe the structures in detail.


BDN_ARS_LEASE

Structure containing information about an IP address reservation.

typedef struct {
    BDN_IP_ADDR    Address;      // The IP address to reserve
    DWORD          LeaseID;      // ID for this reservation
    FILETIME       TimeStart;    // Start time of the reservation
    FILETIME       TimeEnd;      // End time of the reservation
} BDN_ARS_LEASE;


BDN_BANDWIDTH_POLICY

Enumerated variable for various bandwidth allocation policies.

typedef enum {
    BDN_BANDWIDTH_POLICY_GUARANTEED,    // The bandwidth is guaranteed to exist
    BDN_BANDWIDTH_POLICY_REGULATED,    // The bandwidth can be shared
} BDN_BADNWIDTH_POLICY;


BDN_BANDWIDTH_RESERVATION

Structure containing information about a bandwidth reservation.

typedef struct {
    LPOLESTR                DisplayName;         // Friendly name of the reservation'
    DWORD                   ReservationID;       // ID of the reservation
    DWORD                   VifID;               // ID of the VIF used for this reservation
    BDN_BANDWIDTH_POLICY    Policy;              // ??????
    DWORD                   MaxBitsPerSecond;    // The amount of bandwidth to be used in BPS
    FILETIME                TimeBegin;           // Start time of the bandwidth reservation
    FILETIME                TimeEnd;             // End time of the bandwidth reservation
} BDN_BANDWIDTH_RESERVATION;


BDN_IP_ADDR

An IP address.

typedef DWORD BDN_IP_ADDR;


BDN_ROUTE

typedef struct {
    BDN_IP_ADDRESS    Address;          // IP address of packets to be routed
    DWORD             VifID;            // VIF to which the MMR routes packets
    DWORD             ReservationID;    // Reservation associated with this route
} BDN_ROUTE;


BDN_VIF

Structure containing information about a virtual interface (VIF).

typedef struct {
    LPOLESTR    DisplayName;    // Friendly name of the VIF
    DWORD       VifID;          // ID of the VIF
} BDN_VIF;


IBdnApplication

The IBdnApplication interface includes methods to get and set the application ID. The MMR uses the application ID to match instances of applications to address and bandwidth reservations.


IBdnApplication::GetApplicationID

The GetApplicationID method retrieves the application ID set by the SetApplicationID method.

Syntax

HRESULT GetApplicationID(
  const GUID * pApplicationID
);

Parameters

pApplicationID
Pointer to the variable that will be set to the application ID GUID.

Return Value

Returns S_OK if there is a valid application ID for the current application instance. If there is not a valid application ID, the function returns E_FAIL.

See Also

IBdnApplication::SetApplicationID


IBdnApplication::SetApplicationID

The SetApplicationID method sets the ID for an instance of an application.

Syntax

HRESULT SetApplicationID(
  const GUID * pApplicationID
);

Parameters

pApplicationID
Pointer to a GUID that identifies the instance of the application calling the MMR. Application should use CoCreateGUID to obtain a unique GUID for each instance of an application.

Return Value

Returns S_OK if the MMR successfully set the ID. If the ID is not valid, this method returns E_INVALIDARG.

See Also

IBdnApplication::GetApplicationID


IBdnHostLocator

The IBdnHostLocator interface includes methods to locate or specify a particular Address Reservation Server (ARS). The ARS must be specified before using it to reserve an IP address.


IBdnHostLocator::FindServer

The FindServer method locates an Address Reservation Server (ARS).

Syntax

HRESULT FindServer(void)

Return Value

Returns S_OK if the method finds an Address Reservation Server, otherwise it returns E_FAIL.

Remarks

The method for finding the server is unspecified with this interface. Therefore; there is no reliable way to determine which server this method will return.

If this method finds an Address Reservation Server, the server found will be used in subsequent ARS calls.

See Also

IBdnHostLocator::SetServer


IBdnHostLocator::GetServer

The GetServer method retrieves the server name from the last SetServer or FindServer call.

Syntax

HRESULT GetServer(
  LPCOLESTR ServerName
);

Parameters

ServerName
Pointer to where the method should put the Unicode string containing the server name.

Return Value

Returns E_INVALIDARG if the ServerName parameter is NULL or E_OUTOFMEMORY if there is not enough memory at ServerName for the name. If the method succeeds it returns S_OK.

See Also

IBdnHostLocator::SetServer


IBdnHostLocator::SetServer

The SetServer method sets the name of the ARS to use.

Syntax

HRESULT SetServer(
  LPCOLESTR ServerName
);

Parameters

ServerName
Pointer to a Unicode string containing the name of the host to use for address reservations.

Return Value

Returns E_INVALIDARG if the ServerName parameter is NULL, otherwise the method returns S_OK.

See Also

IBdnHostLocator::GetServer, IBdnHostLocator::FindServer


IBdnAddressReserve

The IBdnAddressReserve interface includes functions for reserving IP address for use in multicasting. Note that before an application can use this interface, it must use the IBdnHostLocator interface to connect to an ARS.


IBdnAddressReserve::DeleteAllLeases

The DeleteAllLeases method deletes all address reservations made by the calling process.

Syntax

HRESULT DeleteAllLeases(void)

Return Value

Return S_OK if the method succeeds in deleting the reservations. Otherwise it returns an error code such as ARS_E_INTERNAL_DATABASE_ERROR for problems with the database or Microsoft® SQL Server™ errors.


IBdnAddressReserve::DeleteLease

The DeleteLease method deletes an address reservation.

Syntax

HRESULT DeleteLease(
  DWORD dwLeaseID
);

Parameters

dwLeaseID
ID of the lease to delete.

Return Value

Returns S_OK if the method successfully deletes the lease. Otherwise, the method returns a SQL database error.

See Also

IBdnAddressReserve::RequestLease


IBdnAddressReserve::EnumLeases

The EnumLeases method enumerates the address reservations on the ARS.

Syntax

HRESULT EnumLeases(
  DWORD * pdwArrayCount,
  BDN_ARS_LEASE ** balArray
);

Parameters

pdwArrayCount
Pointer to a variable that receives the number of reservations enumerated.
balArray
Pointer to an array of BDN_ARS_LEASE structures that receives the address of a list of reservations.

Return Value

Returns S_OK if the method returns a valid list of reservations. Otherwise it returns a SQL database error code.


IBdnAddressReserve::QueryLease

The QueryLease method requests information about a specific address reservation.

Syntax

HRESULT QueryLease(
  DWORD dwResvID,
  BDN_ARS_LEASE * pbalReservation
);

Parameters

dwResrvID
ID of the reservation to query.
pbalReservation
Pointer to a structure that receives the reservation information.

Return Value

Returns S_OK if the method successfully returns the reservation information. Otherwise the method returns E_FAIL.

See Also

IBdnAddressReserve::RequestLease


IBdnAddressReserve::RequestLease

The RequestLease method requests an IP address reservation from the ARS

Syntax

HRESULT RequestLease(
  BDN_ARS_LEASE * pbalReservation
);

Parameters

pbalReservation
Pointer to a structure that contains information about the requested reservation. The caller should set the following fields:
TimeStart
The start time for the requested reservation. Setting this field to 0 indicates that the caller would like the reservation to begin immediately.
TimeEnd
The end time for the reservation. Setting this field to 0 indicates that the reservation should continue indefinitely.

Return Value

Returns S_OK if the ARS successfully made the reservation.

See Also

IBdnAddressReserve::QueryLease


IBdnRouter

The IBdnRouter interface contains methods that let an application get the status and manage routes on the MMR.


IBdnRouter::CreateResv

The CreateResv method requests a bandwidth reservation from the MMR.

Syntax

HRESULT CreateResv(
  BDN_BANDWIDTH_RESERVATION * pbbrReservation,
  DWORD * pdwReservationID
);

Parameters

pbbrReservation
Pointer to a structure containing information about the bandwidth being requested.
pdwReservationID
Pointer to a variable that receives the ID of the bandwidth reservation.

Return Value

Returns S_OK if the MMR successfully reserved the bandwidth.


IBdnRouter::CreateRoute

The CreateRoute method creates a new route in the MMR.

Syntax

HRESULT CreateRoute(
  BDN_ROUTE * pbrRoute
);

Parameters

pbrRoute
Pointer to a structure containing information about the route to create.

Return Value

Returns S_OK if the MMR created the requested route.


IBdnRouter::DeleteResv

The DeleteResv method deletes a bandwidth reservation from the MMR reservations database.

Syntax

HRESULT DeleteResv(
  DWORD dwReservationID
);

Parameters

dwReservationID
ID of the reservation to delete.

Return Value

Returns S_OK if the MMR successfully deleted the reservation. Otherwise the method returns E_FAIL.

Remarks

The DeleteResv method only deletes reservations that were created in the current process.

See Also

IBdnRouter::CreateResv


IBdnRouter::DeleteRoute

The DeleteRoute method deletes a route used by the MMR.

Syntax

HRESULT DeleteRoute(
  BDN_ROUTE * pbrRoute
);

Parameters

pbrRoute
Pointer to a structure containing the information about the route to delete.

Return Value

Returns S_OK if the route was successfully deleted.

Remarks

DeleteRoute only deletes routes created in the current process.

See Also

IBdnRouter::CreateRoute


IBdnRouter::EnumResv

The EnumResv method returns a list of the reservations used by the MMR.

Syntax

HRESULT EnumResv(
  DWORD * pdwResvationCnt,
  BDN_BANDWIDTH_RESERVATION ** pbbrReservationList
);

Parameters

pdwReservationCnt
Pointer to a variable that receives the number of reservations returned.
pbbrReservationList
Pointer to a variable that receives a pointer to a list of reservations.

Return Value

Returns S_OK if the MMR successfully returns a list of reservations. Otherwise the method returns E_FAIL.

Remarks

The EnumResv method only returns reservations that were created in the current process.

See Also

IBdnRouter::CreateResv


IBdnRouter::EnumRoute

The EnumRoute method returns a list of the routes used by the MMR.

Syntax

HRESULT EnumRoute(
  DWORD dwFlags,
  BDN_IP_ADDRESS baIPAddress,
  DWORD dwVifID,
  DWORD dwReservationID,
  DWORD * pdwRouteCnt,
  BDN_ROUTE ** pbrRouteList
);

Parameters

dwFlags
Flags to tell the MMR what kinds of routes to return. The possible flags are:
BDN_ROUTE_ALL
Return all routes created by the calling application.
BDN_ROUTE_VIF
Return all routes that use a specific VIF.
BDN_ROUTE_IP_ADDRESS
Return all routes using a specific IP address.
BDN_ROUTE_RESV
Return all routes using a specific reservation ID.
baIPAddress
IP address to match if the BDN_ROUTE_IP_ADDRESS flags is set.
dwVifID
ID of the VIF to match is the BDN_ROUTE_VIF flag is set.
dwReservationID
ID of the bandwidth reservation to match if the BDN_ROUTE_RESV flag is set.
pdwRouteCnt
Pointer to a variable that receives the number of routes returned.
pbrRouteList
Pointer to a variable that receives a pointer to the list of routes.

Return Value

Returns S_OK if the MMR successfully returns a list of routes.

Remarks

The calling routine is responsible for freeing the memory used to hold the list of routes returned by this function using the function CoTaskMemFree.

Note that the EnumRoute method only returns routes created by in the current process.

See Also

IBdnRouter::CreateRoute


IBdnRouter::EnumVif

The EnumVif method returns a list of the virtual interfaces (VIFs) used by the MMR.

Syntax

HRESULT EnumVif(
  DWORD * pdwVifCnt,
  BDN_VIF ** ppbvVifList
);

Parameters

pdwVifCnt
The number of BDN_VIF structures returned.
ppbvVifList
Pointer a variable that points to an array of structures containing information about the VIFs used by the MMR.

Return Value

Returns S_OK if the MMR successfully returned a list of BDN_VIF structures.


IBdnRouter::QueryResv

The QueryResv method gets information about a specific bandwidth reservation.

Syntax

HRESULT QueryResv(
  DWORD dwResvID,
  BDN_BANDWIDTH_RESERVATION * pbbrReservation
);

Parameters

dwResvID
ID of the reservation to query.
pbbrReservation
Pointer to a BDN_BANDWIDTH_RESERVATION structure that receives the information about the reservation ID.

Return Value

Returns S_OK if the method returns the reservation information. Otherwise, the method returns E_FAIL.

Remarks

The QueryResv method only returns reservations that were created in the current process.

See Also

IBdnRouter::CreateResv


Virtual Interfaces

A virtual interface (VIF) is a dynamic-link library (DLL) that the Microsoft® Multicast Router (MMR) uses to route data packets to the correct output device. For more information, see:

  • About Virtual Interfaces
  • Virtual Interface Reference


About Virtual Interfaces

A virtual interface (VIF) is a user-mode dynamic-link library (DLL) that the Microsoft® Multicast Router (MMR) requires to route data packets to a specific output device. The virtual interface packages the data into network- and hardware-specific formatting. Because this packaging is performed by the virtual interface and not the MMR, the MMR software does not need to be rewritten if the network or hardware changes. You can configure new multicast routers simply by changing the MMR registry entries and the virtual interface .dll file.

The following diagram illustrates how a data stream flows from the content server to a broadcast output system.

Each head-end server infrastructure requires a virtual interface specific to its system. During testing of the MMR, Microsoft has created the following virtual interfaces:

  • Local Area Network
  • Serial VBI

For information on the specific functions that must be implemented in a virtual interface, see Virtual Interface Reference.


Local Area Network

The Local Area Network (LAN) virtual interface can be used to test broadcast server and client applications without using a satellite. Instead of forwarding data packets to particular head-end equipment, it sends them over an Ethernet LAN in the form of Internet Protocol (IP) multicast packets.

Driver File

Mc_out.dll

Output Options

The MMR can query and set the options in the following table by calling the following dynamic configuration functions for this driver: msbdnOutputGetValue, msbdnOutputGetValueCount, and msbdnOutputSetValue.

Value | Type | Meaning
Multicast TTL | Dword (DWORD) | The time-to-live (TTL) value at which this driver transmits multicast packets through the output system. The default value is 1, which restricts transmission to the local network.
Interface Address | IPAddress (IN_ADDR) | The address of the network interface card from which this driver transmits multicast packets. If this option is not specified, the operating system uses a default interface. The interface address specified must be in Internet dotted notation (xxx.xxx.xxx.xxx).


Serial VBI

This virtual interface connects a computer serial port to a Norpak TES-3 encoder, which encodes data into the vertical blanking interval (VBI). This connection enables the Norpak encoder to transmit Internet Protocol (IP) multicast packets in a standard analog television signal. The Norpak encoder must be configured to use the Norpak "Bundle FEC (Forward Error Correction)" mode of transmission. The encoder must also be configured to indicate the lines of the VBI to use. The rate encoded data is sent is determined by the number of lines of the television signal that are used.

Driver File

Vbi_out.dll

Output Options

The MMR can query and set the options in the following table by calling the following dynamic configuration functions for this driver: msbdnOutputGetValue, msbdnOutputGetValueCount, and msbdnOutputSetValue.

Value | Type | Meaning
Serial Port | String (LPWSTR) | The communications resource, such as the serial port COM1, to use for communication with the TES-3 encoder.
Serial Port Bit Rate | Dword (DWORD) | The speed in bits per second of the serial port to use for communication with the TES-3 encoder. To locate more information on determining this speed, see Further Server Information.
Debug Log Filename | String (LPWSTR) | The name and path of a file to which this driver writes debugging data.
Debug Log Enable | Boolean (BOOL) | Turns on or off packet dump mode, causing or preventing the contents of packets to be displayed in the output log file specified by the Debug Log Filename option. Setting this value to TRUE turns on packet dump mode, and setting this value to FALSE turns off packet dump mode.
Use Old Framing Mode | Boolean (BOOL) | If set to TRUE, encodes packets in a way that is compatible with the initial experiments by Microsoft with VBI encoding. If set to FALSE, encodes packets using the Microsoft® UDP/IP compression algorithm. Note that a FALSE value is not yet completely supported.


Virtual Interface Reference

This section documents the functions that make up the interface between the Microsoft® Multicast Router (MMR) and a virtual interface, which sends data streams to a broadcast output device. Such a virtual interface communicates with the input unit of a broadcast data encoder. This section also documents structures that hardware vendors use to implement the virtual interface.

The virtual interface is documented in four groups:

  • Virtual Interface Functions
  • MMR Functions
  • Virtual Interface Structures
  • Sample Virtual Interface DLL


Virtual Interface Functions

Hardware vendors should implement the virtual interface functions described in this section. These functions package data from a stream into a specific format, so a particular broadcast encoder can transmit the data stream over a particular network.

Hardware vendors should build their virtual interfaces as dynamic-link libraries (DLLs) that the MMR loads at run time. A virtual interface DLL must implement all the functions listed following that are specified as required. Only virtual interface DLLs that support dynamic configuration must implement the functions listed following that are specified as optional. A virtual interface DLL that supports dynamic configuration enables the MMR to query or set any number of values defined by the virtual interface. Implementation of dynamic configuration is strongly encouraged.

Each virtual interface must be able to safely host multiple instances of an output system. In other words, the MMR should be able to load a virtual interface more than once with separate parameters and route different packet streams to such different instances of a virtual interface. The MMR should be able to independently start and stop each instance of a virtual interface; that is, the MMR should be able to load and unload a driver instance from the MMR's address space.

At run time, the MMR loads the appropriate virtual interface DLL with an output loader. The output loader calls the RegQueryValueEx function, which is part of the Microsoft® Win32® application programming interface (API). The output loader passes RegQueryValueEx the string OutputDLL to retrieve the file name of the virtual interface DLL. The output loader then calls the LoadLibrary Win32 function and passes this file name to retrieve a handle to the output DLL. The output loader uses this handle in calls to the GetProcAddress Win32 function. These calls get the address of each exported function of the virtual interface DLL. To locate documentation on these Win32 API functions that the output loader calls, see Further Server Information.

The following table lists and describes the virtual interface functions.

Function | Description
msbdnOutputCreate | Creates and initializes a single instance of a virtual interface. This function is required.
msbdnOutputDestroy | Destroys an instance of a virtual interface. This function is required.
msbdnOutputFreeBuffer | Frees a buffer returned by msbdnOutputGetValue. This function is optional.
msbdnOutputGetStatus | Retrieves the status of a virtual interface. This function is required.
msbdnOutputGetValue | Retrieves a configuration value of a virtual interface. This function is optional.
msbdnOutputGetValueCount | Retrieves the number of configuration values supported by a virtual interface. This function is optional.
msbdnOutputSendPacket | Sends all packets of a data stream to the output system. This function is required.
msbdnOutputSetValue | Assigns a configuration value to a virtual interface. This function is optional.


msbdnOutputCreate

The msbdnOutputCreate function creates and initializes a single instance of a virtual interface.

HRESULT msbdnOutputCreate(
  OUT MSBDN_OUTPUT_SUBSYSTEM *Subsystem,
  IN DWORD ApiVersion
);

Parameters

Subsystem
Address of an MSBDN_OUTPUT_SUBSYSTEM structure that is to receive details about the virtual interface implementation. This function fills the structure with information about the virtual interface and the output device that the MMR is to send data to.
ApiVersion
Highest version of the virtual interface interface that the caller can use. The high-order bytes specify the minor version number, for example version x.1. The low-order bytes specify the major version number, for example version 1.

Return Values

Returns zero if the function was successful. If the function fails, the return value is non-zero. If this function is unable to allocate memory for an instance of the virtual interface, this function should return E_OUTOFMEMORY.

Remarks

After loading a virtual interface DLL, the MMR immediately calls the msbdnOutputCreate function. This function is only called once, and no other virtual interface functions are called until this function returns.

The msbdnOutputCreate function should create any synchronization objects that it requires and try to connect to and initialize the appropriate output system or device drivers it will use. If a virtual interface DLL stores values in the registry when the DLL starts, msbdnOutputCreate should call the RegQueryValueEx Win32 function for each configuration value and pass the open registry key contained in the Subsystem parameter, the name of the configuration value to retrieve, and a buffer to hold the configuration data. The msbdnOutputCreate function could also provide default data for each configuration value. The msbdnOutputCreate function should then store retrieved or provided configuration data in values defined by the virtual interface. When the MMR requires a dynamic value from the virtual interface's configuration, the MMR calls msbdnOutputGetValue to retrieve such a value.

If msbdnOutputCreate cannot initialize an instance of the virtual interface, it should return a failure condition. The msbdnOutputCreate function should only return a failure condition if there is some condition that prevents the virtual interface from ever running correctly. For example, the virtual interface should not return an error condition if some configuration parameter prevents the hardware from functioning because the virtual interface can only change configuration parameters of the hardware if this function succeeds.

The msbdnOutputCreate function allows the MMR to specify the version of the virtual interface interface that a particular virtual interface is required to support. The function also allows the MMR to retrieve details about the virtual interface's implementation.

In order for the MMR to support future implementations of the virtual interface interface that might have functionality different from that current, a negotiation should take place in msbdnOutputCreate. The MMR and the particular virtual interface DLL indicate to each other the highest interface version that they can support. Each confirms that the other's highest version is acceptable, if it is.

To do so, the virtual interface DLL examines the version requested by the MMR. If this version is equal to or higher than the lowest version supported by the DLL, the call succeeds. On a successful call, the DLL returns the highest version it supports in the Version member of MSBDN_OUTPUT_SUBSYSTEM. In the structure's Version member, the virtual interface DLL returns either the highest version it supports or the version number that the MMR is requesting, whichever is lower.

After msbdnOutputCreate returns, the virtual interface DLL works under the assumption that the MMR uses the interface version returned in Version. If the MMR cannot work with this version, the MMR does not call any other virtual interface functions.

This negotiation allows both a virtual interface DLL and the MMR to support a range of function versions. The MMR can successfully use a virtual interface DLL if there is any overlap in the version ranges.

See Also

msbdnOutputDestroy, msbdnOutputGetValue, MSBDN_OUTPUT_SUBSYSTEM


msbdnOutputDestroy

The msbdnOutputDestroy function shuts down the output system and deletes the instance of the virtual interface DLL before unloading the DLL.

HRESULT msbdnOutputDestroy(
  IN MSBDN_OUTPUT_SUBSYSTEM *Subsystem
);

Parameters

Subsystem
Address of an MSBDN_OUTPUT_SUBSYSTEM structure that contains details about the virtual interface implementation.

Return Values

Should always return zero for a successful status.

Remarks

The msbdnOutputDestroy function is the last virtual interface function that the MMR calls before exiting. When msbdnOutputDestroy is called, the virtual interface DLL should stop all data transmissions, close any devices it has opened, free all packet queues, and release all resources that it allocated such as synchronization objects. The msbdnOutputDestroy function must complete any PACKET_BUFFER handles which it has queued. Because msbdnOutputDestroy is the last function that the MMR calls before exiting, msbdnOutputDestroy should block other functions' processing until it is done with all cleanup.

See Also

msbdnOutputCreate, MSBDN_OUTPUT_SUBSYSTEM, PacketBufferComplete, PACKET_BUFFER


msbdnOutputFreeBuffer

The msbdnOutputFreeBuffer function frees string storage that the MMR obtained from a call to the msbdnOutputGetValue function.

HRESULT msbdnOutputFreeBuffer(
  IN MSBDN_OUTPUT_SUBSYSTEM *Subsystem
  IN LPVOID Buffer
);

Parameters

Subsystem
Address of an MSBDN_OUTPUT_SUBSYSTEM structure that contains details about the virtual interface implementation.
Buffer
Memory storage containing a null-terminated string that this function frees.

Return Values

Should always return zero for a successful status.

Remarks

A virtual interface DLL should implement msbdnOutputFreeBuffer so that the MMR can configure the DLL dynamically. Typically, the implementation for msbdnOutputFreeBuffer should free string storage by calling the free C function, the delete C++ function, or the GlobalFree Win32 base services function. The particular implementation for a virtual interface DLL's string memory management is left up to the hardware vendor.

See Also

msbdnOutputGetValue, MSBDN_OUTPUT_SUBSYSTEM


msbdnOutputGetStatus

The msbdnOutputGetStatus function retrieves the current status of the virtual interface DLL for the MMR.

HRESULT msbdnOutputGetStatus(
  IN MSBDN_OUTPUT_SUBSYSTEM *Subsystem,
  OUT HRESULT *Status
);

Parameters

Subsystem
Address of an MSBDN_OUTPUT_SUBSYSTEM structure that contains details about the virtual interface implementation.
Status
Pointer to a value specifying the current status of the virtual interface DLL.

Return Values

Returns zero if the function was successful. If the function fails, the return value is non-zero.

Remarks

The virtual interface DLL should return a status of S_OK in the Status parameter if it is working properly, and otherwise should return an error code.

See Also

MSBDN_OUTPUT_SUBSYSTEM


msbdnOutputGetValue

The msbdnOutputGetValue function retrieves a specific dynamic value of the virtual interface DLL's configuration for the MMR.

HRESULT msbdnOutputGetValue(
  IN MSBDN_OUTPUT_SUBSYSTEM *Subsystem,
  IN/OUT MSBDN_OUTPUT_VALUE *Value
);

Parameters

Subsystem
Address of an MSBDN_OUTPUT_SUBSYSTEM structure that contains details about the virtual interface implementation.
Value
Address of an MSBDN_OUTPUT_VALUE structure that is to receive details about a dynamic value of the virtual interface's configuration specified by the Index member of MSBDN_OUTPUT_VALUE. This function fills the structure with information about the specified value.

Return Values

Returns zero if the function was successful. If the function fails, the return value is non-zero. If the Index member of MSBDN_OUTPUT_VALUE in the Value parameter is not valid, msbdnOutputGetValue should return E_INVALIDARG.

Remarks

The MMR calls msbdnOutputGetValue to obtain a dynamic value from the virtual interface's configuration with the value's index. The msbdnOutputGetValue function should set the name and data type of the configuration value and the member of the union within MSBDN_OUTPUT_VALUE in the Value parameter corresponding to the correct data type.

If the virtual interface specifies the data type as a string, the virtual interface DLL must allocate this string on the heap. The virtual interface should never return a pointer to global storage; this practice is not safe in a multithreaded environment. To release memory storage for this string, the MMR calls msbdnOutputFreeBuffer.

See Also

msbdnOutputFreeBuffer, msbdnOutputSetValue, MSBDN_OUTPUT_SUBSYSTEM, MSBDN_OUTPUT_VALUE


msbdnOutputGetValueCount

The msbdnOutputGetValueCount function retrieves the upper bound on the number of indexes of configuration values that the virtual interface DLL supports.

HRESULT msbdnOutputGetValueCount(
  IN MSBDN_OUTPUT_SUBSYSTEM *Subsystem,
  OUT DWORD *ValueCount
);

Parameters

Subsystem
Address of an MSBDN_OUTPUT_SUBSYSTEM structure that contains details about the virtual interface implementation.
ValueCount
Address of a value that specifies the upper bound on the number of indexes of configuration values that the virtual interface DLL supports. Usually, this value is a constant.

Return Values

Should always return zero for a successful status.

Remarks

The MMR calls msbdnOutputGetValueCount to obtain the number of dynamic configuration parameters the output system might support. For example, if an output system supports a serial-port value, a bit-rate value, and a framing-mode value, msbdnOutputGetValueCount should store the number three in the memory to which the ValueCount parameter points.

See Also

msbdnOutputGetValue, MSBDN_OUTPUT_SUBSYSTEM


msbdnOutputSendPacket

The msbdnOutputSendPacket function sends all packets of a data stream to the output system.

HRESULT msbdnOutputSendPacket(
  IN MSBDN_OUTPUT_SUBSYSTEM *Subsystem,
  IN PACKET_BUFFER *Packet
);

Parameters

Subsystem
Address of an MSBDN_OUTPUT_SUBSYSTEM structure that contains details about the virtual interface implementation.
Packet
Address of a PACKET_BUFFER structure that describes a packet of data.

Return Values

Returns zero if the virtual interface successfully transmitted the packet. If the function fails, the return value is non-zero.

Remarks

While a stream is active, the stream functionality of the MMR calls the msbdnOutputSendPacket function in the virtual interface DLL. The MMR does so to send a stream's data packets to the broadcast encoder or to other output systems. The msbdnOutputSendPacket function is responsible for translating protocol types, generating network-specific addresses, and reformatting data to follow network-specific protocols.

The virtual interface can alter the Start and End members of a PACKET_BUFFER structure and can alter the memory to which the Data member of PACKET_BUFFER points. However, the virtual interface must not alter the information within the Data member itself. The MMR stores the actual data that the virtual interface transmits in the buffer to which the Data member of PACKET_BUFFER points. The data that the virtual interface transmits begins at the index given by the Start member of PACKET_BUFFER and ends at the index given by the End member of PACKET_BUFFER. The buffer for transmitted packets is structured in this manner to allow virtual interfaces to efficiently add or remove packet headers and trailers without requiring that the virtual interface copy the entire packet elsewhere in memory.

The length of the actual packet data is determined by subtracting the PACKET_BUFFER's Start member from its End member. Provided that there is sufficient space at the beginning of the packet buffer, the virtual interface could decrease the value of the PACKET_BUFFER's Start member and then store new data in that memory location. The virtual interface could also extend the packet by increasing the PACKET_BUFFER's End member. However, the virtual interface must never increase the value of the PACKET_BUFFER's End member beyond its Max member. The virtual interface can also change the values of the PACKET_BUFFER's Start and End members to decrease the length of the packet.

Examples of the virtual interface manipulating packets include:

  • Removing an IP and then a UDP header in order to extract just the UDP body data
  • Encapsulating an IP packet in a larger frame

The virtual interface can accomplish these tasks without copying the packet data, which facilitates high-speed applications.

The virtual interface must "complete" the packet buffer when it is done processing it. If the virtual interface can finish processing the packet immediately, it should complete the packet buffer before returning from msbdnOutputSendPacket; this operation is synchronous. Otherwise, the virtual interface might store the packet in a queue and complete the packet later in a different thread; this operation is asynchronous.

If the MMR receives data with protocol types it cannot decipher, it forwards the data to the virtual interface without modification.

See Also

MSBDN_OUTPUT_SUBSYSTEM, PacketBufferComplete, PACKET_BUFFER


msbdnOutputSetValue

The msbdnOutputSetValue function assigns a dynamic value to a virtual interface DLL's configuration specified by the MMR.

HRESULT msbdnOutputSetValue(
  IN MSBDN_OUTPUT_SUBSYSTEM *Subsystem,
  IN MSBDN_OUTPUT_VALUE *Value
);

Parameters

Subsystem
Address of an MSBDN_OUTPUT_SUBSYSTEM structure that contains details about the virtual interface implementation.
Value
Address of an MSBDN_OUTPUT_VALUE structure. This structure contains details about a dynamic value for the output system's configuration that the MMR requires set.

Return Values

Returns zero if the function was successful. If the function fails, the return value is non-zero. If the Index member of MSBDN_OUTPUT_VALUE in the Value parameter is not valid or the Type member is not correct, msbdnOutputGetValue should return E_INVALIDARG.

Remarks

The MMR calls msbdnOutputSetValue to set a specific dynamic configuration value. The index of the value is stored in the Index member of MSBDN_OUTPUT_VALUE in the Value parameter. The virtual interface DLL should look up the dynamic configuration value corresponding to this index, check to make sure that the data type passed by the MMR is correct for this value, set its own internal value for this configuration value, and should store this configuration value in persistent storage. A virtual interface usually stores values in the registry. If this configuration value affects communication with external equipment, such as setting a bitrate divisor, this change should take place immediately, provided doing so does not cause other problems.

If a virtual interface stores values in the registry, msbdnOutputSetValue should call the RegSetValueEx Win32 function and pass the open registry key contained in the Subsystem parameter, the name of the configuration value to set, and the buffer containing the configuration data. The buffer that holds this configuration data contains the address of the union member of MSBDN_OUTPUT_VALUE in the Value parameter.

See Also

msbdnOutputGetValue, MSBDN_OUTPUT_SUBSYSTEM, MSBDN_OUTPUT_VALUE


MMR Functions

The Microsoft Multicast Router (MMR) also is a dynamic-link library (DLL), which virtual interface DLLs bind to at run time. In this library, the MMR exports a callback function that allows virtual interface DLLs to report internal events and a completion function that allows the virtual interface to report that it has finished with a packet.

Hardware vendors should implement their virtual interface code by including the Bridge.h header file and by calling the MMR functions described in this section. When vendors build virtual interface DLLs, they should link their virtual interface code to the Bdnapi.lib library.

The following table lists and describes the MMR functions.

Function | Description
msbdnBridgeReportEvent | Informs the MMR to record virtual interface events directly in the system event log.
PacketBufferComplete | Informs the MMR that the virtual interface is done processing a packet.


msbdnBridgeReportEvent

The msbdnBridgeReportEvent function informs the MMR to record virtual interface events directly in the system event log.

HRESULT msbdnBridgeReportEvent(
  IN MSBDN_OUTPUT_SUBSYSTEM *Subsystem,
  IN WORD wType,
  IN DWORD dwErrorCode,
  IN LPCSTR szMessage
);

Parameters

Subsystem
Address of an MSBDN_OUTPUT_SUBSYSTEM structure that contains details about the virtual interface implementation.
wType
A value that can be one of the following three standard Win32 error types: EVENTLOG_INFORMATION_TYPE, EVENTLOG_ERROR_TYPE, or EVENTLOG_WARNING_TYPE.
dwErrorCode
A value that can be a Win32 error code, a Windows Sockets error code, a standard system HRESULT value, or one of status codes defined in the Brerror.h header file. If this value is an error code, then the full textual description of the error message will be included with the event in the szMessage parameter.
szMessage
A Unicode string containing the message to record in the event log.

Return Values

Returns zero if the function was successful. If the function fails, the return value is non-zero. To get extended error information, call the Win32 function GetLastError. To locate more information on GetLastError, see Further General Information.

Remarks

The msbdnBridgeReportEvent function allows a virtual interface to easily record events in the event log. A virtual interface can also call the functions of the underlying Win32 event logging application programming interface (API). Using msbdnBridgeReportEvent reduces overhead for a virtual interface implementation.

The MMR implements msbdnBridgeReportEvent as an inline function in the Bridge.h header file. The msbdnBridgeReportEvent implementation calls the ReportEvent member of the MSBDN_BRIDGE_CALLBACKS structure for a specific virtual interface instance defined by an MSBDN_OUTPUT_SUBSYSTEM structure. An inline function by definition is a function whose code gets substituted in place of the actual call to that function. That is, whenever the compiler encounters a call to that function, it merely replaces it with the code itself, thereby saving overhead.

See Also

MSBDN_BRIDGE_CALLBACKS, MSBDN_OUTPUT_SUBSYSTEM


PacketBufferComplete

The PacketBufferComplete function informs the MMR that the virtual interface is done processing a packet and provides status on the completed packet.

void PacketBufferComplete(
  IN PACKET_BUFFER *Packet,
  IN DWORD dwStatus
);

Parameters

Packet
Address of a PACKET_BUFFER structure that describes a packet the virtual interface is finished with.
dwStatus
Value specifying the status of the completed packet. The following table lists and describes the valid status values.
Value | Meaning
PACKET_COMPLETE_FAILURE | A failure occurred in processing the packet.
PACKET_COMPLETE_NO_ROUTE | The virtual interface was unable to route the packet.
PACKET_COMPLETE_OVERFLOW | The virtual interface cannot process the packet synchronously and lacks queue space to process the packet asynchronously.
PACKET_COMPLETE_SUCCESS | Processing of the packet completed successfully.

Return Values

None

Remarks

The MMR implements PacketBufferComplete as an inline function in the Packet.h header file; the Bridge.h header file includes Packet.h. The PacketBufferComplete implementation calls the CompletionFunc member of the PACKET_BUFFER structure for the passed in packet.

Virtual interface DLLs can be implemented for particular output systems that use first-in-first-out (FIFO) chips of a fixed-length in the range of 32 to 64 slots. If such a virtual interface fills the output system's FIFO before transmitting all the packet data, then the virtual interface must inform the MMR that it is done processing the packet with a status value of PACKET_COMPLETE_OVERFLOW.

See Also

PACKET_BUFFER


Virtual Interface Structures

To write virtual interfaces that format and send data to a broadcast encoder or other output systems, you can use the structures discussed in this section. These structures describe specific output systems and drivers and the data packets that virtual interfaces send to their systems. The following table lists and describes these structures.

Structure | Description
MSBDN_BRIDGE_CALLBACKS | Contains information about pointers to callback functions exported by the MMR
MSBDN_OUTPUT_SUBSYSTEM | Contains information representing a specific output system
MSBDN_OUTPUT_VALUE | Contains information about a configuration value
PACKET_BUFFER | Contains information about a packet of data that a virtual interface transmits


MSBDN_BRIDGE_CALLBACKS

The MSBDN_BRIDGE_CALLBACKS structure contains information about pointers to callback functions exported by the MMR that allow virtual interface DLLs to report internal status.

typedef struct MSBDN_BRIDGE_CALLBACKS {
    DWORD Version;
    HRESULT    (*ReportState) (struct MSBDN_OUTPUT_SUBSYSTEM *,
                               DWORD state, LPCSTR message);
    HRESULT    (*ReportActivity) (struct MSBDN_OUTPUT_SUBSYSTEM *,
                               WORD type, DWORD amount);
    HRESULT    (*ReportEvent) (struct MSBDN_OUTPUT_SUBSYSTEM *,
                               WORD, DWORD, LPCWSTR);
} MSBDN_BRIDGE_CALLBACKS;

Members

Version
Version number of the MMR callback reference.
ReportState
Pointer to a function that a virtual interface calls to inform the MMR about the state of such virtual interface.
ReportActivity
Pointer to a function that a virtual interface calls to inform the MMR about real-time bandwidth usage and minor problems with the output system.
ReportEvent
Pointer to a function that a virtual interface calls to inform the MMR of a virtual interface event.

See Also

msbdnBridgeReportEvent


MSBDN_OUTPUT_SUBSYSTEM

The MSBDN_OUTPUT_SUBSYSTEM structure contains information representing a specific output system that a virtual interface can configure dynamically and to which a virtual interface sends data packets.

typedef struct MSBDN_OUTPUT_SUBSYSTEM {
    DWORD                  Version;
    MSBDN_BRIDGE_CALLBACKS BridgeCallbacks;
    MSBDN_SUBSYSTEM_ID     OutputSubsystemID;
    HKEY                   RegistryKey;
    LPVOID                 DriverContext;
} MSBDN_OUTPUT_SUBSYSTEM;

Members

Version
Version of the virtual interface interface that the virtual interface requires the MMR to support.
BridgeCallbacks
An MSBDN_BRIDGE_CALLBACKS structure containing information about pointers to callback functions exported by the MMR that allow virtual interface DLLs to report internal status.
OutputSubsystemID
A value that identifies a particular output system. This value uniquely identifies an instance of a virtual interface DLL. An MSBDN_SUBSYSTEM_ID data type is defined as a DWORD data type.
RegistryKey
The handle of an open registry key that the virtual interface can use to retrieve any previously stored configuration data and to store new configuration data. The virtual interface can use this registry key handle but should not close or alter it. This value should not be NULL.
DriverContext
Reserved for the virtual interface to use. Typically, this member points to a structure defined by the virtual interface DLL that contains all of the internal state information of an instance of an output system such as configuration data, synchronization objects, and device handles.

Remarks

In every virtual interface function call, the MMR passes a pointer to MSBDN_OUTPUT_SUBSYSTEM in order to uniquely identify a specific instance of a virtual interface DLL.

See Also

MSBDN_BRIDGE_CALLBACKS


MSBDN_OUTPUT_VALUE

The MSBDN_OUTPUT_VALUE structure contains information about a dynamic value for a virtual interface's configuration.

typedef struct MSBDN_OUTPUT_VALUE {
    DWORD  Index;
    DWORD  Type;
    LPWSTR Name;
    union {
        DWORD   Dword;
        LPWSTR  String;
        IN_ADDR IPAddress;
        BOOL    Boolean;
    };
} MSBDN_OUTPUT_VALUE;

Members

Index
Index number of a dynamic value for a virtual interface's configuration.
Type
Value specifying the type of information stored as configuration data. The following table lists and describes the valid values.
Value | Meaning
MSBDN_OUTPUT_VALUE_BOOLEAN | BOOL data type
MSBDN_OUTPUT_VALUE_DWORD | DWORD data type
MSBDN_OUTPUT_VALUE_IPADDRESS | IN_ADDR data type
MSBDN_OUTPUT_VALUE_STRING | LPWSTR data type

Name
A null-terminated string containing the name of a dynamic value for a virtual interface's configuration.
Dword
Member of the union contained in MSBDN_OUTPUT_VALUE that can hold a 32-bit number (DWORD) as configuration data.
String
Member of the union contained in MSBDN_OUTPUT_VALUE that can hold a Unicode string (LPWSTR) as configuration data.
IPAddress
Member of the union contained in MSBDN_OUTPUT_VALUE that can hold an IP address (IN_ADDR) as configuration data.
Boolean
Member of the union contained in MSBDN_OUTPUT_VALUE that can hold a Boolean value (BOOL) as configuration data.

See Also

msbdnOutputGetValue, msbdnOutputSetValue


PACKET_BUFFER

The PACKET_BUFFER structure contains information about a packet of data that a virtual interface sends to its output system.

typedef struct PACKET_BUFFER {
    LPBYTE                 Data;    // storage for packet data
    DWORD                  Start;   // where the data begins
    DWORD                  End;     // where the data ends
    DWORD                  Max;     // the physical length of Data
    DWORD                  Context;
    WORD                   Protocol;
    WORD                   AddressLength;
    BYTE                   Address[16];
    PACKET_COMPLETION_FUNC CompletionFunc;
} PACKET_BUFFER;

Members

Data
Buffer containing the data that the virtual interface transmits.
Start
The beginning memory location of the transmitted data.
End
The ending memory location of the transmitted data.
Max
The maximum physical length of the transmitted data. The End member can never be increased beyond the value of Max.
Context
Value specifying the context of the transmitted data.
Protocol
Value specifying the format of the data. The following table lists and describes the valid format values.
Value | Meaning
PACKET_BUFFER_PROTOCOL_IP | The packet body is a full IP packet, including header and body. Virtual interfaces should extract an IP address from the message body. The Address member of PACKET_BUFFER is not used.
PACKET_BUFFER_PROTOCOL_VBI_RAW | The packet is a VBI frame. The Address member of PACKET_BUFFER is not used.

AddressLength
Size, in bytes, of the Address array. If Address is null, AddressLength is zero.
Address
An array of bytes specifying an address to which the packet belongs. This array can be no longer than 16 bytes.
CompletionFunc
Pointer to a function that a virtual interface DLL calls to inform the MMR that the DLL is done processing the packet buffer. In this call, the DLL provides status on the completed packet.

Remarks

The MMR keeps track of packets with the PACKET_BUFFER structure. A virtual interface uses PACKET_BUFFER to route packets from the MMR to a specific output system.

The PACKET_BUFFER structure provides virtual interfaces with an easy way to add or remove packet headers without requiring memory allocation and copy operations. For example, to remove an IP header from a packet, advance the Start member of PACKET_BUFFER by the length of the IP header. To add an Ethernet frame header to the front of a packet, first insure that there is sufficient space at the beginning of the packet buffer by checking to make sure that the Start member is greater than or equal to the length of an Ethernet header. Then, subtract the length of the Ethernet header from the Start member and fill in the appropriate members in the Ethernet header.

When the MMR calls the msbdnOutputSendPacket function on a specific instance of a virtual interface, such a virtual interface takes responsibility for the passed PACKET_BUFFER while processing it. This virtual interface must eventually call the PacketBufferComplete function to indicate to the MMR that the virtual interface is done processing.

See Also

msbdnOutputSendPacket, PacketBufferComplete


Sample Virtual Interface DLL

This section describes source code for the sample dynamic-link libraries (DLLs) for virtual interfaces (VIFs) that are provided as part of the Microsoft® Platform Software Development Kit (SDK). These DLLs are provided to give hardware vendors assistance in writing their own virtual interface DLLs. To be of maximum value, this section requires the user to have the Main.cpp source code files close at hand. You can find these files in the Mc_out and Nulloss directories.

Note Virtual interface DLLs are components of a broadcast server and therefore only run on the Microsoft® Windows NT® Server version 4.0 operating system or later operating systems.

The following sections describe:

  • Sample Virtual Interface Overview
  • Sample Virtual Interface Anatomy
  • Sample Virtual Interface Walk-through


Sample Virtual Interface Overview

The beta program for the Microsoft® Windows® 98 operating system and the Platform SDK provide the source code for two sample virtual interfaces described as follows.

The source code for the Mc_out.dll sample demonstrates a virtual interface that broadcasts over a local area network (LAN). Such a virtual interface can be used to test broadcast server and client applications without using a vertical blanking interval (VBI) transmitter. Instead of forwarding data packets from the Microsoft® Multicast Router (MMR) to particular head-end equipment, Mc_out.dll sends them over an Ethernet LAN in the form of Internet Protocol (IP) multicast packets. The source code for the Mc_out.dll shows implementations for the optional functions that support dynamic configuration in addition to the required functions. The required and optional functions for a virtual interface are described in Sample Virtual Interface Anatomy.

The source code for the Nulloss.dll sample demonstrates a virtual interface that is useful for debugging purposes. Such a virtual interface can collect packets from the MMR, and rather than forwarding those packets to particular head-end equipment, periodically display the bandwidth of the packets. Because the Nulloss.dll sample does not have any configuration values, it does not export the optional functions that support dynamic configuration and its source code does not show implementations for those functions.


Sample Virtual Interface Anatomy

After installing the Broadcast Architecture Programmer's Reference material, the Main.cpp files for both samples are available. These sample files aid the user in understanding the purpose of each sample and its relationship to the MMR. The following table shows how the MMR calls and the uses of the exported virtual interface functions. Documentation for the following exported virtual interface functions can be found in the Virtual Interface Functions section.

HRESULT msbdnOutputCreate(
  MSBDN_OUTPUT_SUBSYSTEM * subsystem,
  DWORD version);
Creates and initializes a single instance of a virtual interface. This function is required.
HRESULT msbdnOutputDestroy(
  MSBDN_OUTPUT_SUBSYSTEM * subsystem);
Destroys an instance of a virtual interface. This function is required.
HRESULT msbdnOutputFreeBuffer(
  MSBDN_OUTPUT_SUBSYSTEM * subsystem,
  LPVOID buffer);
Frees a buffer returned by msbdnOutputGetValue. This function is optional.
HRESULT msbdnOutputGetStatus(
  MSBDN_OUTPUT_SUBSYSTEM * subsystem,
  HRESULT * status);
Retrieves the status of a virtual interface. This function is required.
HRESULT msbdnOutputGetValue(
  MSBDN_OUTPUT_SUBSYSTEM * subsystem,
  MSBDN_OUTPUT_VALUE * value);
Retrieves a configuration value of a virtual interface. This function is optional.
HRESULT msbdnOutputGetValueCount(
  MSBDN_OUTPUT_SUBSYSTEM * subsystem,
  DWORD * count);
Retrieves the number of configuration values supported by a virtual interface. This function is optional.
HRESULT msbdnOutputSendPacket(
  MSBDN_OUTPUT_SUBSYSTEM * subsystem,
  PACKET_BUFFER * packet);
Sends all packets of a data stream to the output system. This function is required.
HRESULT msbdnOutputSetValue(
  MSBDN_OUTPUT_SUBSYSTEM * subsystem,
  MSBDN_OUTPUT_VALUE * value);
Assigns a configuration value to a virtual interface. This function is optional.


Sample Virtual Interface Walk-through

The following steps briefly describe creation, use, and destruction for the Mc_out.dll sample. The Mc_out.dll functions mentioned in this section are described in greater detail in Virtual Interface Functions.

  1. At run time, the MMR loads Mc_out.dll with an output loader and retrieves the address of each exported function of the DLL. The MMR then calls the msbdnOutputCreate function and specifies the version of the required output system so it can retrieve details of the specific virtual interface implementation. The msbdnOutputCreate function then connects to the appropriate output system with specific options obtained from the virtual interface's configuration and configures the output system. The msbdnOutputCreate function calls the WinSock socket function to create a socket that uses UDP for the Internet address family and then calls the WinSock bind function to bind a local address to such a socket. If the socket could not be bound to a UDP/IP port, msbdnOutputCreate calls the msbdnBridgeReportEvent function and passes the EVENTLOG_ERROR_TYPE error type and the error code provided by WinSock to inform the MMR to record the error directly in the system event log.
  2. When the MMR requires dynamic values of the virtual interface's configuration, it calls the msbdnOutputGetValueCount and msbdnOutputGetValue functions.
  3. When the MMR assigns a dynamic value to a virtual interface's configuration, it calls the msbdnOutputSetValue function.
  4. When the MMR has data to send, it calls the msbdnOutputSendPacket function to send a packet of a data stream to the output system. After msbdnOutputSendPacket has finished processing the packet, it informs the MMR by calling the PacketBufferComplete function and provides status on the completed packet.
  5. Before exiting, the MMR calls the msbdnOutputDestroy function to stop all data transmissions and free all resources that the virtual interface allocated.


Internet Channel Server

Internet channel broadcasting is an architecture that enables World Wide Web sites to be collected, packaged, and then broadcast to multiple subscribers simultaneously.

Currently, the Web operates on a one-to-one basis. Each user who wants to view a site must create a separate connection to that site. If too many users try to access a site at the same time, the server is unable to handle all of the requests. In contrast, Internet channel broadcasting operates on a one-to-many basis. Web sites are broadcast to many users at once and stored in each user's cache until the user is ready to view them.

The Microsoft® Internet Channel Server runs as a service on the Microsoft® Windows NT® Server operating system, version 4.0 or greater. You can administer the server to automatically collect, package, and broadcast Internet channels, also know as Channel Definition Format files. Because the server uses broadcast technology, the channels can be multicast to many users at once.


Using Broadcast Architecture

The following sections describe how to perform development tasks common when working with Broadcast Architecture:

  • Displaying Video
  • Writing a Custom Guide Database Loader
  • Scheduling Show Reminders
  • Recording Shows
  • Creating Controls for WebTV for Windows
  • Building Enhancement Authoring Tools
  • Writing and Testing Server Applications

These sections are closely integrated with the Broadcast Architecture sample applications provided with the Microsoft® Platform Software Development Kit (SDK). To locate these sample applications, see Broadcast Architecture Sample Applications.


Broadcast Architecture Sample Applications

A group of sample applications, controls, and libraries for use with Broadcast Architecture is provided on the compact disc with the Microsoft® Platform Software Development Kit (SDK).

Text files including sources, libraries, and control files needed to create executable versions of the samples reside in the SDKdir\Samples\Graphics\Ba directory. Note that SDKdir in this path represents either the Mssdk directory on the Platform SDK compact disc, or the directory you selected for installing the Platform SDK.

The samples are as follows:

  • Four samples developed in different ways demonstrate how to use the Video control to display video. These samples are located in the UseVideo subdirectory:
    • The Vid_Tune subdirectory contains a Microsoft® Visual Basic® group comprising a Visual Basic control and a Visual Basic project to test the control. The Visual Basic control contains a Video control as a constituent control.
    • The VidCntrl subdirectory contains a Visual Basic project that uses the Video control.
    • The VideoMFC subdirectory contains a Microsoft® Visual C++® project workspace that uses the Video control.
    • The WebTune subdirectory contains a Hypertext Markup Language (HTML) document that Internet Explorer uses to display a Video control.

    For more information on how to run each sample, see the Readme.txt file in the UseVideo subdirectory.

  • Two samples developed in different ways, Load and Download, demonstrate how to write Guide database loaders. The Loader subdirectory contains source code for the Load sample, a simplified loader that gives an unobstructed view of how certain loader functions work. The Download subdirectory contains source code for the Download sample, which shows how to write a full-featured loader. For more information on each sample, see the Readme.txt file in the subdirectory for that sample.
  • The sample application Schsamp.dll is a Microsoft® ActiveX® component that schedules a show reminder. It is located in the subdirectory Schsamp. For information on how to compile and run Schsamp.dll, see the Readme.txt file in that subdirectory.
  • The sample application Lr.exe runs a VCR using a remote control. It is located in the subdirectory Record. For information on how to compile and run Lr.exe, see the Readme.txt file in that subdirectory.
  • The sample MFC application Tvxsamp.exe demonstrates how to connect to and control Microsoft® WebTV® for Windows®. It is located in the subdirectory Tvxsamp. For information on how to compile and run Tvxsamp.exe, see the Readme.txt file in that subdirectory.
  • The sample applications Enhancement Stream Editor and Stream Player create and test an enhancement stream. They demonstrate how an application can use the Stream Compiler object library to implement stream authoring functionality. Both of these samples are located in the subdirectory Enhance\Author. For more information on how to compile and run these samples, see the Editor.txt and Player.txt; for more detailed information on what the samples do, see the Readme.txt file in the Enhance\Author subdirectory.
  • The sample application Validator checks the syntax of an enhancement stream file. If errors are found, Validator displays them to the user. The user can then use Validator to correct the syntax and recheck the file. This sample is located in the Enhance\Validate directory. For more information on how to run and compile this sample, see the Readme.txt file in that directory.
  • The sample stream authoring tool Quizstr.exe generates a custom enhancement stream for a quiz show. It is located in the directory Enhance\Quizstr. For information on how to compile and run Quizstr.exe, see the Readme.txt file in that subdirectory.
  • The sample applications Wsend and Wlisten send and receive multicast data. In addition, Wsend sends data to the Microsoft® Multicast Router using a tunnel. The sample library Brtest includes functions used by Wsend and Wlisten. These samples are located in the subdirectories Brtest, Wsend, and Wlisten. For more information on how to compile and run each sample, see the Readme.txt file in the subdirectory for that sample.


Displaying Video

To present audio and video on a computer display or to manage all the devices associated with video, you can use the Microsoft® ActiveX® control for video in Broadcast Architecture (the Video control, Vid.ocx). You can use the Video control in applications written using Microsoft® Foundation Classes (MFC) or with the Microsoft® Visual Basic® development system. You can also embed the Video control in a World Wide Web page or use it as a constituent control in a control that you create.

If you want, you can create your own television viewing application. Your television viewer might consist of the Video control along with an interface enabling users to select frequently viewed television channels.

The following topics describe in order implementation tasks that are necessary to use the Video control in an application, in another control, or while it is embedded in a container:

  1. Installing the Video Control
  2. Getting Available Devices
  3. Setting Video Input
  4. Setting Video Output
  5. Tuning to a Channel
  6. Sizing the Video Control
  7. Setting Video Priority

The software supporting Broadcast Architecture includes four sample applications developed in different ways to demonstrate how to use the Video control. To locate these samples, see Broadcast Architecture Sample Applications.

For more information about the Video control, how to use it, and the interfaces it supports, see About the Video Control, Using the Video Control, and Video Control Reference.


Installing the Video Control

Before your application can present video and audio on a computer, you must first obtain the Microsoft® ActiveX® control for video (the Video control) and install an instance of the Video control on the application's user interface.

The best way to install the Video control depends on how you develop your application. With the Microsoft® Visual Basic® development system, you obtain the Video control by selecting the Microsoft BPC Video Server and Control module. You locate this module by selecting the Components item from the Project menu of Visual Basic. In the Components dialog box that appears, you find this module in the Controls tab. Selecting this module causes the Video control to appear in the Visual Basic Toolbox as an icon that consists of blue letters that spell out VID. If you place the mouse pointer on this icon for one second or longer, the name of this control appears as BPCVid. After the Video control is in the toolbox, you can install, position, size, and name the instance of the Video control in your application the same way that you perform those operations for any other control.

In applications written using MFC, you install the Video control by inserting Vid Control in your application. You locate the Video control by choosing the menu command Project, Add To Project, Components and Controls in the Microsoft® Visual C++® development system. In the Components and Controls Gallery dialog box that appears, you find the Video control in the Registered ActiveX Controls directory. When you insert the Video control in your application, you must generate the CBPCVid, CBPCDevices, and CBPCDeviceBase classes. You must also include the header files that define those classes in any source files that use them. Inserting the Video control causes it to appear in the Controls box as an icon that consists of blue letters that spell out VID. If you place the mouse pointer on this icon for one second or longer, the name of this control appears as Vid. After the Video control is in the controls box, you can install, position, size, and name the instance of the Video control in your application the same way that you perform those operations for any other control.

To direct a Web browser to embed the Video control, initialize it, and position it in your Web page, you insert an OBJECT tag in your hypertext markup language (HTML) document and supply attribute values that specify the object type, location, initial data, and so on. The following is a description of the necessary attributes for the Video control:

  • The CLASSID attribute is the Globally Unique Identifier (GUID) of the Video control. The Video control's GUID is 31263ec0-2957-11cf-a1e5-00aa9ec79700. This attribute enables the Web browser to obtain the Video control from the registry.
  • The ID attribute is the name of the instance of the Video control.
  • The WIDTH and HEIGHT attributes dictate the dimensions of the Video control.
  • The ALIGN attribute dictates the position of the Video control in the page of the Web browser.

You can use Microsoft ActiveX Control Pad to create an HTML document and embed an instance of the Video control in that document by inserting Vid Control.


Getting Available Devices

Before your application can enable users to run the Microsoft® ActiveX® control for video (the Video control) in all its possible ways, it needs information on which device to use. In many cases, users must select one or more devices to use. For example, your application could provide a user the option to select a video camera, a VCR, or a television tuner as the input device for video. Your application can thus retrieve the list of available devices before it starts presenting video and audio, and potentially it can present a list box of devices to select from. If video and audio are instrinsic to your application's functionality, your application in most cases should retrieve the list of available devices when it starts.

Additionally, your application might need to retrieve (and potentially present to the user) a list of available devices whenever some new video or audio capability is required or desirable.

For your application to retrieve this list, it must first declare and allocate storage for variables of BPCDevices and BPCDeviceBase object types. Your application then assigns the collection of all the available input and output devices to the BPCDevices variable with the BPCVid object's Devices property. Your application next enters a loop to get each BPCDeviceBase object that represents an available device for video. Your application can use the BPCVid object's DeviceCount property to determine the number of times to loop. Your application then obtains a string representing the name of each available video device with the Name property of the BPCDeviceBase object and adds those strings to an array of string elements. When user device selection is required, your application also adds those strings to a list box or combo box on the user interface.

The best way to add initialization functionality to your application depends on how you develop your application. With the Microsoft® Visual Basic® development system, you implement initialization in the Form_Load procedure. With MFC, you implement initialization in the OnInitDialog method of your dialog class. With a Hypertext Markup Language (HTML) document, you implement initialization in the script that runs when a Web browser loads the page.

In this release of Broadcast Architecture, hardware configurations only support sending analog video to the digital VGA display surface of the control itself. Therefore, the Video control cannot set an output device; it can only set which input device to receive video from. If a user's computer has an analog television tuner card installed and your application provides a list of available devices, the friendly name of the WDM stream class minidriver for the tuner device is listed as an input source. WDM here stands for (Microsoft®) Windows® Driver Model.

To locate more information on working with display surfaces, see Further Information on Development Tasks in Broadcast Architecture.


Setting Video Input

Before your application can display video, it must first assign an input device as a source for the video stream. If no user input is required to do so, you application sets the input device from the array of available devices described in Getting Available Devices. Alternatively, users can select the input device through a list on the user interface.

For your application to set an input, it must first declare and allocate storage for variables of BPCDevices and BPCDeviceBase object types. Your application then assigns the collection of all the available input and output devices to the BPCDevices variable with the BPCVid object's Devices property.

Your application next enters a loop to retrieve each BPCDeviceBase object representing an available video device. Your application obtains a string representing the name of each device with the Name property of the BPCDeviceBase object. It then compares the string to the name of the device selected from the list or array. If the string values are the same, your application can assign the selected device as the input source with the Input property of the BPCVid object. Before setting the device as the input source, your application should confirm that the selected device is for video input with the IsInput property of the BPCDeviceBase object.


Setting Video Output

In the future, when hardware that supports additional outputs for video is available, your application will be able to assign an output device to receive the video stream. An application sets the video output the same way as it sets the video input, as described in Setting Video Input, except for the following differences:

  • Your application assigns the selected device to be the output source with the Output property of the BPCVid object.
  • To confirm that a selected device is for video output, your application should use the IsOutput property of the BPCDeviceBase object.

In this release of Broadcast Architecture, hardware configurations only support sending analog video to the digital VGA display surface of the control itself.


Tuning to a Channel

To display video from a broadcast channel specified by the user, your application can do one of two things. It can assign a channel to the device that was set as the input source for video as described in Setting Video Input. Alternatively, your application can tune to a channel in a specific tuning space.

In either case, the result is that a tuning device tunes to the channel and the received video appears on the display surface of the Microsoft® ActiveX® control for video (the Video control). The following topics describe these two ways of tuning to a channel:

  • Setting a Channel Number
  • Tuning to a Channel in a Tuning Space

If the input source is a tuner, you can set the BPCVid object's VideoOn property in your application to either TRUE or FALSE to display video or to stop video from displaying. To stop a tuner from sending video, your application calls the BPCVid object's Close method.

To locate more information on working with display surfaces, see Further Information on Development Tasks in Broadcast Architecture.


Setting a Channel Number

To tune a channel number for a specific tuning device, your application performs the following process. First, it determines if the input source for video is from a tuner with the HasChannel property of the BPCDeviceBase object. If so, your application switches the tuner to the specified channel with the BPCDeviceBase object's Channel property. You can also use the ChannelAvailable method of the BPCDeviceBase object in your application to determine whether a tuner can tune to the specified channel before actually tuning to the channel.


Tuning to a Channel in a Tuning Space

To tune to a channel number within a specific tuning space, such as the tuning space for analog cable TV, your application performs the following process.

First, it must obtain the number that identifies the tuning space. You obtain such a tuning space number from the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\TV Services\Tuning Spaces

To obtain the description of a tuning space in the registry to determine if it is the one you want, click the tuning space number to select it. Details about the tuning space then appear in the right section of the registry's window.

Your application can obtain a number for a specific tuning space by using functions from the Microsoft® Win32® application programming interface (API) to retrieve data from the registry. To do so, your application can open the Tuning Spaces key, enumerate the subkeys of this key, and then retrieve data from the values associated with each subkey until finding a subkey that has data defining the specific tuning space. The subkeys of the Tuning Spaces key are the tuning space numbers.

Once your application has the tuning space number, your application can then determine if the user's computer contains a tuner supporting that tuning space. To do so, your application should call the BPCVid object's TSDeviceCount method and specify the tuning space number. If this method returns a number greater than zero meaning that the specified tuning space has at least one tuner available, your application can then call the BPCVid object's Tune method. When calling Tune, your application should specify the tuning space number, the channel number to tune to, and the default values for the video and audio subchannels. As shown in the video sample applications, the default value for both subchannels is –1, which allows the tuner to choose an appropriate subchannel.

To locate more information on the registry and retrieving data from it, see Further Information on Development Tasks in Broadcast Architecture.


Sizing the Video Control

Because of user interaction, your application might require that the size of the Video control change. Some examples of user interaction that could result in changes to the size of the Video control are:

  • Changing the size of your application resulting in the size of the Video control changing proportionally
  • Action causing the size of the Video control to fill the entire viewing space of your application
  • Action reducing the Video control's size

To change the Video control's size in proportion to a change in your application, you implement a function that responds to your application's resize event. In the resize function, you set the size of the Video control to a fraction of the application's size.

To enable users to fill your application with the Video control or to reduce the Video control's size, you implement functions in your application that respond to specific events of the Video control. To fill your application with the Video control when the user clicks on the Video control, you implement a function that responds to the Video control's Click event. In the click function, you set the width and height of the Video control to the application's width and height. To reduce the Video control's size when the user double-clicks on the Video control, you implement a function that responds to the Video control's DblClick event. In the double-click function, you set the size of the Video control to a fraction of the application's size.


Setting Video Priority

In many cases, your application should retain control of its input device if another application containing an instance of the Microsoft® ActiveX® control for video (Video control) starts. For example, if your application provides the primary method for users to view television, it should retain control. In these cases, you can set the priority for the Video control in your application to a high level. On the other hand, you might not want the Video control in your application to retain control. In that case, you set its priority to a low level.

You can set the priority level of the Video control in your application with the Priority property of the BPCVid object. For more information about priority levels of the Video control, see Device Contention and BPCVid.Priority.


Writing a Custom Guide Database Loader

The Guide database stores information about what television programming is available through Broadcast Architecture applications. The information for the Guide database comes from different sources, such as the Internet and vertical blanking interval (VBI) transmissions. The database is a Microsoft® Jet database that can be accessed using Microsoft® Data Access Objects (DAO). To locate more information on DAO, see Further General Information.

To streamline access to the database, Broadcast Architecture uses loader programs. The two sample applications discussed in the following sections, Load and Download, show how to write custom database loader programs. To locate the source code for these sample applications, see Broadcast Architecture Sample Applications.

These sample loaders are written using Microsoft® Foundation Classes (MFC) and several libraries from Broadcast Architecture. Each sample has the same general structure and shows the important functions of a loader application. The sample called Download (Download.dll) reads television programming information from a text file and adds it to the Guide database. This sample shows how to write a full-featured loader. The sample called Load (Load.dll), a simplified example, gives an unobstructed view of how the loader functions for adding channels and shows to the Guide database work.

The following topics describe, in order, the tasks involved in loading data into the Program Guide:

  1. Getting Data to the Client discusses possible sources of Program Guide data and how to get it to the broadcast client.
  2. Making a Loader DLL describes the required features of a Guide database loader.
  3. Using Guide Data Objects to Access the Database shows how to use functions in Broadcast Architecture to simplify loader development.
  4. Entering Data shows specific examples of how to enter and edit records in the Guide database.
  5. Removing Records Using Special Functions describes how to use special queries in the Guide database to perform housekeeping functions.
  6. Installing and Running Your Loader shows how to use the Loadstub component and the Task Scheduler in the Microsoft® Windows® 98 operating system to run your loader.

For an overview on how to write a custom loader, see Writing a Custom Loader.


Getting Data to the Client

The first step to updating the Guide database is to get information about what television programming is on what channel at what time. The procedure for this depends on the source of the data. For example, if the data is in a file on the Internet, you can send it over the VBI of a predetermined television channel by using Internet channel broadcasting, if the television channel supports this functionality. The user can then subscribe to the appropriate Internet channel, and the file appears in the designated file directory. Then a loader can read the file and transfer the results into the Guide database.

Many other possible sources of data exist, such as e-mail and World Wide Web pages. You can even write a program that associates VCR Plus codes, used with some VCRs to specify channels and times to be recorded, with show names to make your own custom show. In the sample application Load, the data to load the database is hard-coded into the loader. Hard-coding data into the loader means you can see how the loader works without getting bogged down in the details of a particular source. To locate the source code for Load and Download, see Broadcast Architecture Sample Applications.


Making a Loader DLL

A loader is a dynamic-link library (DLL) that can be called by Loadstub.exe, a component that starts loader applications. The prototype for an entry-point function for a loader is:

ExitCodeList APIENTRY
EPG_DBLoad(int &argc, _TCHAR **argv, CdbDBEngine &db
    , PFNFORCEQUIT pfnForceQuit);

The mechanism for passing the specific information that a loader requires is to include the information as command-line arguments to Loadstub.

Loadstub passes the command-line arguments that it does not handle itself to the entry-point function of a loader when that loader is called. These arguments are passed by means of the entry-point function's first two arguments, argc and argv. Any arguments your loader requires can be passed using these arguments. For example, Loadstub can pass the user's zip code to select the channels to load for a given region. For more information on Loadstub and its arguments, see Loadstub.

In addition to such loader-specific arguments, Loadstub can pass a /c argument to request that the loader compact the database, or a /p argument to request a partial database update. For more information on how to handle these arguments, see Removing Records Using Special Functions.

Another command-line argument a user or setup application can specify is /L, which tells the loader about the source of the data. The format of this argument depends on the data source. For example, if the data comes from the Internet, the argument can be the Uniform Resource Locator (URL) of the data source.

The third argument for the entry-point function, db, is a reference to the DAO database engine. This value must be passed to any function that accesses the Guide database. To locate more information on the CdbDBEngine object used in this argument, see Further Information on Development Tasks in Broadcast Architecture. The sample loader saves the value in a member of the application object called m_pDAODB.

The last argument, pfnForceQuit, is a pointer to a function that returns a value that is TRUE if the operating system is trying to shut down the loader, and FALSE otherwise. Your loader should check this function from time to time to see if the loader should shut down. Doing so prevents the operating system from forcing the loader to exit without performing necessary cleanup operations, such as closing databases and releasing system resources.


Using Guide Data Objects to Access the Database

Your loader can access the Guide database directly through the CdbDBEngine variable passed to the loader in its entry-point function, as shown in Making a Loader DLL. However, to avoid having to deal with the details of the database, your loader can use the Broadcast Architecture component library Dbsets.dll. This library provides objects that give access to each of the database tables, which contain the information required to manipulate how shows are displayed in the Program Guide. For more information on this library, see Guide Data Objects.

As an example of how to use Dbsets.dll, see the sample loader Load. The application object in Load includes pointers to each of the objects defined in Dbsets.dll. The Load member function OpenTables initializes these pointers. After calling OpenTables, Load can access any table in the database by using the appropriate object. To locate the source code for Load, see Broadcast Architecture Sample Applications.


Entering Data

The sample loader Load enters data into the database by using the method Handle in its application object. As mentioned in Getting Data to the Client, Load uses hard-coded values. Your loader should replace this function with one that loads the data you require.

Load creates objects, defined in the Dbsets library, for each record to add to the database, then uses the corresponding Guide data object to update the record. This is the recomended approach for manipulating the data in the guide database. Notice that several of the created objects require objects or identifiers from other objects. For example, when adding a channel you must supply the identifier of the station record. This requirement means that you must have a station record before you can create a channel record. The descriptions of the Guide database objects in the Guide Data Objects section indicate which methods require identifiers and which methods supply the required identifier.

Be careful when using dates and times. The database stores times in coordinated universal time (UTC). You must convert this to or from local time when appropriate. You can use the application member variable m_odtsTimeZoneAdjust to make the conversion.

While the Handle method is running, the loader is not receiving system messages.This means that if the system tries to shut down the loader, the loader is not informed and thus cannot terminate gracefully. Loading may stop while files are open or other system resources are in use. Such termination may have disastrous results.

To prevent this problem, your loader should call the function that pfnForceQuit points to within long processing loops to see if a shutdown message is in the message queue. If this function returns TRUE, your loader should perform whatever processing is required to safely terminate Handle. In Load and Download, the address for the function pfnForceQuit points to is stored in the application object's member variable m_pfnForceQuit.


Removing Records Using Special Functions

Your loader can use special functions to remove unused or out-of-date data records from the Guide database. Removing excess records is important to keep the database from growing too large. These special functions are stored in the database as queries. For information about specific queries, see Guide Database Query Reference.

As an example of the use of special functions, see the sample loader Load. Load runs queries by calling the application object's member function ExecuteActionQuery. The application object's ClearOldEntries member function uses these queries to remove excess records from the database. Removing excess records is important for keeping the database from growing too large.


Installing and Running Your Loader

In order to run your loader, you must make sure the Loadstub component (Loadstub.exe) is informed about it. You do this by adding an entry to the registry and causing Task Scheduler to pass this entry to Loadstub when Loadstub calls your loader.

Loadstub.exe searches for your loader's entry in the following registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\TV Services\Guide\Loaders.

The name of the entry should be the globally unique identifier (GUID) for the loader, enclosed within curly braces ({}). If you have installed Microsoft® WebTV® for Windows®, you can use the entry for the default loader as an example of such an entry. You must add a name string value to the new entry that gives the complete path to your loader. You can also include any parameters your loader requires in this entry; for more information on what is required in your loader's registry entry, see Loaders Subkey. When Loadstub is run, Loadstub adds values to the registry entry for your loader's last attempted run time, last completed run time, and last completed result.

Once the registry contains the new entry, you can run your loader with the following command line:

loadstub /L:{00000000-0000-0000-0000-000000000000}

where the number between the curly braces is the GUID for your loader.

When you have verified that your loader is working properly, you can set it to run at regular intervals. You do so by adding the preceding command line to the scheduled tasks list in Task Scheduler.


Scheduling Show Reminders

A show reminder is a special-purpose task scheduled in Task Scheduler, a feature of the Microsoft® Windows® 98 operating system. When a show reminder runs, it calls an application that displays a message informing the user that a television show is about to begin. Microsoft WebTV for Windows is typically used to display show reminders, but you can also write custom display applications to display your show reminders. For example, your custom application can play music or animate the show reminder message.

Users can set show reminders in the Microsoft® WebTV® for Windows user interface. In addition, Broadcast Architecture exposes several interfaces that you can use to programmatically set, modify, or delete show reminders. For example, you can create a control for an enhancement page that automatically schedules a reminder for next week's episode of a particular television program.

The following topics describe in order the basic tasks involved in creating a show reminder:

  1. Getting and Working with Episode Data
  2. Setting a Show Reminder
  3. Setting a Record Reminder
  4. Setting a Reminder That Appears in WebTV for Windows
  5. Displaying a Show Reminder
  6. Deleting a Show Reminder

The software supporting Broadcast Architecture includes the sample application Schsamp.dll, a Microsoft® ActiveX® component that schedules a show reminder. To locate Schsamp.dll, see Broadcast Architecture Sample Applications.

To locate more information about Task Scheduler, see Further General Information.


Getting and Working with Episode Data

Before you can set a show reminder, your application must obtain information about the episode or episodes for which you are scheduling the reminder. Obtaining information can be as simple as using known episode data hard-coded into a script or application, or as complicated as implementing an episode object in your application and then querying the Guide database to populate the object's properties.

How you handle episode data depends largely on your application and on which Broadcast Architecture interfaces it calls to set show reminders. For example, if you are creating a show reminder from a temporary enhancement page, hard-coding the data into the Microsoft® Visual Basic® Scripting Edition (VBScript) script that sets the reminder may be sufficient. This is because in this case, the application only needs to set a reminder for a specific show, the interactive show, not for shows in general.

However, if you are calling ITVViewer::SetReminder method to set a show reminder, you must pass in a pointer to an IEPGEpisode interface. (SetReminder is implemented by ITVViewer, the dispatch interface for Microsoft® WebTV® for Windows®.) Thus, your application must implement IEPGEpisode and populate that interface's property values with the data for the episode in question. This population can be done using data from the Guide database.

For more information, see the following topics:

  • Episode Data Format, which describes the format of the episode data you must specify when setting a reminder.
  • Retrieving Episode Data from the Guide Database, which explains ways to retrieve data from the Guide database.


Episode Data Format

The amount and type of episode data that your application must provide varies depending on which of the reminder-setting methods described in Setting a Show Reminder you use, either calling the SetReminder method of ITVViewer, or by adding a reminder to the ScheduledItems collection of Television System Services (TSS).

If you are using the IScheduledItems::Add method to schedule a show reminder you must provide a fully specified show reference. For more information, see Show Reference Format.

If you are using ITVViewer::SetReminder to schedule a show reminder, your application must implement the IEPGEpisode interface and populate its property values with data about the episode for which you are setting a reminder. For more information, see IEPGEpisode.


Retrieving Episode Data from the Guide Database

The Guide database stores Program Guide information about future shows. You can query this database for information about an episode.

For example, when gathering data about an episode for a show reminder, your application might query the Guide database for episode records with a specific title and start date. Once you find a matching record in the database, you can fill in the rest of the episode information for the reminder, such as channel, network, and ending time, from the record's fields.

To enable applications to retrieve or set episode and other records and fields in the Guide database, Broadcast Architecture provides the Guide data objects. These objects wrap the Data Access Objects (DAO) code necessary to access the Guide database's records and fields. Specifically, you can use the CEpisodeTRecordset object to select and create episode records in the Guide database. The CEpisodeTRecordset contains a collection of CEpisodeT objects, each of which wraps the field information about an individual episode record.

For more information, see the following topics:

  • Guide Data Objects.
  • Using Guide Data Objects.
  • Episode Table in the Guide Database Schema. The Episode Table contains episode information.

To locate information on DAO, see Further General Information.


Setting a Show Reminder

A show reminder is a task set in Task Scheduler that at a specific time starts an application to remind users a show is about to begin. Broadcast Architecture provides two technologies that you can use to set a show reminder, Microsoft WebTV for Windows and Television System Services (TSS).

The process of setting a reminder that appears in the Microsoft® WebTV® for Windows® user interface is identical to the process that occurs when a user sets a reminder by clicking a Remind button in the Program Guide user interface displayed by WebTV for Windows. To set such a show reminder, your application calls the ITVViewer dispatch interface exposed by WebTV for Windows. A show reminder set using this interface is visible from the WebTV for Windows search page. Such a reminder also causes an icon indicating that the reminder has been set to appear in the Program Guide.

The disadvantage to using WebTV for Windows to set a reminder is that the programming is more complex. Your application must ensure that WebTV for Windows is currently running, get a reference to ITVViewer, and implement the IEPGEpisode interface. For more information on this process, see Using ITVViewer to Schedule a Show Reminder.

If your application is relatively simple, for example a Microsoft® ActiveX® control or Java applet on an enhancement page, you may find it more convenient to use TSS to schedule your show reminders. If you want TSS-set reminders to appear in the WebTV for Windows user interface as icons or on the search page, you must set reminders that meet the standards described in Setting a Reminder That Appears in WebTV for Windows. WebTV for Windows only displays reminders set by WebTV for Windows in these fashions.

You can, however, use WebTV for Windows to display a message for a TSS-set reminder to the user, regardless of whether the TSS-set show reminders meet these standards. In other words, if you specify Tvx.exe in the command line for the reminder, WebTV for Windows will always attempt to display a reminder message when the reminder runs.

For more information about setting a show reminder using TSS, see Using IScheduledItems to Schedule a Show Reminder and Setting a Reminder That Appears in WebTV for Windows.


Setting a Record Reminder

A record reminder is a task set in Task Scheduler that at a specific time starts an application that controls a VCR or similiar device to record a show. Record reminders are set in the same manner as show reminders save for a few additional steps. These are listed below:

  1. Instead of using Tvx.exe to display the reminder, you should specify either a custom application you have created to handle record reminders or Tvxwakeup.exe.
  2. If the recording process has helper applications, such as an application to turn a VCR on and off, the location and filenames of the helper applications should be listed in the StartRecordingApp and/or EndRecordingApp values in the registry. These values appear under this registry key:

    HKLM\Software\Microsoft\TV Services\Explorer\

    StartRecordingApp specifies the application that should be run before recording starts, and EndRecordingApp specifies the application that should be run after recording is complete. These values may specify the same application if it implements both starting and ending functionality.

    Tvwakeup.exe automatically looks for these registry keys. If they exist, Tvwakeup.exe runs the helper applications at the appropriate times. If you are using a custom application to handle record reminders, it should implement this functionality.

    For more information about the helper applications specfied in StartRecordingApp and EndRecordingApp, see Record Reminder Helper Applications.

  3. Set the TASK_FLAG_SYSTEM_REQUIRED flag for the reminder. This can be done using the Task Scheduler. This flag enables applications to tune the television tuner even if the system is sleeping. Note that this does not wake up the display if the system is sleeping, so that recording can be done quietly.

    Note The TASK_FLAG_SYSTEM_REQUIRED flag should not be set for standard show reminders. Version 1.0 of Broadcast Architecture does not support standard show reminders that go off while the system is sleeping.


Record Reminder Helper Applications

Record reminder helper applications are run before and/or after a show is recorded. These applications typically implement functionality to control the recording device, such as starting and stopping a VCR or DVD-recorder.

The helper applications can be started automatically at the correct times if you store the location and filename of the record applications in the StartRecordApp and EndRecordApp values of the HKLM\Software\Microsoft\TV Services\Explorer\ registry key. Applications that handle the record reminder check for these values, and if found, run the specified helper applications. The helper application specified in StartRecordApp is run prior to the start of the show that is being recorded. The application listed in EndRecordApp is run after the show is concluded.

Typically, the application used to handle record reminders and start the helper applications is Tvwakeup.exe. In order for your helper applications to be compatible with Tvwakeup.exe, it should support the following command-line syntax.

<application> -f <function> -d <duration> -c <channel> -s <tuning_space> -t <title> -r <show_reference>

Where

<application>
Is the path and filename of the application specified in either StartRecordingApp or EndRecordingApp. If recording is starting this value is the application in StartRecordingApp, if recording is ending, this value is the application in EndRecordingApp.
<function>
Indicates whether recording is starting or ending. If recording is starting this value is "start", if recording is ending, this value is "end".
<duration>
Is the duration, in minutes, of the show being recorded. The call to the end recording application always specifies a duration of 0.
<channel>
Is the channel number.
<tuning_space>
Specifies the name of the tuning space. For example, "Cable"
<title>
Specifies the title of the show being recorded.
<show_reference>
The show reference as specified in the record reminder.

As an example of how the Broadcast Architecure client uses the helper applications, consider the case where Tvwakeup.exe is used to handle a record reminder. The helper applications specified in this example are StartRec.exe and EndRec.exe.

  • Two minutes before the show begins, Tvwakeup.exe checks for the StartRecordingApp value, and if found, starts that application using command-line syntax such as the following:
    C:\Startrec.exe -f "start" -d 30 -c 6 -s "Cable" -t "InterNight
-r "1997/11/6!0/0/0!23:00!0!0!0!0!0!0!0!0!0!''!'MSNBC'!'Cable'!2!InterNight
  • Two minutes after the show ends, Tvwakeup.exe checks for the EndRecordingApp value, and if found, starts that application using command-line syntax such as the following:
    C:\Endrec.exe -f "end" -d 0 -c 6 -s "Cable" -t "InterNight
-r "1997/11/6!0/0/0!23:00!0!0!0!0!0!0!0!0!0!''!'MSNBC'!'Cable'!2!InterNight

To view an example of an record reminder helper application see, Recording Shows.


Setting a Reminder That Appears in WebTV for Windows

Microsoft WebTV for Windows provides a user interface that displays a information about currently set reminders. These reminders appear when the user opens the search page in Microsoft® WebTV® for Windows® and clicks My Reminders in the list of categories. In addition, a reminder icon appears in the Program Summary panel when the user clicks an episode in the Program Guide for which a reminder is set.

Users can use the MyReminders list to view, edit, or delete show reminders. The reccommended way to set reminders that appear in the WebTV for Windows user interface is to use ITVViewer::SetReminder.

However, you can use the IScheduledItems::Add method of TSS to set reminders that appear in WebTV for Windows if the reminders meet the following standards:

  • Ensure that the show reference contains the start date, channel number, tuning space, station call letters and title.
  • Set the application flag to tvviewer. For more information, see Using IScheduledItems to Schedule a Show Reminder.
  • Only set one-time, weekly, or daily reminders.
  • If it is a record reminder, follow the procedures described in Setting a Record Reminder.
  • Limit the number of reminders you add. The reminder list displayed by WebTV for Windows has a limit of 50 reminders.
  • Do not add duplicate reminders that specify the same show reference.
  • Set the reminder to run no more than 30 minutes before the show starts.


Displaying a Show Reminder

A show reminder is simply a task set in Task Scheduler. As such, it does not provide a user interface. When it runs, it calls a display application, such as Microsoft WebTV for Windows, to parse its show reference and display a reminder message to the user. When that display application is Microsoft® WebTV® for Windows®, the application also offers the user the opportunity to tune immediately to the channel on which the episode is broadcast. Your application specifies which display application to use when it sets the reminder.

If your application requires a custom reminder dialog box or special functionality, you can write a custom display application to handle show reminders. For example, you can write an application that displays an image of the show's cast and plays the theme song when it reminds the user the show is about to begin.

To be compatible with Broadcast Architecture show reminders, a custom display application should accept a show reference as input. It should then parse the show reference to obtain the episode data and display the reminder to the user. For more information on show references, see Show Reference Format.

To locate more information on Task Scheduler, see Further General Information.


Deleting a Show Reminder

Show reminders are deleted during the course of successful completion. When a show reminder runs, unless it is a recurring show reminder, the Task Scheduler deletes the reminder from the Tasks folder.

In addition, show reminders can also be deleted by the following:

  • You can delete a show reminder programmatically using either ITVViewer::DeleteReminder or by removing the item corresponding to the reminder from the IScheduledItems collection.
  • Invalid show reminders, those having an invalid show reference or incorrect command line syntax, are deleted automatically by Microsoft® WebTV® for Windows®.
  • If the show reminder is one that appears in the WebTV for Windows reminders list, you can use the WebTV for Windows user interface to delete a show reminder.
  • You can delete a show reminder by opening the Tasks folder, typically C:\Windows\Tasks, right-clicking the task for the reminder, and selecting Delete.

Note Reminders are scheduled as hidden tasks. Therefore, they do not appear in the Tasks folder unless you have set your viewing options to show hidden files. To do this, go to the Tasks directory, typically C:\Windows\Tasks, and type attrib –h *.*.


Recording Shows

One of the features of Microsoft WebTV for Windows is the ability to schedule the recording of future shows that a user selects from the Program Guide. If a user has set a reminder within Microsoft® WebTV® for Windows® to automatically record a show, WebTV for Windows sets a task in Task Scheduler that at a specific time starts helper applications. At the specified time, these helper applications can start and then run a VCR or similar device to record a selected show. You must create one or more helper applications to tune a VCR and start and stop recording a show and set values for those applications in the registry. Although you can create separate applications that start and stop recording a show, it is possible to write one application to do both. In addition, the reminder for recording in WebTV for Windows also requires a specific helper application to wake up your other helper applications. Unless you intend to create and set in the registry your own wake-up application, the record reminder uses the Tvwakeup.exe application, a component of Broadcast Architecture, as the default. The Tvwakeup.exe application starts your other helper applications with a specific command-line syntax. To use Tvwakeup.exe, you must enable your helper applications to process the specific arguments of this syntax.

Although some VCRs might have the ability to be controlled by a computer from an RS-232 connection, most VCRs must be controlled by a remote control connected to a computer's serial port.

The following topics describe in order the basic implementation tasks involved in creating a command-line application that Broadcast Architecture uses to automatically record shows:

  1. Processing Arguments of the Command Line
  2. Connecting to the Remote Control
  3. Specifying Key Codes
  4. Sending Commands to the Remote Control
  5. Disconnecting from the Remote Control
  6. Registering Your Application with TV Services

The software supporting Broadcast Architecture includes the sample application Ir.exe, a command-line application that controls a VCR through an infrared remote control. To locate Ir.exe, see Broadcast Architecture Sample Applications.

To locate more information about setting a reminder for recording shows and the command-line syntax that Tvwakeup.exe starts applications with, see Setting a Record Reminder. To locate more information about the registry entries in which to store the path and file name of your helper applications, see Registry Entries for WebTV for Windows.


Processing Arguments of the Command Line

One of the first operations your application must perform is to parse the arguments of the command line obtained from Tvwakeup.exe or from your own wake-up application. Your application requires parsing these arguments to process them. The best way to parse these arguments is when your application initializes. If you write your application in Microsoft® Foundation Classes (MFC), you should create a command-line class that inherits from the CCommandLineInfo class and override the ParseParam method. During your application's InitInstance method, your application should create an instance of the command-line object. Your application should then call the ParseCommandLine method of the CWinApp class from which your application inherits and pass the command-line object. The ParseCommandLine method then parses and passes each argument in the command line to the ParseParam method that you implement. After ParseParam fills the command-line object, your application passes the command-line object to the ProcessShellCommand method of the CWinApp class. ProcessShellCommand then handles the command-line arguments and flags to perform the indicated operation.

The ParseParam method that you implement should evaluate the arguments of the command line and process them according to whether they are specific flags or functions or the final argument of the command line. Your ParseParam method should create static variables that will store the most recently passed flag argument and a boolean value indicating whether or not ParseCommandLine passed the command to begin recording. If your ParseParam method receives an argument and determines that the static flag variable holds a function flag, ParseParam should evaluate the argument according to the operation specified. If the argument specifies to start recording, ParseParam should set the static boolean value for recording. If the argument specifies to end recording, ParseParam should send a command to stop recording. If your ParseParam method receives an argument and determines that the static flag variable holds a channel flag, ParseParam should evaluate the argument and send commands to the remote control to tune the VCR. If your ParseParam method determines that it received the final argument and that its static boolean value was set for recording, ParseParam should send a command to start recording.


Connecting to the Remote Control

Before your application can start sending commands to the remote control, your application must first open a connection for writing to the serial port of the computer connected to the remote control. To open a connection for writing and obtain the device handle, your application should call the CreateFile function, part of the Microsoft® Win32® application programming interface (API), and pass the name of the port such as COM1 along with the GENERIC_WRITE, OPEN_EXISTING, and FILE_ATTRIBUTE_NORMAL flags. Because your application should only require sending a sequence of commands that consists of one or two one-byte values at a time, it should not require passing the FILE_FLAG_OVERLAPPED flag. This file-attribute flag specifies an asynchronous transfer of data for operations that take a significant amount of time to process.

After opening the connection, your application should configure the settings of the serial port device according to the parameters of the remote control to ensure the two devices follow the same protocol and communicate properly. To configure these settings, your application should first call the Win32 GetCommState function and retrieve the device-control block (DCB) structure for the serial device. Next, your application should assign the remote control's parameters to this DCB structure such as the baud and the number of data bits per byte. Finally, your application should call the Win32 SetCommState function and pass this reassigned DCB structure to configure the serial port device.

After the connection to the remote control is open and configured, your application should send a sequence of commands to the remote control that set the remote control in automatic mode. Your application should also set a flag that indicates a connection to a serial port is open and the remote control is in automatic mode.


Specifying Key Codes

To enable your application to send command sequences that perform specific VCR operations, you must define a list of key codes in your application that the remote control recognizes. Key codes are one-byte values that represent either operations that a VCR performs or numbers from zero to nine. The necessary key codes for operations you must define are the ones that cause the VCR to start and stop recording. Your application uses the key codes that represent numbers from zero to nine to tune a VCR to a specific channel. Some remote controls might require command sequences that put the remote controls in either automatic or manual mode.


Sending Commands to the Remote Control

Once your application has opened and configured a connection to the remote control and specified the relevant key codes for the remote control, your application can begin to send command sequences that will perform specific VCR operations. Sending command sequences consists of separately sending one or more one-byte values that either modifies the remote control or causes the VCR to perform an operation. Before sending a command, your application should first determine that it previously opened a connection to a serial port and put the remote control in automatic mode. If either one of these conditions are not met, your application will not be able to send commands that operate the VCR. Next, your application should create a pointer to a buffer and fill that buffer with the one-byte value that your application requires sending. Finally, to send the command, your application should call the WriteFile function, part of the Microsoft® Win32® application programming interface (API), and pass the handle to the serial port to be written to along with the buffer containing the one-byte value.

When your application sends a start or stop recording command, your application only requires sending a single one-byte value. When your application requires tuning the VCR to a specific channel, your application must send two or more one-byte number values that represent the channel to tune. If the channel specified in the command line is a number less than ten, the first one-byte number value your application should send is the one that represents a zero.


Disconnecting from the Remote Control

To enable users to again manually operate the remote control, your application should send a command to the remote control that puts the remote control in manual mode. Once the remote control is in manual mode, your application no longer requires a connection to the serial port connected to the remote control. To close the serial port connection, your application should call the CloseHandle function, part of the Microsoft® Win32® application programming interface (API), and pass the handle to the opened serial port. Your application should also reset the connection flag to indicate the connection to the serial port is closed and the remote control is in manual mode.


Registering Your Application with TV Services

The reminder for recording in Microsoft WebTV for Windows checks for a helper application in the registry to start your applications for recording shows. If you do not create and set in the registry this helper application, the record reminder uses the Tvwakeup.exe application, a component of Broadcast Architecture. The Tvwakeup.exe application checks for your recording applications in the StartRecordingApp and EndRecordingApp values in the registry. These values should appear under the following registry key:

HKLM\SOFTWARE\Microsoft\TV Services\Explorer\

Your applications must set these registry values with strings that contain the paths and filenames to your applications. If these registry values do not already exist, your applications also create them. If you only write one application that both starts and stops recording a show, your single application must set these registry values with the same string that contains the path and filename to your single application.

Your application can create and set values in the Explorer key by using functions that are part of the Microsoft® Win32® application programming interface (API) to write data to the registry. To do so, your application should open the Explorer key and associate the StartRecordingApp and EndRecordingApp values and their string data with this key.

To locate more information on the registry and writing data to it, see Further Information on Development Tasks in Broadcast Architecture.


Creating Controls for WebTV for Windows

Microsoft® WebTV® for Windows, a component of the Microsoft® Windows® 98 operating system, is the user interface for Broadcast Architecture. WebTV for Windows hosts several controls, such as Internet Explorer and the Microsoft® ActiveX® control for video (the Video control), that it uses to present data such as live video, Program Guide information, and enhancements.

You can extend the Broadcast Architecture user interface by writing custom controls that are hosted by WebTV for Windows. Because Broadcast Architecture uses Hypertext Markup Language (HTML) for its user interface, writing a control for WebTV for Windows is as simple as writing an signed ActiveX control.

However, you need not stop there. WebTV for Windows exposes COM interfaces that enable your control to interact with it. You can query WebTV for Windows about its state, programmatically control it, and receive event notifications from it. You call the WebTV for Windows interfaces from any programming language that supports COM and the GetActiveObject Automation function.

For example, you can write a control that queries the state of WebTV for Windows to monitor a user's viewing habits. This information might be used locally to build a user profile and then to recommend future broadcasts that the user might enjoy. The information might also be transmitted through the back channel to advertisers and broadcast content providers, to enable them to compile information about which episodes are most successful.

The following topics describe tasks your WebTV for Windows control can implement:

  • Connecting to WebTV for Windows
  • Controlling WebTV for Windows
  • Receiving Events from WebTV for Windows

The software supporting Broadcast Architecture includes two sample applications that work with WebTV for Windows. To locate these samples, see Broadcast Architecture Sample Applications.

Note that all ActiveX controls hosted by WebTV for Windows must be signed. Otherwise the control is not displayed or run by WebTV for Windows. This additional security is to prevent unauthorized controls from being downloaded and run as enhancements. To locate information on how to sign an ActiveX control, see Further Information on Development Tasks in Broadcast Architecture.

For more information about WebTV for Windows and the interfaces its exposes, see WebTV for Windows and the ITVViewer and ITVControl interfaces.

Note WebTV for Windows controls that need to access information from the Guide database should link to the static library, dbsetst.lib, instead of dbsets.dll. This is because dbsets.dll is single-threaded and may already be in use by a loader when your application runs.


Connecting to WebTV for Windows

Before your control can program Microsoft® WebTV® for Windows® or receive events from it, your control must connect to WebTV for Windows. It does so by calling the GetActiveObject Automation function.

Typically, a control calls GetActiveObject during its initialization. Connecting to WebTV for Windows when the control first starts ensures that the control has a connection before it tries to access WebTV for Windows. Obtaining a connection before you access WebTV for Windows is important because if a connection cannot be obtained, attempting to call the methods of ITVViewer will return an error. For example if your control cannot connect to WebTV for Windows, because WebTV for Windows is not currently running, the control can gracefully exit or otherwise handle the error.

For a detailed description of how to connect to WebTV for Windows, see Getting a Pointer to WebTV for Windows. To locate more information about GetActiveObject, see Further Information on Development Tasks in Broadcast Architecture.


Controlling WebTV for Windows

Once your control has obtained a reference to Microsoft® WebTV® for Windows®, as described in Connecting to WebTV for Windows, the control can call the methods WebTV for Windows exposes to programmatically control WebTV for Windows. For example, a channel-surfing control might automatically retune WebTV for Windows to a new channel every three minutes.

WebTV for Windows also provides methods that your control can call to query the state of WebTV for Windows. For example, you can query whether WebTV for Windows is currently displaying closed caption information.

For more information about the methods exposed by WebTV for Windows, see ITVViewer.

For examples of tasks your control can perform using WebTV for Windows, see:

  • Tuning WebTV for Windows
  • Using ITVViewer to Schedule a Show Reminder


Receiving Events from WebTV for Windows

Microsoft® WebTV® for Windows® sends event notifications for such events as tuning to a new channel and navigating to a new enhancement page. Your control receives notification of WebTV for Windows events by doing the following:

  1. Implementing the ITVControl interface.
  2. Obtaining a reference to WebTV for Windows as described in Connecting to WebTV for Windows. Your control must obtain this reference before it can call the methods exposed by ITVViewer or register an ITVControl notification sink.
  3. Registering its implementation of ITVControl as a notification sink with WebTV for Windows. This enables your control to receive WebTV for Windows event notifications.

For a detailed description of how this is done, see Registering an ITVControl Sink.

Note Currently, WebTV for Windows only sends notifications to applications running in the same process as WebTV for Windows. An example of such an application is a Microsoft® ActiveX® control or component called from an enhancement page that is currently being displayed by WebTV for Windows.


Building Enhancement Authoring Tools

An enhancement stream is a script that synchronizes enhancements with video. The following topics are intended for independent software vendors (ISVs) and tools vendors who want to develop enhancement authoring tools for users who produce interactive video, such as a video production company.

The primary function of an enhancement stream authoring tool is to produce valid Enhancement Stream language statements that correctly display the interactive show. You can also incorporate functionality to test the enhancement stream and transmit it to broadcast clients.

Because the Enhancement Stream language is a text-based syntax, an authoring tool can be a simple text editor. This, however, requires the user to be fluent in the Enhancement Stream language and to validate the syntax themselves. Many users prefer to use a robust editor that automatically generates and validates the enhancement stream syntax based on their directions.

The following topics assume a working knowledge of interactive shows and enhancement stream. For general information about enhancements, see Video Enhancements.


Stream Authoring Tool Strategies

The form and function of the enhancement stream authoring tool you create depends largely on your user's needs. The following topics describe some common authoring scenarios and the types of tools you can create to serve them.

  • Generic Stream Authoring Tools, which describes general purpose stream authoring tools.
  • Custom Stream Authoring Tools, which describes stream authoring tools customized for a particular enhancement format.
  • Live Stream Authoring Tools, which describes authoring tools designed to produce enhancements on the fly for live-broadcast shows


Generic Stream Authoring Tools

Generic stream authoring tools offer the widest range of stream authoring functionality. In effect, such a tool attempts to meet the needs of all users. An apt analogy to a generic stream authoring tool is a full-featured word processor application.

The drawback of a generic stream authoring tool is its complexity. This slows development and increases the amount of time it takes users to learn the tool. A full-featured stream authoring tool can be overwhelming to a user who simply needs to make small changes to a stream.

If your users are developing enhancements for a wide variety of shows, each with different enhancement formats and requirements, producing a full-featured authoring tool may be your best option. On the other hand, if users are producing enhancements for a single show that employs a standard template they may be better served by a custom stream authoring tool.

The software supporting Broadcast Architecture includes two generic stream authoring tools, Enhancement Stream Editor and Stream Player, which edit and play a generic enhancement stream. To locate these sample tools, see Broadcast Architecture Sample Applications.


Custom Stream Authoring Tools

Custom stream authoring tools are used to generate a stream for shows that use a standard enhancement template. For example, a weekly quiz show might have an enhancement that displays a "play at home" version of the show. The format of the enhancement would be the same each week, with only the question data changing.

For an authoring scenario where most of the enhancement stream is the same from week to week, you could create a tool to automatically generate the components of the enhancement stream that do not change, and enable the user to modify the components that do change. In the preceding example this would be the question content. Streamlining the tool simplifies the authoring process for the user.

The drawback of a custom stream authoring tool is its inflexibility. If the show's enhancements change, the tool must be rewritten.

The software supporting Broadcast Architecture includes a sample custom stream authoring tool, Quizstr.exe, which generated an enhancement stream for a quiz show. To locate Quizstr.exe, see Broadcast Architecture Sample Applications.


Live Stream Authoring Tools

Live stream authoring tools address the needs of users to develop streams "on the fly." For example, a live news show might need the flexibility to modify its enhancements to match late-breaking news items.

When enhancements are added to the show as it is broadcast, there is little time to correct any authoring mistakes. As a consequence, a live-broadcast stream authoring tool should provide a simple and robust user interface. Wherever possible, the tool should automate the stream authoring process and attempt to correct any problems that arise. For example, a live stream authoring tool might automatically find and transmit dependency files for each enhancement page the user transmits.

Other features that are useful for a live stream authoring tool are a dynamic time line that indicates the seconds remaining before a particular enhancement is broadcast, a list of enhancements previously broadcast, and a list of enhancements that are waiting to be broadcast.


Tools for Developing Authoring Tools

Broadcast Architecture provides several tools to assist you in writing enhancement stream authoring tools.

  • The stream compiler objects implement functionality you can use to create stream authoring tools. They wrap the elements of Enhancement Stream language to make it programmable and provide utilities such as syntax validation and time conversion. The stream compiler objects are Microsoft® ActiveX® objects and so can be used from any programming language, including the Microsoft® Visual Basic® development system, Java, C++, and HTML scripting languages. For more information, see Using the Stream Compiler Objects.
  • The enhancement sender object transmits an enhancement stream to broadcast clients over a Microsoft Multicast Router. Like the enhancement stream objects, it is also an ActiveX object. For more information, see Broadcasting an Enhancement.
  • The Enhancement Stream Editor, Enhancement Player, and QuizStr are working examples of authoring tools written using the stream compiler objects. These complete applications illustrate much of the authoring tool functionality described in the following topics. To locate these sample applications, see Broadcast Architecture Sample Applications.


Characteristics of a Well-Formed Enhancement Stream

Whatever type of authoring tool you create, the result should be a well-formed stream that transmits enhancements to the client efficiently and robustly. This topic describes guidelines that your authoring tool can follow to create well-formed enhancement streams.

One of the greatest challenges of any enhancement stream is to handle the case where a viewer tunes into a show in the middle of a broadcast. Because viewers often switch channels or "channel-surf," you cannot assume that broadcast clients will receive an entire stream. To handle this, a well-formed stream repeats events. For example, if the client misses the first occurrence of an announcement or trigger, it can receive the second, third, or fourth occurrence.

A related concern is ensuring that the client receives enhancements with all their dependency files. For example, if an enhancement displays three images, the client must receive all three images or the enhancement will appear broken when it is displayed. You can ensure that dependencies are transmitted with their parent files by specifying EnhEvent.onefile as True for download events. When onefile is True, the stream compiler automatically packages the file and its dependencies into a cabinet file for transmission.

You can also package files into cabinet files explicitly using the EnhCab object provided by the ipenhsnd Type Library. Note that if you use EnhCab to package files, you must add a trigger event to the stream to unpackage the cabinet. If you use onefile, this is done for you.

To handle these and other challenges, a well-formed stream has the following attributes:

  • A single announcement that is repeated as often as possible.
  • A single data trigger that is repeated as often as possible.
  • All navigation targets, items that can be named in the [targ: ] attribute of a Nav trigger, are part of the enhancement base page.
  • Files are transmitted with their dependencies, packaged together into a cabinet file.

To view an example of a well-formed enhancement stream, see Outline of a Typical Enhancement Stream.


Outline of a Typical Enhancement Stream

The following outline is an example of a "typical" enhancement stream. The enhancement stream for a any particular show may vary. In the following, a typical enhancement stream is defined as a stream that is well-formed, and which contains one or more base pages.

  1. Announce the enhanced show repeatedly
  2. Trigger data reception repeatedly
  3. Transmit enhancement files repeatedly
  4. Send other triggers as needed.

The following topics describe the preceding steps in greater detail and provide example stream language statements for each step.

Announce the show repeatedly, either:

  • Before the show, as a future announcement
    -00:30:00.00 announce "MyFuture.ann" repeat 180 until 00:00:00.00;
  • During the show, as a current announcement
    00:00:10.00 announce "MyCurrent.ann" repeat 180;
  • Both before and during the show. (This is the most robust method.)
    -00:30:00.00 announce "MyFuture.ann" repeat 180 until 00:00:00.00;
00:00:10.00 announce "MyCurrent.ann" repeat 180;

Trigger data reception repeatedly, by sending a Data trigger. This enables the client to receive enhancement files.

00:00:20.00 trigger (1 "<FTS> 125.354.23.11:190&MyShow") repeat 180;

Using the same repetition interval for both the announcement and data trigger keeps the two events consistently linked.

Transmit enhancement files repeatedly, using cabinet files to ensure that all dependencies arrive with the files. You can do this either by:

  • Using onefile, to automatically create the cabinet file.
    00:00:30.00 trigger(2 "<EnhPage.htm>") onefile repeat 270;
  • Transmitting a cabinet file explicitly.
    before 00:00:30.00-10 EnhCab.cab repeat 270;
00:00:30.00-5 trigger(1 "<CAB> [bpc://MyShow/EnhCab.cab]") repeat 270;
00:00:30.00 trigger(3 "<EnhPage.htm>") only repeat 270;

Send other triggers as needed throughout the show, repeating them as often as practical. Examples of additional triggers are: Nav triggers, script triggers, user triggers, etc.

00:01:00.00 trigger (4 "<JScript> alert(\'Thanks for tuning in!\')");
00:02:00.00 trigger ("3001 Q:What is the square root of 25?_A:5") repeat 30 until 00:10:05.00;
00:03:00.0 trigger(3 "<MyLeftPage.htm>[targ:LeftSide]") onefile repeat 90;


Authoring an Enhancement Stream

The functionality and form of the stream authoring tool depends on your user's needs. For example, novice users might prefer a tool that automatically generates an enhancement stream from a wizard, whereas advanced users might require an editor that enables them to directly edit the stream.

Although you have great flexibility in how you write and design your authoring tool, there are certain common steps to creating, testing, and transmitting an enhancement stream.

The following topics describe, in order, the tasks involved in authoring an enhancement stream:

  1. Create a new enhancement stream or open an existing stream.
  2. Add events to the stream.
  3. Create announcement files
  4. Allocate available bandwidth.
  5. Edit and delete events in the stream.
  6. Validate the syntax of the stream language statements.
  7. Convert the stream to low-level syntax.
  8. Save the stream to disk.
  9. Test the stream.
  10. Transmit the stream.

Note that the last two steps are not strictly part of an enhancement stream editor. They are, however, necessary functionality for your user. You can implement these tasks into a stream editing tool or a separate application.


Create or Open an Enhancement Stream

The first step of authoring an enhancement stream is to create a new stream or open a pre-existing stream file. Your enhancement authoring tool should provide means for the user to open and create enhancement streams.

If you are using the stream compiler objects to build your authoring tool, you can create a new enhancement stream simply by creating an instance of an EnhEvents object. The EnhEvents object represents the stream as a whole. To open a pre-existing stream into an EnhEvents object, call EnhEvents.Load and specify the file name of the stream you wish to open.

For more information, see Creating an Enhancement Stream.


Add Events to the Stream

An enhancement stream comprises the many events of an interactive show. Your authoring tool should provide a way for users to add new events, such as triggers, announcements, and file transmissions, to the enhancement stream.

If you are using the stream compiler objects to build your authoring tool, you can use the EnhEvents.Add and EnhEvents.AddText methods to add an event to an enhancement stream.

For more information on using the stream compiler objects to add events to the stream, see Adding Events to an Enhancement Stream.


Create Announcement Files

Typically, the first events you add to the stream will be announcement events. Before you can transmit an announcement event, however, you must generate the file that contains the announcement data. It does not matter whether you create the announcement file before or after the enhancement stream so long as the file name used matches the one in the announcement event.

The Stream Compiler Object Library, Stream.dll, includes an object, Annc, which you can use to programmatically create announcement files. For more information, see Creating Enhancement Announcements and Enhancement Announcement Format.


Allocate Available Bandwidth

Because the broadcast medium used to transmit enhancements, such as a Vertical Blanking Interval (VBI) or Local Area Network (LAN), has a finite bandwidth, there is a limit to the number and size of events that can be transmitted during an interactive show.

Your authoring tool should provide a way for users to enter the available bandwidth, and an indication of how much of the bandwidth is utilized by the current stream. Your tool should warn the user when the enhancement stream exceeds the given bandwidth and enable the user to reduce the number or size of events.

The stream compiler objects provide several tools to assist your authoring tool in managing bandwidth utilization. The EnhEvents.Bandwidth property stores the total available bandwidth for the broadcast medium. The EnhEvent.Length property contains the length of the file being transmitted, in bytes. Other methods and properties enable your application to determine the time and bandwidth required to transmit an event. EnhEvent.XmitDuration determines the time required to transmit an event based on its length, the bandwidth, and the file transmission redundancy. By comparing the show time to the time required to transmit all of the stream events, you can calculate the percentage of the available bandwidth currently used.


Edit and Delete Events in the Stream

Authoring an enhancement stream often requires the user to make alterations to the stream. These corrections may be due to a changing format for the show, errors discovered during testing, or the need to stay within a budgeted bandwidth.

Your authoring tool should provide a way for users to delete or change the properties of stream events.

If you are using the stream compiler objects to build your authoring tool, you can edit an event by locating its corresponding EnhEvent object in the EnhEvents collection and changing the values of its properties. To delete an event, call the EnhEvent.Delete method of the event the application is deleting.

For more information on using the stream compiler objects to edit or delete events from the stream, see Locating an Event in the Enhancement Stream and Editing and Deleting Events in an Enhancement Stream.


Validate the Stream Language Syntax

Syntax validation checks that each event in the stream corresponds to a valid Enhancement Stream language statement. This validation can either be done as each event is added to the stream or you can validate the entire stream as a batch process.

The stream compiler objects provide several methods to assist you in validating the stream syntax. When you call the EnhEvents.Load or EnhEvents.AddText methods, the compiler objects automatically check the stream syntax and build an array of the errors it finds. EnhEvents.ErrorCount contains the number of errors in the array and EnhEvents.ErrorList enables you to view a particular error in the array.

Note that the error-checking provided by the stream compiler objects is basic, and may not catch every error caused by user input. It is recommended that you implement additional validation in your authoring tool.

Even if the production team is fluent in the stream compiler language and is authoring the stream using a text editor, a syntax validation tool may still be useful. Such a tool, for example, might search through a .str file, notify the user when there is an error, enable the user to fix the error, and re-check the syntax.

A sample syntax checker, Validator, is included with the software accompanying the Broadcast Architecture Programmer's Reference. To locate this sample application, see Broadcast Architecture Sample Applications.


Convert the Stream to Low-Level Syntax

Converting the enhancement stream to low-level syntax causes compound events, such as those that contain repetition or dependencies, to be converted into multiple simple statements. This is a useful step if your tool needs to examine the stream in its simplest form, such as when your tool plays a stream, determines the required transmission bandwidth, and so on.

Note If your application only adds low-level events to the stream conversion to low-level format is not necessary. Such an application, for example, would store the download of a file with three dependencies as four low-level events instead of a single compound event.

If you use the enhancement sender object to transmit the enhancement stream to clients you must convert the stream to low-level syntax before you broadcast it.

If you are using the stream compiler objects, you can convert the stream to low-level format by calling EnhEvents.Flatten. For more information, see Converting Events to Low-level Syntax.


Save the Stream to Disk

Saving the enhancement stream to disk enables the user to store the stream for later transmission or editing. Your authoring tool should provide a way for users to store the stream.

By convention, enhancement streams are stored as Enhancement Stream language statements in a text file with a .str extension. The following is an example of the file format used by the stream compiler objects. This text file would have a name such as MyStream.str.

00:10:19:00 "Pretty.gif";
00:10:26:00 "Left_07.htm" only;
00:10:30:00 trigger 1 "Left_07.htm" only;
00:11:19:00 "Pretty.gif";
00:11:26:00 "Left_07.htm" only;

If you are using the stream compiler objects, you can save the stream to disk by calling the EnhEvents.Store method and specifying a file name. For more information on using the stream compiler objects to save a file, see Loading or Saving an Enhancement Stream.


Test the Stream

Before an interactive show is broadcast to clients, the stream should be tested to ensure that the video and enhancements are properly synchronized and that the interactive show displays correctly. To simplify this process for the user, you can create an application that displays the interactive show locally.

A stream player enables users to play back the enhancement stream in conjunction with video, so the user can view the show exactly as it would appear on broadcast clients and check the interactive show. The player can either be implemented as a separate application, or built into a stream editing tool. Ideally, the player should be integrated with the editor so the user can easily correct any errors they discover while viewing the interactive show.

The following steps outline the functionality of an enhancement stream player:

  1. Read in an enhancement stream. For more information on how to do this, see Loading or Saving an Enhancement Stream.
  2. Start Microsoft WebTV for Windows or a Web browser to display the interactive show.
  3. Play the video from a multimedia file or a VCR. For more information on how to do this, see Displaying Video and the Enhancement Video Control.
  4. Synchronize the enhancement stream with the video. This ensures that the enhancement stream starts to play at exactly the same time that the show starts. This is essential to test the timing of stream events.
  5. Play or transmit the enhancement stream locally so that the client responds to the enhancement events. For more information on how to do this, see Broadcasting an Enhancement.

Note The interactive show can only be tested on a computer that has the broadcast component of the Microsoft® Windows® 98 operating system installed. The broadcast component installs the broadcast client, which contains controls, such as the enhancement control, required to display the interactive show.

The software provided with the Broadcast Architecture Programmer's Reference includes a sample stream player application. To locate this sample application, see Broadcast Architecture Sample Applications.


Transmit the Stream

Once the stream has been created and tested with the video, your tools should provide a way for the producers at the head-end to transmit the stream, with its accompanying video, to the broadcast clients.

The enhancement stream can be transmitted several ways, either packaged with the video, as in the case of VBI-line encoding, or transmitted before the show is broadcast using a means such as Internet channel broadcasting. In either case, you can use the enhancement sender object to transmit the enhancement stream. Because the enhancement sender always transmits the stream to a Microsoft Multicast Router it is independent of the actual transmission means. The implementation details of the broadcast medium are handled by hardware-specific virtual interfaces set in the router. For more information, see Working with the Microsoft Multicast Router.

If you are going to use the enhancement sender object to transmit the stream, you must first convert it to low-level format. For more information on how to do this, see Converting Events to Low-level Syntax.

If your authoring tool transmits the enhancement stream, it should provide a way to set the network interface card, IP addresses and IP ports used to broadcast triggers, file downloads, and announcements. Your application can either collect this information from the user or detect these values automatically.

For more information about using the enhancement sender object to broadcast the enhancement stream, see Broadcasting an Enhancement.

Note If you are using a custom application to transmit the stream to clients instead of the enhancement sender object, ipsend, you must implement the redundancy value described in Trigger Checksum Value.


Additional Stream Authoring Functionality

This topic discusses additional functionality that you can add to your stream authoring tool to make it easier to use and more robust. While the features described below are not essential to a stream authoring tool, they add considerable value.

  • Merging and Including Streams
  • Custom Comments and Syntax
  • Graphical Time Line
  • Indication of Bandwidth Utilization
  • Wizards
  • Templates


Merging and Including Streams

Sometimes a user may wish to combine enhancement streams. For example, if multiple production teams are working on different aspects of the interactive show or if the user is creating a master enhancement stream that comprises several consecutively-broadcast shows.

When your application combines two streams it should resolve time and resource conflicts. For example, if events in the combined streams occur simultaneously, your application should shift one of the events to occur slightly earlier or slightly later so that they do not occur at the same time.

The stream compiler objects provide two ways to combine streams: merging and including. The difference between merging and including a stream is how you specify the relative starting time of the added stream. When two files are merged, the starting time of the added stream is specified in EnhEvents.LoadBias. If you are including one stream within another, the second stream's start time is relative to the time the stream was included.

For more information about using the enhancement stream objects to combine streams, see Merging Enhancement Streams and Including One Enhancement Stream in Another.


Custom Comments and Syntax

Your authoring tool can store application-specific data as user comments in an event. For example, if your tool needs to identify which author has entered an event into the stream, it can store the user's name as a comment in the added event. The comment is stored as a microevent within the event.

To add a comment or custom data to an event, use the userdef keyword. The stream compiler objects provide several methods that enable you to set and edit user comments: EnhEvent.Attr, EnhEvent.Opcode, and EnhEvent.AttrCount. For more information about using these methods, see Adding User-Defined Comments to an Event.

The only limitation the stream compiler objects place on user-defined comments is that a comment cannot be followed by any other type of microevent, such as a file transmission or announcement. Custom comments are expected to be the last items in an event string, and as such, can only be followed by other custom comments.


Graphical Time Line

Presenting the user with a graphical representation of the enhancement stream time line enables the user to better visualize where in the stream an event occurs. This can be accomplished, for example, by creating a Microsoft® ActiveX® control that reads an enhancement stream and displays the events in a horizontal time line. The following illustration presents an example of a control that uses arrows to indicate events.

You might write a graphical time line control that enables the user to edit an event by clicking on the marker that represents it.


Indication of Bandwidth Utilization

Allocating the limited broadcast bandwidth is a part of any stream-authoring tool. You can extend this functionality by providing the user with a graphical or numerical display of the running total of allocated bandwidth.

A graphical display, such as a bar or pie graph, helps the user visualize how much bandwidth is left and can influence their enhancement design decisions. For example, if a repetitions of a particular file download are taking up half the available bandwidth, the user can choose to reduce the file size by making enhancement pages more simple or to reduce number of times that the file is transmitted.


Wizards

You can increase the ease-of-use of your authoring tool by providing wizards that walk the user through common stream-authoring tasks such as creating a new enhancement stream. Wizards are especially useful for the novice user because they guide the user through the decision-making process and can suggest default values.


Templates

Enhancement stream templates are Enhancement Stream language files that contain standard or blank stream events. For example, if a show is repeatedly broadcast, such as a weekly situation comedy, the enhancements for each episode may contain the same elements, for example, each episode might broadcast the same HTML cast pages.

If the enhancement streams created by your users follow a pattern, using a template enables your tool to more quickly build the stream because it does not have to re-create the basic stream framework. The tool simply modifies events already in the template to fit the user's needs.

You can extend this functionality even further by providing a way for users to create and define their own custom templates.


Avoiding Problems in Stream Authoring Tools

This topic describes potential pitfalls and inefficient design that can occur when building stream authoring tools and how to avoid them.

How can I play a stream if the files are not in the spool directory?

In normal operation, the Enhancement control resolves all file locations relative to the spool directory. This is a security feature that ensures that enhancements do not access the client's file system. During authoring, however, the files for an interactive show may be spread over many directories or machines.

Your application could copy the enhancement files to the spool directory when it displayed or tested the stream. This is an inelegant solution that results in extra copies of the enhancement files and can result in versioning problems.

A more elegant solution is to change the behavior of the Enhancement control to use fully-specified paths. Instead of resolving paths relative to the spool directory, the Enhancement control accepts only fully-specified paths such as "C:\Program Files\TV Viewer\Temp Enhancement\MyEnhShow.5".

To do this, set the HKLM/Software/Microsoft/TV Services/Enhanced Content/AcceptFullPaths registry key to a nonzero value. Note that this key is not created during installation of the client, so you may have to create it before you set the value.

Once this registry key is set, the Enhancement control does not resolve paths. Your application can use fully-specified paths in the enhancement stream to display the files from their current locations.

Do not forget to change the paths in the enhancement stream back to their spool-relative values before you transmit the stream to clients.

For more information, see Enhancement Registry Entries.


Writing and Testing Server Applications

Content server applications running on a network that includes a Microsoft® Multicast Router (MMR) can send data to the MMR for routing to the broadcast network.

The software supporting Broadcast Architecture includes a sample, called Wsend that is a simple content server application. Another projects in the software supporting Broadcast Architecture, called Wlisten is a test program that you can use to monitor multicast packets sent by your content server application. A third project, Brtest, creates a library of objects used by WSend and Wlisten. To locate the source code for these samples, see Broadcast Architecture Sample Applications.

Content server applications are very diverse, and no one series of steps to create one can be recommended. How content server applications incorporate code to send data to the MMR differs widely. The WSend sample is a simple example of a content server application, designed to illustrate the use of the MMR access functions. For an overview on how to create a content server application, see Writing Content Server Applications.

The following topics show how the samples work:

  • Some Useful Objects
  • Key Routines in Wsend
  • Key Routines in Wlisten


Some Useful Objects

Brtest is a library that includes several objects that applications can use to send data to the MMR. The following table lists the objects:

Object | Description
CData | Base class for data storage
CString | CData-derived class for strings
CSession | Base class for connections to the MMR
CMulticast | Multicast session
CTunnel | Tunneling session


CData

The CData class is a base class for objects that contain data. It includes member functions for locking the data in order to control access to the data in multithreaded applications.


CString

The CString class is derived from the CData class. The data in this object is a null-terminated string.


CSession

The CSession class is an abstract base class for a connection to the MMR. This class should not be used directly. Instead, use CMulticast or CTunnel depending on the type of connection.


CMulticast

The CMulticast class is derived from CSession. It includes a method to broadcast multicast packets that the MMR can route to a virtual interface (VIF).


CTunnel

The CTunnel class is derived from CSession. The constructor opens a socket connection to the MMR called a tunnel. The send method sends data through this tunnel to the MMR. Using a tunnel allows the MMR to control the rate that the server application sends the data.


Key Routines in Wsend

The Wsend program uses the objects in the Brtest library to send data to the MMR. This program can use either tunneled access or send IP multicast packets.

Much of the code in Wsend.cpp is meant to handle saving and restoring data from the registry and also to handle the user interface. The operation of these functions is not covered in this chapter.

The functions that illustrate how to connect to the MMR and send data are described in Multicasting Functions and Tunneling Functions.


Multicasting Functions

When you start a multicast session in WSend, it calls the OnStartMulticast function. This function starts a thread that multicasts data using the MulticastWorkerThread function.

The MulticastWorkerThread function runs until you stop the session. The OnStopMulticast function handles stopping the session by setting an abort event, waiting for the event to be handled by the thread, then shutting down the thread.

The MulticastWorkerThread function handles sending the multicast packets. It calls the BandwidthThrottleSend function repeatedly to send the data. The BandwidthThrottleSend function computes the speed for sending data based on the amount of data to send and the bandwidth of the virtual interface. The result of the speed computation is the number of milliseconds to wait between send operations. While waiting, BandwidthThrottleSend checks for abort events, to know when to stop sending.


Tunneling Functions

When you open a tunnel session in WSend it calls the OnOpenTunnel function. This function opens a tunnel to the MMR and, if the tunnel opens without error, starts a thread that sends data through the tunnel. The OnCloseTunnel function stops the transfer by setting an abort event, waiting for the thread to process the abort event, and shutting down the thread.

The TunnelWorkerThread function is nearly identical to the MulticastWorkerThread function. The difference is that the send function in BandwidthThrottleSend uses a tunnel to send the data to the MMR instead of broadcasting multicast packets.


Key Routines in Wlisten

Wlisten.exe waits for specified multicast packets and displays information about them. The key function in this program is WorkerThread, a routine that runs as a thread when WListen is listening for multicast packets.

WorkerThread starts by creating an event that indicates when the socket is available for reading. The main loop of the thread waits for this event or a completion event. If it sees the read event, WorkerThread reads data from the socket and processes the data so it can be displayed. When the user shuts down Wlisten, the program sets a completion event that causes WorkerThread to close down and exit.


Numbers

802.3 intermediate driver
A Network Driver Interface Specification (NDIS) intermediate driver that is a component of Broadcast Architecture. This driver translates Multipacket Transport (MPT) packets from satellite networks into Internet Protocol (IP) packets. This translation makes it possible for Windows Sockets (WinSock) to handle the data as it does any other data carried by Transmission Control Protocol/Internet Protocol (TCP/IP).


A

ActiveX control
A reusable software component that can quickly add specialized functionality to World Wide Web sites, desktop applications, development tools, and interactive video programs. These controls typically provide user interface elements, such as buttons. Microsoft® ActiveX® controls were previously known as OLE custom controls or OCXes.
Address Resolution Protocol
(ARP) The protocol that maps Internet Protocol (IP) addresses to the physical hardware addresses of specific networks. This protocol operates at the level of network operating systems and is not generally accessible to applications.
ADSL
See Asymmetrical Digital Subscriber Line.
analog television tuner card
A type of broadcast receiver card that receives and processes analog video signals.
analog video
Video transmitted by an analog signal, such as an NTSC, PAL, or SECAM transmission.
announcement filter
In the Announcement Listener, one of a collection of dynamic-link libraries (DLLs) or executable files that act as Automation servers. An announcement filter distinguishes between announcements that are of interest to a particular broadcast client's user and those that are not. Multiple filters can exist for different kinds of data; for example, in Broadcast Architecture Internet channel broadcasting and enhancements have their own filters.
Announcement Listener
A operating-system service that receives announcements of upcoming data. Using Announcement Listener, the broadcast client can filter incoming data at the network interface (that is, at the broadcast receiver card) so the client only receives data of interest.
API
See application programming interface.
application
A computer program designed to help people perform a certain type of work. An application differs from an operating system (which runs a computer), a utility (which performs maintenance or general-purpose chores), and a programming language (with which computer programs are created). An application can manipulate text, numbers, graphics, or a combination of these elements. In the context of Broadcast Architecture, potential applications might enable users to shop at home, find information, order movies, and so on.
application layer
The seventh and highest layer in the International Organization for Standardization's Open Systems Interconnection (OSI) model. The application layer contains the signals sent during interaction between user and application and that perform useful work for the user, such as file transfer. See also data link layer, transport layer.
application programming interface
(API) An interface exposed by a software module as a means for other software modules to interact with it. For example, applications generally interact with an operating system by way of the APIs the operating system exposes. In the case of Microsoft® Windows® 98 and Microsoft® Windows NT®, the APIs consist of functions that an application uses to request operating-system services, such as screen management, keyboard input, printer output, and so forth.
ARP
See Address Resolution Protocol.
ASCII
(American Standard Code for Information Interchange) A coding scheme that assigns numeric values to letters, numbers, punctuation marks, and certain other characters. By standardizing the values used for these characters, ASCII enables computers and computer programs to exchange information. Although it lacks accent marks, special characters, and non-Roman characters, ASCII is the most universal character-coding system.
Asymmetrical Digital Subscriber Line
(ADSL) A technology that allows data to be sent over ordinary twisted-pair telephone lines at T1 trunk-line speeds, currently up to 1.544 megabits per second, and to be returned at a current rate of 16 kilobits per second. ADSL provides a bidirectional voice signal while data is sent.
authorization key
A Triple DES key used to encrypt session keys.


B

back channel
The segment of a two-way communications system that flows from the consumer back to the content provider, or to a system component, to provide feedback.
backbone
The top level in a hierarchical network.
bandwidth
Literally, the frequency range of an electromagnetic signal, measured in hertz (cycles per second). The term has come to refer more generally to the capacity of a channel to carry information, as measured in data transferred per second. Transfer of digital data, for example, is measured in bits per second.
bandwidth reservation
The process of setting aside bandwidth on a specific broadcast channel for a specific data transmission. A content server application reserves bandwidth on a Microsoft Multicast Router by calling the msbdnReserveBandwidth function. This function forwards the request to a bandwidth reservation server. The server returns a unique reservation identifier if the bandwidth can be reserved. See also IP multicast address assignment.
baseband
Describes transmissions using the entire spectrum as one channel. Alternatively, baseband describes a communication system in which only one signal is carried at any time. An example of the latter is S-video or a composite video signal that is not modulated to a particular television channel. See also broadband.
baud
Number of bits per second, a measure of data-transmission speed. Baud was originally used to measure the transmission speed of telegraph equipment but now most commonly measures modem speed. The measurement is named after the French engineer and telegrapher Jean Maurice-Emile Baudot.
broadband
Describes high-frequency transmissions over coaxial cable or optical fibers, involving sending several data streams simultaneously. Broadband is also sometimes used to describe high-speed networks in general. See also baseband.
broadcast
In general terms, a transmission sent simultaneously to more than one recipient. In Internet terminology, a transmission sent to a single address to be forwarded to many recipients. In practice, Internet broadcasts only function on local networks, because routers do not forward them. Broadcast Architecture uses a refinement of this Internet technique known as multicast, in which routers forward transmissions. In multicast, each transmission is assigned its own Internet Protocol (IP) multicast address, allowing clients to filter incoming data for specific packets of interest at the network interface card.
Broadcast Architecture
The Microsoft computer software and hardware design that enables personal computers to serve as clients of broadband digital and analog broadcast networks.
Broadcast Architecture subsystems
The functional parts that make up Broadcast Architecture. These include the Broadcast and Data Receiver subsystem, the Data Services subsystem, the Video and Display subsystem, the User Interface subsystem, and the Television Client Services subsystem. For more information, see the Broadcast Client Architecture section of the Broadcast Architecture Programmer's Reference.
broadcast client
A versatile personal computer that can receive and display broadband digital and analog broadcasts, blending television with new forms of information and entertainment. Broadcast client programming can include television, audio, World Wide Web pages, and computer data content.
Broadcast Cryptography API
Broadcast Architecture functions that help CryptoAPI decrypt content using encryption keys.
broadcast data encoder
A hardware subsystem provided by an independent hardware vendor that encodes data for broadcast, for example pay-per-view shows that only subscribers may watch. A broadcast data encoder receives data streams from the Microsoft Multicast Router through a virtual interface.
broadcast receiver card
A printed circuit board or adapter that can be plugged into a computer to receive and process broadcast signals, such as television or other broadcast data. One type of broadcast receiver card is a satellite receiver card. Another is an analog television tuner card.
broadcast server
A computer that sends broadcast programming across a broadcast channel to broadcast clients, in some cases forwarding data over the Microsoft Multicast Router. The programming sent can include television, audio, World Wide Web pages, and digital data such as stock prices, multimedia magazines, and computer software.
Broadcast Architecture transport
A Broadcast Architecture component that manages broadcast data received through a broadcast receiver card. The Broadcast Architecture transport binds to the Broadcast Architecture NIC miniports, which control and retrieve data in formats such as MPEG, audio, Microsoft Broadcast Data Network (MSBDN), or any arbitrary format.


C

CDF
See Channel Definition Format.
CERN
(Conseil Europeen pour le Recherche Nucleaire, or European Laboratory for Particle Physics), a research laboratory with headquarters in Geneva, Switzerland. CERN pioneered work in developing the World Wide Web. CERN intended the Web to help scientists share information.
channel
In general, a path or link through which information passes between two devices. For example, a television channel carries a specific sequence of television programming. In Microsoft® Internet Explorer version 4.0, a channel is a collection of World Wide Web pages defined by means of a Channel Definition Format (CDF) file.
Channel Definition Format
(CDF) A specification for a format that defines a content channel. Microsoft developed this specification and has presented it to the World Wide Web Consortium (W3C). Applications can use CDF files to offer users subscriptions to World Wide Web channels. Subscription applications automatically update the channel content on a user's computer when this content changes on the channel server. The Internet channel broadcasting components of Broadcast Architecture use CDF files to define subscription content.
chroma
The color portion of the video signal that includes hue and saturation information. Hue refers to a tint or shade of color. Saturation indicates the degree to which the color is diluted by luminance or illumination. See also YUV.
class
In general terms, a category. In programming languages, a class is a means of defining the structure of one or more objects. See also device class.
class driver
A standard driver provided with the operating system that provides hardware-independent support for a given class of devices. Such a driver communicates with a corresponding hardware-dependent minidriver using a set of device control requests defined by the operating system. These requests are specific to the particular device class. A class driver can also define additional device control requests itself. A class driver provides an interface between a minidriver and the operating system.
client
Generally, one of a group of computers that receive shared information sent by a computer called a server over a broadcast or point-to-point network. The term client can also apply to a software process, such as an Automation client, that similarly requests information from a server process and that appears on the same computer as that server process, or even within the same application.
closed captioning
Real-time, written annotation of the currently displayed audio content. Closed captioning usually provides subtitle information to hearing-impaired viewers or to speakers of a language other than that on the audio track.
color keying
A display technique in which a selected Video Graphics Array (VGA) color is replaced with video wherever that color appears on the screen. For example, television news programs commonly use color keying to replace a blue backdrop mounted behind a weather announcer with a video picture of a weather map.
COM
See Component Object Model.
commit
To allocate a device data stream and tune a specified connection to that device data stream. Such commitment is performed by a NIC miniport.
common library interface functions
Software routines supplied by Broadcast Architecture that add network driver functionality to a broadcast receiver card and manage computer memory resources for hardware-specific code. To use these common library interface functions, a hardware vendor building a NIC miniport should link the miniport code to the common library.
Component Object Model
(COM) An object-oriented programming model for building software applications made up of modular components. COM allows different software modules, written without information about each other, to work together as a single application. COM enables software components to access software services provided by other components, regardless of whether they involve local function calls, operating system calls, or network communications.
content producer
A person or company creating broadcast content. Content can include television programming, data, World Wide Web sites, and software applications.
content provider
A person or company delivering broadcast content. Content can include television programming, data, World Wide Web sites, and software applications.
content server application
An application written by a content provider and running on a computer at the broadcast head end that gathers, schedules, and sends data to the appropriate Microsoft Multicast Router. For more information, see the Writing Content Delivery Software section of the Broadcast Architecture Programmer's Reference.
content subnet
A network located at a broadcast head end that connects one or more content server applications to one or more Microsoft Multicast Routers.
CPU
Central processing unit. The computational and control unit of a computer; this device, usually a single chip, interprets and executes instructions. Examples include the Intel Pentium processor.
CRC
See cyclic redundancy check.
CryptoAPI
An application programming interface (API) that provides an abstraction layer for encryption and decryption services provided by a cryptographic service provider. Because CryptoAPI furnishes this layer, applications can use different encryption methods without requiring information about the hardware or software involved. This API also provides a way of protecting sensitive key data. See also Broadcast Cryptography API.
cryptographic service provider
(CSP) An independent software module that contains cryptography algorithms or services that are integrated into CryptoAPI. Many CSPs are Microsoft® Win32® application programming interface (API) service programs, managed by the Win32 service control manager. Some, such as a smart card or secure coprocessor, reside in hardware.
CSP
See cryptographic service provider.
cyclic redundancy check
(CRC) A common technique for detecting errors in data transmission. In CRC error checking, the sending device calculates a number based on the data transmitted. The receiving device repeats the same calculation after transmission. If both devices obtain the same result, it is assumed the transmission was error-free. The procedure is known as a redundancy check because each transmission includes not only data but additional, redundant values for error checking.


D

Data Encryption Standard
(DES) A standard defined by the National Bureau of Standards for encryption of digital data transmissions within the United States.
data link layer
The second of the seven layers in the International Organization for Standardization's Open Systems Interconnection (OSI) model for standardizing computer-to-computer communications. The data link layer is one level above the physical layer. It is involved in packaging and addressing information and in controlling the flow of separate transmissions over communications lines. The data link layer is the lowest of the three layers (data link, network, and transport) that help move information from one device to another. See also transport layer.
data service
A mechanism provided by a service provider for sending broadcast data to broadcast clients. Such data can include Program Guide information, World Wide Web pages, software, and other digital information. The data service mechanism can be any broadcast process, including Internet channel broadcasting.
data stream
See stream.
datagram
One packet of information and associated delivery information, such as the destination address, that is routed through a packet-switching network. In a packet-switching network, data packets are routed independently of each other and may follow different routes and arrive in a different order from which they were sent. An Internet Protocol (IP) multicast packet is an example of a datagram.
dependency
A file that must be downloaded for an enhancement page to display properly, for example an image file in .gif format.
DBS
See direct broadcast satellite.
DES
See Data Encryption Standard.
DES decryptor
A hardware device that converts cipher text encrypted to the Data Encryption Standard (DES) back to plain text.
device
A unit of hardware, for example an audio adapter. For hardware used with the Microsoft® Windows® 98 operating system, such a unit can be detected by Plug and Play. See also device class, device driver, and device object.
device class
A group into which devices and buses are placed for the purposes of installing and managing device drivers and allocating resources. The hardware registry tree is organized by device class. Windows 98 uses class installers to install the drivers for the different classes of hardware.
device driver
A software component that allows an operating system to communicate with one or more specific hardware devices attached to a computer.
device object
A programming object used to represent a physical, logical, or virtual hardware device whose device driver has been loaded into the operating system.
direct broadcast satellite
(DBS) A satellite communications technology that allows use of a very small (18 inches to 3 feet in diameter) receiver dish packaged as a consumer electronics product, enabling consumers to directly receive satellite television signals.
DirectShow
The Microsoft® DirectShow™ (formerly Microsoft® ActiveMovie™) application programming interface (API) is a multimedia technology designed to play video, audio, and other multimedia streams in a variety of formats that are stored locally or acquired from Internet servers. DirectShow relies on a modular system of pluggable components called filters arranged in a configuration called a filter graph. A component called the filter graph manager oversees the connection of these filters and controls the data flow of the stream.
DirectShow filter
A Microsoft® DirectShow™ component that processes data streams. Each filter handles part of the operation involved in receiving, decoding, transforming, scheduling, and displaying interdependent video, audio, or other data streams. Filters connect to each other in a configuration called a filter graph.

A DirectShow filter is a user-mode entity that is an instance of a Component Object Model (COM) object, usually implemented by a dynamic-link library (DLL). A Broadcast Architecture DirectShow filter can be a source filter, a transform filter, a renderer filter, or a utility filter.

See also KSProxy filter.

DLL
See dynamic-link library.
downstream
One-way data flow from head end to broadcast client. See also upstream.
dynamic-link library
(DLL) A file with the file name extension .dll that contains one or more functions compiled, linked, and stored separately from the computing processes that use them.


E

encryption key
A specific value used by an encryption algorithm to encode and decode data.
enhancement
A multimedia element, such as a hypertext link to a World Wide Web page, a graphic, a text frame, a sound, or an animated sequence, added to a broadcast show or other video program. Many such elements are based on Hypertext Markup Language (HTML).
enhancement announcement
An announcement that contains data about an upcoming enhancement for an interactive television show. Such data includes the name of the show the enhancement is associated with, that show's show reference, and the show's base page. The base page is the Hypertext Markup Language (HTML) page that resides at the top level or base of the enhancement pages currently loaded into the user's Web browser for the show in question.
Enhancement control
An ActiveX control that resides on the broadcast client and that handles enhancement events such as file transmissions and triggers. This control is provided with Broadcast Architecture.
enhancement event
A statement in the Enhancement Stream language that causes a broadcast client to perform an action relating to an enhancement. A client's response to an enhancement event can include actions such as receiving a file transmission, updating show data, or displaying new enhancement content to the user. A trigger is a type of enhancement event.
enhancement filter
An announcement filter that processes enhancement announcements.
enhancement page
A Hypertext Markup Language (HTML) page that formats enhancement content, such as images and text, for display.
enhancement stream
A script that synchronizes enhancement events with specific times during an interactive show.
Enhancement Stream language
A programming language used in Broadcast Architecture to create stream scripts that announce, broadcast, and synchronize enhancements with the video of an interactive television show.
Enhancement Video control
An ActiveX control that displays video within an enhancement. Unlike the Video control, which also displays video within an enhancement, the Enhancement Video control can be used only in Hypertext Markup Language (HTML) pages displayed by Microsoft WebTV for Windows. In contrast, the Video control can be used in World Wide Web pages and stand-alone applications as well as in Microsoft® WebTV® for Windows®. The Enhancement Video control automatically handles the connection between itself and WebTV for Windows, whereas the Video control does not. The Enhancement Video control is provided with Broadcast Architecture.
episode
A discrete narrative portion of an ongoing television or radio show, usually viewed in one continuous showing. Generally, an episode forms a coherent story in itself.


F

field
In broadcast television, one of two sets of alternating lines in an interlaced video frame. In one field, the odd-numbered lines of video are drawn; in the other, the even-numbered lines are drawn. When interlaced, the two fields combine to form a single frame of on-screen video.
File Transfer Protocol
(FTP) A protocol that supports file transfers to and from remote systems on a network using Transmission Control Protocol/Internet Protocol (TCP/IP), such as the Internet. FTP supports several commands that allow bidirectional transfer of binary and ASCII files between systems. See also Hypertext Transport Protocol (HTTP).
File Transfer Service
(FTS) A component of Microsoft® NetShow™ server that can send files using a multicast transfer mechanism that includes forward error correction.
filter
See announcement filter, DirectShow filter, or KSProxy filter.
filter graph
A connected set of DirectShow filters that processes media data by controlling KSProxy filters.
filter graph manager
An object that controls how a filter graph is assembled and how data is moved through it. Applications can use the filter graph manager implicitly, allowing it to construct an appropriate filter graph for a specified media format. Applications can also access the filter graph manager explicitly — for example, to add a proprietary filter to a filter graph.
forward error correction
A system of error correction that incorporates redundancy into data so transmission errors can, in many cases, be corrected without requiring retransmission.
frame
In broadcast television, a single screen-sized image that can be displayed in sequence with other slightly different images to animate drawings. For NTSC video, a video frame consists of two interlaced fields of 525 lines; NTSC video runs at 30 frames per second. For PAL or SECAM video, a video frame consists of two interlaced fields of 625 lines; PAL and SECAM video runs at 25 frames per second. In comparison, film runs at 24 frames per second.
FTP
See File Transfer Protocol.
FTS
See File Transfer Service.


G

genre
In Broadcast Architecture, a category of broadcast programs, typically related by style, theme, or format, for example movies or television series.
global announcement
A general message that is sent to all broadcast clients. Global announcements alert clients that information of a specified type will be broadcast at a certain Internet Protocol (IP) address at a certain time, or that a particular type of service is available. Global announcements are intended to be transmitted on all possible channels, so they can be received regardless of what channel a client is tuned to. Such announcements are sent relatively infrequently and may be human-readable. See also local announcement.
guaranteed bandwidth
Bandwidth that is reserved only if the requested bandwidth is available for the requested period. Once reserved, such bandwidth can be relied upon to be available. See also opportunistic bandwidth.
Guide database
In Broadcast Architecture, the database in which Program Guide information is maintained. This database is stored on the broadcast client.


H

hardware-specific interface functions
A set of routines that a hardware vendor must implement to add broadcast network functionality.
HDTV
See high-definition television.
head end
The origin of signals in a terrestrial, cable, satellite, or network broadcast system. In Broadcast Architecture, the server infrastructure that gathers, coordinates, and broadcasts data is generally located at the broadcast head end.
high-definition television
(HDTV) Television that is delivered at a higher screen resolution than NTSC, PAL, SECAM, or other existing standards provide for.
HTML
See Hypertext Markup Language.
HTTP
See Hypertext Transport Protocol.
Hypertext Markup Language
(HTML) A markup language used to create hypertext documents that are portable from one platform to another. HTML files are text files with embedded codes, or markup tags, that indicate formatting and hypertext links. HTML is used for formatting documents on the World Wide Web.
Hypertext Transport Protocol
(HTTP) The underlying, application-level protocol by which World Wide Web clients and servers communicate on the Internet. See also File Transfer Protocol.


I

ICP
Independent content provider. See content provider.
IHV
See independent hardware vendor.
independent hardware vendor
(IHV) A person or company that develops and sells hardware, in this case for Broadcast Architecture.
independent software vendor
(ISV) A person or company that develops and sells software, in this case for Broadcast Architecture.
infrared
(IR) Defines a spectrum of electromagnetic radiation with frequencies in the spectrum less than those of visible light. Remote control units usually communicate with home televisions and VCRs by using infrared signals.
integrated receiver/decoder
(IRD) A subscriber terminal, such as the set-top box used for satellite television systems. In the case of Broadcast Architecture, the IRD is the broadcast receiver card.
Integrated Services Digital Network
(ISDN) A type of phone line used to enhance data transmission speed. Data can be transmitted over ISDN lines at speeds of 64 or 128 kilobits per second, whereas standard phone lines generally limit modems to top speeds of 20 to 30 kilobits per second. An ISDN line must be installed by the phone company.
interactive television
The combination of a video program and multimedia enhancement elements such as hypertext links, graphics, text frames, sounds, and animations.
interface
In computing in general, the point where two elements connect so that they can work with one another, for example the connection between an application and an operating system or between an application and a user (the user interface).

In C++ programming, a collection of related methods exposed by a given class of objects. The methods in an interface are procedures that can be performed on or by those objects.

The Component Object Model (COM) architecture has become the foundation for interfaces that work with the Microsoft® Windows® 98 and Microsoft® Windows NT® operating systems. In earlier programming for Windows, an application programming interface (API) consisted of functions that one piece of software could call to gain access to services provided by another piece of software.

interlacing
A video display technique, used in current analog televisions, in which the electron beam refreshes (updates) all odd-numbered scan lines in one field and all even-numbered scan lines in the next. Interlacing takes advantage of both the screen phosphor's ability to maintain an image for a short time before fading and the human eye's tendency to average subtle differences in light intensity. By refreshing alternate lines, interlacing halves the number of lines to update in one screen sweep. An alternative video display technique, used in computer monitors, is progressive scanning. In progressive scanning, the image is refreshed one line at a time.
Internet
Generically, a collection of networks interconnected with routers. "The Internet" is the largest such collection in the world. The Internet has a three-level hierarchy composed of backbone networks, midlevel networks, and stub networks.
Internet channel broadcasting
A technology to gather and redistribute World Wide Web content. Applications that use Internet channel broadcasting package a series of Web pages or sites and deliver them to broadcast clients at regular intervals. They can provide this content to a broadcast server for retail delivery to subscribing clients, or they can provide the content on a local area network (LAN).
Internet Protocol
(IP) The primary network layer of Internet communication, responsible for addressing and routing packets over the network. IP provides a best-effort, connectionless delivery system that does not guarantee that packets arrive at their destination or that they are received in the sequence in which they were sent. See also Transmission Control Protocol/Internet Protocol and User Datagram Protocol/Internet Protocol.
IP
See Internet Protocol.
IP multicast address assignment
The process by which transient Class D Internet Protocol (IP) multicast addresses are allocated. Each address must be assigned uniquely across the system for a specific time period. Once that time period elapses, the address returns to the available pool. In Broadcast Architecture, these addresses are used to identify data streams being broadcast, both at the head end and in broadcast client systems in the home.
IR
See infrared.
IR/D
See integrated receiver/decoder.
ISDN
See Integrated Services Digital Network.
ISV
See independent software vendor.


J

Java
A object-oriented, platform-independent computer programming language developed by Sun Microsystems. The Applet subclass of Java can be used to create Internet applications.


K

kernel mode
Software processing that occurs at the level of the operating system closest to the computer, ring 0. Kernel-mode software resides in protected memory at all times and provides basic operating-system services. Kernel-mode software may activate hardware directly or interface to another software layer that drives hardware. See also user mode.
KSProxy filter
A WDM streaming component that processes data streams. A KSProxy filter is a kernel-mode entity usually implemented by a driver within the operating system. See also DirectShow filter.


L

local announcement
A specific message that is intended to be sent over a particular broadcaster's own transponder. Most local announcements are not human-readable. Local announcements are generally sent at frequent intervals a short time before the broadcast they announce. See also global announcement.
local area network
(LAN) A network dispersed over a relatively limited area and connected by a communications link that enables each device on the network to interact with any other. See also wide area network.
log on
To provide a user name and password that identifies you to a computer network.
luminance
A measure of the degree of brightness or illumination radiated by a given source. Alternatively, the perceived brightness component of a given color, as opposed to its chroma. See also YUV.


M

MBONE
See multicast backbone.
merchant server
A server that enables user purchases in a secure fashion.
Microsoft Broadcast Data Network
(MSBDN) A high-bandwidth broadcast network, capable of sending 2 to 25 megabits per second, or 22 to 270 gigabits per day. MSBDN is designed to use strong Data Encryption Standard (DES) encryption to secure valuable goods and services so that only paying subscribers have access to them. This high level of security will make MSBDN a suitable channel for delivery of software and other expensive digital goods and services that would otherwise be vulnerable to theft.
Microsoft Multicast Router
(MMR) A component that enables a content server to send a data stream to a multiplexer or other broadcast output device. The MMR calls a virtual interface to package and transmit a stream at the appropriate rate and in the appropriate packet format.
Microsoft WebTV for Windows
A component of the Microsoft® Windows® 98 operating system that enables users to select television channels and that displays interactive television programs. Microsoft® WebTV® for Windows uses an ActiveX control to display conventional television shows, and it hosts a Hypertext Markup Language (HTML) browser to display interactive content for those shows at the same time.
minidriver
A hardware-specific dynamic-link library (DLL) that uses a Microsoft-provided class driver to accomplish most actions and provides only device-specific controls. In Windows Driver Model (WDM), the minidriver registers each device with the class driver, which creates an object for each device. The minidriver uses these device objects to make calls to the operating system.
miniport
Software that communicates with a specific piece of peripheral hardware through a port. A miniport translates all applicable commands that come through the port from the computer into the appropriate hardware commands. This miniport functionality means the port does not require extensive information about each piece of hardware it supports. See also NIC miniport.
miniport driver
See miniport.
MMDS
See Multichannel Multipoint Distributed System.
MMR
See Microsoft Multicast Router.
MPEG
(Motion Pictures Experts Group standard) MPEG-1 is a standard designed for video playback of NTSC quality from CD-ROM. MPEG-1 provides video and audio compression at rates up to 1.8 megabits per second. MPEG-2 provides higher video resolutions and interlacing for broadcast television and high-definition television (HDTV). Both standards were created by the Motion Pictures Experts Group, an International Standards Organization/International Telegraph and Telephone Consultative Committee (ISO/CCITT) group set up to develop motion video compression standards.
MPT
See Multipacket Transport.
MSBDN
See Microsoft Broadcast Data Network.
MTS
A stereo encoding standard used with analog audio and video transmissions.
multicast
A point-to-many networking model in which a packet is sent to a specific address, and only those computers that are set to receive information from this address receive the packet. On the Internet, the possible IP multicast addresses range from 224.0.0.0 through 239.255.255.255. Computer networks typically use a unicast model, in which a different version of the same packet is sent to each address that must receive it. The multicast model greatly reduces traffic and increases efficiency on such networks.
multicast backbone
(MBONE) A virtual, multicast-enabled network that works on top of the Internet. The most popular application for the MBONE is video conferencing, including audio, video and whiteboard conferencing. However, the essential technology of the MBONE is simply multicast — there is no special support for continuous media such as audio and video. The MBONE has been set up and maintained on a cooperative, volunteer basis.
Multichannel Multipoint Distributed System
(MMDS) Also known as wireless cable, this system broadcasts terrestrial or satellite microwave transmissions directly to consumers' homes. The Federal Communications Commission (FCC) invented this system in the 1980s to provide competition to traditional cable television companies. There are currently 33 MMDS channels allocated, most in the 2.5-gigahertz band.
multihomed computer
A computer connected to two or more networks or having two or more addresses on one network. For example, a network server may be connected to multiple local area networks (LANs). Generally, a multihomed computer may send and receive data over any of its connections but does not necessarily route traffic for other computers.
multimedia
Online material that combines text and graphics with sound, animation, or video, or some combination of the three.
Multipacket Transport
(MPT) A data link adaptation layer developed by Microsoft that resides above the data link layer of a network with large, fixed-size packets, such as a satellite system. MPT allows higher-layer protocols such as Internet Protocol (IP) to exist independently of, and be unaffected by, the underlying network.
multiplexer
In general terms, a device for funneling several different streams of data over a common communications line. In the case of Broadcast Architecture, a multiplexer combines multiple television channels and data streams for a single transponder.


N

NABTS
(North American Basic Teletext Specification) An open standard for transmission of data over the television vertical blanking interval (VBI). NABTS is an established standard for television data transmission, and it is in use by broadcasters and systems integrators in North America, Europe, South America, and the Far East.
NDIS
See Network Driver Interface Specification.
NDIS extension
An addition to the Network Driver Interface Specification (NDIS) that provides supplementary functionality. Broadcast Architecture supplies NDIS extensions that must be supported by all NIC miniports written to control broadcast receiver cards and by all transports that work with and access broadcast receiver cards.
network
In computing, a data communications system that interconnects a group of computers and associated devices at the same or different sites. See also local area network, wide area network.

In television broadcasting, a chain of radio or television broadcasting stations linked by wire or microwave relay, or a company that produces the programs for these stations.

Network Driver Interface Specification
(NDIS) In Microsoft® Windows® networking, the Microsoft/3Com specification for the interface between device drivers and a network. All transports call the NDIS interface to access and work with network interface cards (NICs). Using NDIS, developers can write hardware device drivers that are independent of a target operating system. Broadcast Architecture supports NDIS version 5.0.
network interface card
(NIC) An printed circuit board, adapter or other device used to connect a computer to a network.
NIC
See network interface card.
NIC miniport
Miniport for the Broadcast Architecture network interface card (NIC). The NIC miniport supports Network Driver Interface Specification (NDIS).
NIC miniport driver
See NIC miniport.
North American Basic Teletext Specification
See NABTS.
NTSC
(National Television System Committee standard) Standard regulating analog television signals in North America, Japan, and parts of South America, originated by the National Television System Committee. North America and Japan established NTSC color standards to make signals compatible with black and white transmissions. NTSC is based on the 60-hertz rate of U.S. electrical mains. An NTSC set can display 525 scan lines at approximately 30 frames per second, but nonpicture lines and interlaced scanning methods make for an effective resolution limit of about 340 lines. NTSC bandwidth is 4.2 megahertz. See also PAL, SECAM.


O

object
A computer programming term describing a software component that contains data or functions accessed through one or more defined interfaces. In Java and C++, an object is an instance of a object class.
octet
A group of eight bits capable of representing 256 different values. Internet Protocol (IP) addresses are typically represented in dotted-decimal notation — that is, with the decimal values of each octet of the address separated by periods, for example 138.57.7.27.
operating system
Software responsible for controlling the allocation and usage of computer hardware resources such as memory, CPU time, disk space, and peripheral devices.
opportunistic bandwidth
Bandwidth granted whenever possible during the requested period, as opposed to guaranteed bandwidth, which is actually reserved for a given transmission.
overlay
In video, to superimpose a graphic image generated on a computer over video signals, either live or recorded.


P

packet
A unit of information transmitted as a whole from one device to another on a network. In packet-switching networks, a packet is defined more specifically as a transmission unit of fixed maximum size that consists of binary digits representing both data and a header containing an identification number, source and destination addresses, and sometimes error-control data.
PAL
(Phase Alternation by Line standard) The analog television standard for much of Europe, excepting France, Russia, and most of Eastern Europe, which use SECAM. As with SECAM, PAL is based on a 50-hertz power rate, but it uses a different encoding process. It displays 625 scan lines and 25 frames per second and offers slightly better resolution than the NTSC standard used in the North America and Japan. PAL bandwidth is 5.5 megahertz.
pay per view
(PPV) A revenue-enhancing system in which cable or satellite customers are charged for watching a single movie or event. This system contrasts with premium cable services, which are paid for monthly regardless of usage.
PC 97
The system and peripheral design elements required for a computer to bear the 1997–1998 "Designed for Microsoft® Windows®" logo. PC 97 Hardware Design Guide defines these requirements.
PC 98
The system and peripheral design elements required for a computer to bear the 1998–1999 "Designed for Microsoft® Windows®" logo. PC 98 Checklist, an addendum to PC 97 Hardware Design Guide, defines these requirements.
pin
In the Component Object Model (COM), an object that represents the point where a unidirectional data stream connects to a filter. An input pin receives media samples, and an output pin passes media samples to the next filter.
Plug and Play
A design philosophy and set of specifications that describe changes to hardware and software for the personal computer and its peripherals. These changes make it possible to automatically identify and arbitrate resource requirements among all devices and buses on a computer. Plug and Play specifies a set of application programming interface (API) elements that are used in addition to existing driver architectures.
port
Generally, the address at which a device such as a network interface card (NIC), serial adapter, or parallel adapter communicates with a computer. Data passes in and out of such a port. In Internet Protocol, however, port signifies an arbitrary value used by the Transmission Control Protocol/Internet Protocol (TCP/IP) and User Datagram Protocol/Internet Protocol (UDP/IP) to supplement an IP address so as to distinguish between different applications or protocols residing at that address. Taken together, an IP address and a port uniquely identify a sending or receiving application or process. See also port driver.
port driver
An interface library of functions and services provided to a minidriver so that the minidriver can communicate with the operating system. The MPEG port driver is one example.
PPV
See pay per view.
Program Guide
An on-screen guide that lists television and cable programs and broadcast time slots. This Broadcast Architecture component receives current information about program schedules and maintains these in the Guide database. The Program Guide enables the viewer to review, select, and control what programs will be watched.
push model
A broadcast model in which a server sends information to a large number of clients on its own schedule, without waiting for requests. The clients scan the incoming information, save the parts they have been instructed to save, and discard the rest. Because the push model eliminates the need for requests, it allows one server to handle as much data as it has bandwidth to send. The push model contrasts with the pull model, in which each client requests information from a server. The pull model is more efficient for interactively selecting specific data to receive but uses excessive bandwidth when many clients request the same information.


Q

query
A request that specific data be retrieved, modified, or deleted.


R

radio frequency
(RF) The portion of the electromagnetic spectrum with frequencies between 10 kilohertz and 300 gigahertz. This portion includes the frequencies used for radio and television transmission.
RAM
Random access memory. RAM is semiconductor-based memory within a personal computer or other hardware device that can be rapidly read and written to by a computer's microprocessor or other devices. It does not generally retain information when the computer is turned off. See also ROM.
rating
A category applied to movies and other programs to reflect the age appropriateness of their content, particularly to help parents decide whether children should view the shows. Possible Motion Picture Association of America (MPAA) ratings include NR (not rated), G (general), PG (parental guidance suggested), PG-13 (parents strongly cautioned), R (restricted), NC-17 (no children under 17).
recordset
A recordset represents the entire set of records from a table in a database or that result from an executed command. A recordset is a set of rows in which each row has columns of data.
registry
In the Microsoft® Windows® 98 and Microsoft® Windows NT® operating systems, a hierarchical database that provides a repository for information about a computer's hardware and software configuration.
renderer filter
A filter that renders the contents of a stream on an output device such as a computer monitor, sound card, or printer. Renderer filters have only input pins.
resource
A piece of static data, such as a dialog box, that can be used by more than one application or in more than one place within an application. Alternatively, any part of a computer or network, such as a disk drive, printer, or memory, that can be used by a program or process.
RF
See radio frequency.
ring 0
The operating system kernel or core—in other words, the portion that allocates system resources; manages memory, files, and peripheral devices; maintains the time and date; and starts applications. See also kernel mode.
ring 3
The application layer. Ring 3 includes applications, dynamic-link libraries (DLLs), and DirectShow filters.
ROM
Read-only memory. ROM is semiconductor-based memory within a personal computer or other hardware device that contains instructions or data that can be read but not modified. See also RAM.
router
A device that helps local area networks (LANs) and wide area networks connect and interoperate. A router can connect LANs that have different network topologies, such as Ethernet and token ring. Routers choose the best path for a packet, optimizing network performance.


S

satellite receiver card
A broadcast receiver card that receives and processes data sent by satellite.
satellite uplink
The system that transports a signal to a satellite for broadcast. Signals usually come to the uplink through multiplexers.
SECAM
(Sequential Couleur á Memoire, or Sequential Color with Memory) The television standard for France, Russia, and most of Eastern Europe. As with PAL, SECAM is based on a 50-hertz power rate, but it uses a different encoding process. Devised earlier than PAL, its standards reflect earlier technical limitations. See also NTSC.
Secure Electronic Transaction
(SET) The Microsoft standard for safely transmitting Visa or Mastercard information to support electronic commerce over the Internet.
server
On a network, a computer running software that provides data and services to clients over the network. The term server can also apply to a software process, such as an Automation server, that similarly sends information to clients and that appears on the same computer as a client process, or even within the same application.
server lookup
The process by which a content server application finds for a specified data service the names of the appropriate Microsoft Multicast Router, address reservation server, and bandwidth reservation server, along with the Internet Protocol (IP) multicast addresses reserved for global and local announcements for that data service. Because there are likely to be backup machines for the servers and the router, these names can each resolve to more than one actual IP address. For more information, see the MSBDN Services Overview section of the Broadcast Architecture Programmer's Reference. See also IP multicast address assignment.
service provider
In Broadcast Architecture, a business that provides a broadcast data service.
Session Announcement Protocol
(SAP) An Internet protocol for announcements that defines a header in binary format that precedes the Session Description Protocol (SDP) portion of an announcement. A draft document about SAP has been produced by the Internet Engineering Task Force (IETF).
Session Description Protocol
(SDP) A textual Internet protocol for the announcements intended to announce and initiate multimedia sessions. Currently a work in progress, SDP is defined in a draft document produced by the Internet Engineering Task Force (IETF). See also Session Announcement Protocol.
session key
A Triple DES key used to encrypt broadcast data content.
SET
See Secure Electronic Transaction.
set-top box
In standard cable or satellite systems, this device converts and decodes the incoming signal into a form that can be received by a standard television set. The device usually sits on top of the viewer's television.
show reference
Information about a television show in a text data format that specifies such things as the time the show is broadcast, the channel the show is broadcast on, and the show's duration. Show references allow software based on Broadcast Architecture to exchange references to television shows.
show reminder
Tasks in Task Scheduler that remind a user to watch or record a television broadcast. Show reminders can be set by Microsoft WebTV for Windows and by applications developed by independent software vendors.
signal-to-noise ratio
(S/N) The amount of power by which a signal exceeds the amount of channel noise at the same point in transmission. This amount is measured in decibels and indicates the clarity or accuracy with which communication can occur.
smart card
A circuit board the size of a credit card with built-in logic, memory, or firmware that gives it storage and decision-making ability, generally for purposes of purchasing, funds transfer, or identification and validation.
S/N
See signal-to-noise ratio.
source filter
A filter that receives data from a source, such as an MPEG file, and introduces it into a filter graph. Source filters have one or more output pins.
spin lock
A data type that provides a synchronization mechanism for protecting resources shared by kernel-mode threads. A thread acquires a spin lock before accessing protected resources. The spin lock keeps any thread but the one holding the spin lock from using the resource. A thread waiting for the spin lock loops, attempting to acquire the spin lock, until it is released by the thread that holds the lock.
SRB
See stream request block.
station
An establishment equipped for radio or television transmission.
stream
A collection of data sent over a data channel in a sequential fashion. The bytes are typically sent in small packets, which are reassembled into a contiguous stream of data. Alternatively, the process of sending such small packets of data.
stream request block
(SRB) Information necessary for a vertical blanking interval (VBI) minidriver to process data and control requests for the streams it works with. An SRB comprises a command and data associated with that command. A HW_STREAM_REQUEST_BLOCK structure contains all information relating to a specific SRB.
streaming architecture
A model for interconnection of stream-processing components, in which applications dynamically load data as they output it. Dynamic loading means data can be broadcast continuously. See also WDM streaming.
streaming data
Data continuously broadcast to an application. For example, a broadcast client's user might subscribe to continuously broadcast sports scores.
string
Data composed of a sequence of characters, usually representing human-readable text.
stub network
A network that carries packets only to and from local devices. Even if a stub network has paths to more than one network, it does not carry traffic for other networks.
subgenre
In Broadcast Architecture, a subset within a genre, for example science fiction, Western, or soap opera.
super VGA
(SVGA) A video standard established by the Video Electronics Standards Association (VESA) to provide high-resolution color display on IBM-compatible computers. SVGA supports the Video Graphics Array (VGA) standard.
SVGA
See super VGA.
S-video
Video in which chrominance and luminance signals are sent separately. This separate transmission produces a sharper video image than composite video, because it has no color artifacts. For example, S-video has no traveling dots or shimmering along color-change lines.


T

Task Scheduler
A scheduling service and user interface that is available as a common resource with the Microsoft® Windows® 98 operating system. Windows 98 includes Task Scheduler as a Component Object Model (COM) interface. Task Scheduler manages all aspects of job scheduling: starting jobs, enumerating currently running jobs, tracking job status, and so on. In Task Scheduler, the user works with a folder under My Computer called Scheduled Tasks, which lists currently scheduled items and enables creation of new tasks. The Task Scheduler replaces the Microsoft® Windows® 95 System Agent.
TCP/IP
See Transmission Control Protocol/Internet Protocol.
Television System Services
(TSS) An Automation interface designed to enable developers to write Windows 98 – based applications that use broadcast television. TSS provides a user model with password security and interapplication scheduling of television shows for viewing or recording. TSS is designed to be used with the Guide database, the Video control or its underlying Microsoft® DirectShow™ filters, the Video Access server, and Guide database loaders. See also Broadcast Architecture subsystems.
theme
A category to which individual television programs are assigned within the Guide database. A theme allows a program episode to be associated with multiple genre/subgenre pairs.
thread
One of several paths of execution in a program or process in which all paths can execute in parallel. Each thread can perform a different function, or many threads can cooperate to perform a larger task.
time to live
(TTL) A value in the range 0 through 255 that defines the scope within which multicast packets should be sent over a network using Internet Protocol (IP). The scope is defined in terms of how local or remote a packet's destination is. Each router decrements the TTL by one. When the value reaches a predefined lower limit, the router throws the packet away. Current multicast backbone (MBONE) requirements, available at the ftp://ftp.isi.edu/mbone/faq.txt site, define the following standard scopes: local network, 1; local site, 15; region, 63; world, 127. Other settings may have local meaning; for example, 31 might indicate all sites within a particular organization.
transform filter
A filter that modifies the contents of a stream. Transform filters usually have both input and output pins.
Transmission Control Protocol/Internet Protocol
(TCP/IP) A networking protocol that provides reliable communications across interconnected networks made up of computers with diverse hardware architectures and operating systems. The TCP portion of the protocol, a layer above IP, is used to send a reliable, continuous stream of data and includes standards for automatically requesting missing data, reordering IP packets that might have arrived out of order, converting IP datagrams to a streaming protocol, and routing data within a computer to make sure the data gets to the correct application. The IP portion of the protocol includes standards for how computers communicate and conventions for connecting networks and routing traffic. See also User Datagram Protocol/Internet Protocol (UDP/IP).
transponder
A device on a satellite that receives and amplifies uplink signals in radio frequencies that come from an earth station. Once the signal is received, the transponder redirects it back toward its destination earth station within the particular satellite's footprint. Each transponder is responsible for a small frequency range, and a satellite is typically made up of 10 to 40 transponders. Unlike in traditional broadcast television, each transponder has enough bandwidth to carry multiple television channels, as well as data. Any one transponder might carry anywhere from 10 low resolution television channels to 2 high-definition television (HDTV) channels, or some combination. See also multiplexer.
transport layer
The fourth of the seven layers in the International Organization for Standardization's Open Systems Interconnection (OSI) model for standardizing computer-to-computer communications. The transport layer is one level above the network layer and is responsible for error detection and correction, among other tasks. Error correction ensures that the bits delivered to the receiver are the same as the bits transmitted by the sender, in the same order and without modification, loss, or duplication. The transport layer is the highest of the three layers (data link, network, and transport) that help move information from one device to another. See also data link layer.
trigger
A notification that is sent to a broadcast client at specific times during an interactive television show to change enhancement display on the client. For example, you can use triggers to automatically change the content of an enhancement, as in an advertisement rotator.
Triple DES
A method of encryption in which the Data Encryption Standard (DES) algorithm is applied three times in a row using three different session keys. These three keys are combined into one Triple DES session key. Triple DES encryption is much more resilient to differential and plaintext attacks than DES.
TSS
See Television System Services.
tuner
An electronic component that locks onto a selected channel and filters signals such as audio and video from that frequency for amplification and display.
tuning space
A set of nonoverlapping channels that are all available through the same type of physical channel tuner, such as a broadcast receiver card or analog cable tuner. A broadcast client with multiple tuning devices can provide channels from multiple tuning spaces.
twisted-pair cable
A communications medium consisting of two thin, insulated wires, generally made of copper, that are twisted together. Standard telephone connections are often referred to as "twisted pair."


U

unicast
A point-to-point networking model in which a packet is duplicated for each address that needs to receive it. See also multicast.
upstream
One-way data flow from broadcast client to head end. See also downstream.
User Datagram Protocol/Internet Protocol
(UDP/IP) A networking protocol used to send large unidirectional packets across interconnected networks made up of computers with diverse hardware architectures and operating systems. The UDP portion of the protocol, a networking layer above IP, is used to send unidirectional packets of up to 64 kilobytes in size and includes standards for routing data within a single computer so it reaches the correct client application. The IP portion of the protocol includes standards for how computers communicate and conventions for connecting networks and routing traffic. See also Transmission Control Protocol/Internet Protocol.
user mode
Software processing that occurs at the application layer, ring 3.
utility filter
A filter that supports the processing of audio and video without necessarily directly manipulating the broadcast stream. See also renderer filter, source filter, and transform filter.


V

VBI
See vertical blanking interval.
vertical blanking interval
(VBI) The time period in which a television signal is not visible on the screen because of the vertical retrace (that is, the repositioning to top of screen to start a new scan). Data services can be transmitted using a portion of this signal. In a standard NTSC signal, perhaps 10 scan lines are potentially available per channel during the VBI. Each scan line represents a data transmission capacity of about 9600 baud.
VGA
See Video Graphics Array.
Video Access server
An out-of-process server that handles device contention among multiple instances of the ActiveX control for Microsoft WebTV for Windows. Device contention is conflict over which process controls a particular device.
Video control
An ActiveX control in Broadcast Architecture that applications use to control how the Video Access server presents audio and video streams. Unlike the Enhancement Video control, which also displays video, the Video control can be used in World Wide Web pages and stand-alone applications as well as in Microsoft WebTV for Windows. In contrast, the Enhancement Video control can be used only in Hypertext Markup Language (HTML) pages displayed by Microsoft® WebTV® for Windows®. However ,the Enhancement Video control automatically handles the connection between itself and WebTV for Windows, whereas the Video control does not. The Video control is provided with Broadcast Architecture.
Video Graphics Array
(VGA) A video standard created by IBM that supports several modes, including a graphics mode of 640 horizontal pixels by 480 vertical pixels with 2 or 16 simultaneous colors and a graphics mode of 320 horizontal pixels by 200 vertical pixels with 256 colors. The term VGA chip is often used generically to refer to a video controller chip.
VIF
See virtual interface.
virtual device driver
(VxD) A 32-bit, protected-mode driver that manages a system resource, such as a hardware device or installed software, so that more than one application can use the resource at the same time. VxD refers to a general virtual device driver — the x represents the type of device driver. For example, a virtual device driver for a display device is known as a VDD, a virtual device driver for a timer device is a VTD, a virtual device driver for a printer device is a VPD, and so on.
virtual interface
(VIF) A dynamic-link library that a Microsoft Multicast Router calls to package and transmit a stream in the format required by a particular broadcast output device. A virtual interface is valid only for the hardware and software configuration for which it was created, and thus each type of broadcast output device requires a different virtual interface.
VxD
See virtual device driver.


W

WDM
See Windows Driver Model.
WebTV for Windows
See Microsoft WebTV for Windows.
wide area network
(WAN) A communications network that connects geographically separated areas. See also local area network.
WDM streaming
An extension of the Microsoft® DirectShow™ application programming interface (API) based on the Windows Driver Model (WDM). WDM streaming provides the kernel connection and streaming services used by the WDM stream class driver and by components of the Microsoft® Windows NT® and Microsoft Windows® 98 operating systems. In these operating systems, WDM streaming provides low-level services in Ring 0 for the lowest latency streaming. DirectShow provides higher-level features and control.
Windows Driver Model
(WDM) A Microsoft 32-bit driver model based on the driver model within the Microsoft® Windows NT® operating system. WDM provides a common architecture of input/output (I/O) services and device drivers for specific driver classes. Both Windows NT and the Microsoft® Windows® 98 operating system support WDM.
Windows Sockets
(WinSock) An application programming interface that provides access to multiple transport protocols, including Transmission Control Protocol/Internet Protocol (TCP/IP), the Internet standard. WinSock provides a network abstraction layer that allows applications to receive and send network data without requiring information about the network involved. WinSock also supports networking capabilities such as real-time multimedia communications.
World Wide Web
(the Web) A hypertext-based, distributed information system created in Switzerland and used for exploring the Internet. Users may create, edit, or browse hypertext documents on the Web.
wrapper
A function that provides an interface to another function.


Y

YUV
True-color encoding that uses one luminance value (Y) and two chroma values (UV).


README.TXT

For information on system requirements for Broadcast Architecture, see the Client Hardware Requirements section of the the Broadcast Architecture Device-Driver Development Kit (DDK).

NOTE: For the Broadcast Architecture samples to have maximum value, you should have the
      following components installed:

   1. Microsoft  Windows  98, including the optional TV Viewer component.

   2. Microsoft Visual Basic version 5.0. For more information on installing
      and using Visual Basic 5.0, see the Visual Basic 5.0 documentation.

   3. Microsoft Visual C++ version 5.0. For more information on installing
      and using Visual C++ 5.0, including the Microsoft Foundation Class
      (MFC) Library, see the Visual C++ 5.0 documentation.


README.TXT

Loader DLL to demonstrate loading data into the Guide database

SUMMARY
=======

Load is a sample loader that shows how to create a loader that edits data for the Guide database. It is designed to run with version 1.0 of Broadcast Architecture running under the Microsoft Windows 98 operating system.

MORE INFORMATION
================

The following information describes the Load sample.

Requirements
-----------------------------
Load.exe must be compiled using Microsoft Visual C++ 5.0 with Microsoft Foundation Classes (MFC). In addition, the Data Access Objects (DAO) Software Development Kit (SDK) must be installed.

You must configure your environment before compiling Load.exe. First, make sure that the environment variable INCLUDE points to the Visual C++ Include directory, the DAO SDK Include directory, and the MFC Include directory. Similarly, make sure the environment variable LIB points to the Visual C++ Lib directory, the DAO SDK Lib directory, and the MFC Lib directory.

To Compile Load
-----------------------------

Use the following command to compile the sample:

   nmake load.mak

For make options, see the makefile header comments.

If the build tools cannot find Sdkutil.lib, use the Samples\Com\Common sample to build Sdkutil.lib.

To Run Load
-----------------------------

Load runs under the Broadcast Architecture program Loadstub.exe. The first step is to copy Load to the TV Viewer directory on your Windows 98 system. Next, you must add a registry key under HKEY_LOCAL_MACHINE\Software\Microsoft\TV Services\Guide\Loaders. The name of the key is the GUID that you want to use for this loader. Under this new key, add a string value called Name. The data in this entry is the complete path to Load.dll.

Here is an example of a registry entry:

HKEY_LOCAL_MACHINE\Software\Microsoft\TV Services\Guide\Loaders\{1234 9ABC 9998 DDD}
Namec:\Windows\Program Files\TV Viewer\Load.dll

Now you can run Loadstub with the GUID in the /L: command line parameter. Here is the command line for running the loader with the previous registry entry:

loadstub /L:{1234 9ABC 9998 DDD}

Load Files
-------------
Load.cpp is the main program file for the loader. It contains the entry function called from Loadstub and routines to manipulate the database.


CMDPROC.H

/////////////////////////////////////////////////////////////////////////////
// cmdproc.h
// Copyright (C) 1996 Microsoft Corp.
//
//  more flexible replacement for mfc CCommandLineInfo

/////////////////////////////////////////////////////////////////////////////
// CCommandLineInfo

#ifndef CMDPROC_H
#define CMDPROC_H

class CCommandLineProc : public CObject
{
public:
    // process the command line for switch based arguments
    BOOLEAN ProcessCommandLine(int iSC, int &argc, _TCHAR **argv);
protected:
    typedef void (CCommandLineProc::*PMFNCmdProc)(CString &csArg);
    class CArgProcTable {
    public:
        int m_iIDS;  // string resource of command switch
        PMFNCmdProc m_Cmd;    // argument processing function
    };
    friend CArgProcTable;
    static CArgProcTable acapArgs[];
    // remove any desired positional arguments
    virtual BOOLEAN GetPositionalArgs(int &argc, _TCHAR **argv);

    // this function deletes the argument at iPos by copy the remaining
    // elements of argv 1 to the left
    inline void CCommandLineProc::DeleteArg(int iPos, int &argc, _TCHAR **argv)
    {
        for (int k = iPos + 1; k < argc; k++) {
        argv[k - 1] = argv[k];
        }
        argc--;
    }

};

#endif
// end of file - cmdproc.h


CMDPROC2.CPP

// cmdproc.cpp : replacement for mfc CCommandLineInfo
//
//
// This is a part of the Microsoft Foundation Classes C++ library.
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// See the reference for detailed information regarding
// Broadcast Architecture.

#include "stdafx.h"
#include "cmdproc.h"

BOOLEAN
CCommandLineProc::ProcessCommandLine(int iSC, int &argc, _TCHAR **argv)
{
    CString csSwitchChars;
    csSwitchChars.LoadString(iSC);
    CString csParam;

    if(acapArgs[0].m_Cmd == NULL)
{
        return TRUE;
    }
  int i = 1;
    while(i < argc)
{
        csParam = argv[i];
if(!_tcscspn(csParam, csSwitchChars))
{
            // its a switch
// remove flag specifier
csParam = csParam.Right(csParam.GetLength() - 1);
            // find the function for this switch
            CString csSwitch, csArg;

            for(int j = 0; acapArgs[j].m_Cmd != NULL; j++)
{
                csSwitch.LoadString(acapArgs[j].m_iIDS);
                if(!_tcsnccmp(csParam, csSwitch, csSwitch.GetLength()))
{
                    break;
                }
            }
            if(acapArgs[j].m_Cmd != NULL)
{
                csArg = csParam.Right(csParam.GetLength() - csSwitch.GetLength());
                (this->*(acapArgs[j].m_Cmd))(csArg);
                DeleteArg(i, argc, argv);
            }
else
{
                i++;  // skip this one
            }
}
else
{
            // its positional so skip it.
            i++;
        }

}
    return GetPositionalArgs(argc, argv);
}

BOOLEAN
CCommandLineProc::GetPositionalArgs(int &argc, _TCHAR **argv)
{
    // default implementation provides no positional args
    return TRUE;
}


LOAD.CPP

// load.cpp : Guide database loader sample program
//
//
// This is a part of the Microsoft Foundation Classes C++ library.
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// See the reference for detailed information regarding
// Broadcast Architecture.

#include "stdafx.h"
#include "Load.h"
#include "tssutil.h"

/////////////////////////////////////////////////////////////////////////////
// CLoadApp

BEGIN_MESSAGE_MAP(CLoadApp, CWinApp)
//{{AFX_MSG_MAP(CLoadApp)
// NOTE - the ClassWizard will add and remove mapping macros here.
//    DO NOT EDIT what you see in these blocks of generated code!
//}}AFX_MSG_MAP
END_MESSAGE_MAP()

/////////////////////////////////////////////////////////////////////////////
// CLoadApp construction

CLoadApp::CLoadApp()
{
// TODO: add construction code here,
// Place all significant initialization in InitInstance
}

/////////////////////////////////////////////////////////////////////////////
// The one and only CLoadApp object

CLoadApp theApp;

//
// This is the external entry point defined in the .DEF file that is used by
// the generic loader app to call into the Sample loader.
//
extern "C"
{
ExitCodeList APIENTRY
EPG_DBLoad(int &argc, _TCHAR **argv, CdbDBEngine &db, PFNFORCEQUIT pfnForceQuit)
{

    AFX_MANAGE_STATE(AfxGetStaticModuleState());

    ExitCodeList rc = theApp.EPG_DBLoad(argc, argv, db, pfnForceQuit);

if(theApp.m_lpfnDaoTerm)
(*theApp.m_lpfnDaoTerm)();

return rc;
}
};

CLoadApp::CLoadCommandLineProc::CLoadCommandLineProc(void)
{
    m_fPartial = FALSE;
m_csRead = "";
}

void
CLoadApp::CLoadCommandLineProc::Partial(CString &csArg)
// Process the cmd line switch that allows us to be
// told to do a partial update
{
    m_fPartial = TRUE;
    return;
}

void
CLoadApp::CLoadCommandLineProc::Read(CString &csArg)
// Process the cmd line switch that gives a location to read loader data from
{
    m_csRead = csArg;
    return;
}

void
CLoadApp::CLoadCommandLineProc::Help(CString &csArg)
// Display the command line usage
{
    AfxMessageBox(IDS_USAGE, MB_OK | MB_ICONSTOP);
    return;
}

// This table tells the command line processor what to do for each valid argument.
CLoadApp::CLoadCommandLineProc::CArgProcTable
CLoadApp::CLoadCommandLineProc::acapArgs[] =
{
    IDS_SWPARTIAL, (void (CCommandLineProc::*)(class CString &))CLoadApp::CLoadCommandLineProc::Partial,
    IDS_SWREAD, (void (CCommandLineProc::*)(class CString &))CLoadApp::CLoadCommandLineProc::Read,
    IDS_SWHELP, (void (CCommandLineProc::*)(class CString &))CLoadApp::CLoadCommandLineProc::Help,
    -1, NULL,
};

BOOLEAN
CLoadApp::CLoadCommandLineProc::GetPositionalArgs(int &argc, _TCHAR **argv)
{
    return TRUE;
}

// This is the main entry point into the loader class.
ExitCodeList
CLoadApp::EPG_DBLoad(int &argc, _TCHAR **argv, CdbDBEngine &db
, PFNFORCEQUIT pfnForceQuit)
{
ExitCodeListrc;

    if(!m_clpCmds.ProcessCommandLine(IDS_SWITCHCHARS, argc, argv))
return EXIT_USAGE;

theApp.m_pDAODB = &db;
theApp.m_pfnForceQuit = pfnForceQuit;

    try
    {
        if(EXIT_OK != (rc = InitMembers()))
        return (rc);

        rc = ProcessInput(m_clpCmds.m_fPartial, db);

        return (rc);
    }
    catch (CException *e)
    {
        e->Delete();

        return (EXIT_FAIL_CEXCEPTION);
    }
    catch (CdbException cdbe)
    {
return (EXIT_FAIL_DBEXCEPTION);
    }
catch (ExitCodeList rc)
    {
return (rc);
    }
    catch (...)
    {
return (EXIT_FAIL);
    }
}

// This reinitializes certain app class members
ExitCodeList
CLoadApp::InitMembers(void)
{
DWORD rc;

    // Incoming data is all gmt.  Set up app class time info
    // for conversions
    TIME_ZONE_INFORMATION tzi;
    DWORD tzrc;
    tzrc = ::GetTimeZoneInformation(&tzi);

    CTimeSpan bias(0, 0, tzi.Bias, 0);
    switch(tzrc)
{
    case TIME_ZONE_ID_UNKNOWN:
    break;
case TIME_ZONE_ID_DAYLIGHT:
{
CTimeSpan temp(0, 0, tzi.DaylightBias, 0);
bias += temp;
        break;
}
case TIME_ZONE_ID_STANDARD:
{
            CTimeSpan temp(0, 0, tzi.StandardBias, 0);
            bias += temp;
break;
}
    default:
THROWASSERT(0, EXIT_FAIL_GETTIMEZONE);
        break;
}
    m_odtsTimeZoneAdjust.SetDateTimeSpan(bias.GetDays(), bias.GetHours(), bias.GetMinutes(), bias.GetSeconds());
m_codtGuideStartTime.SetStatus(COleDateTime::invalid);
m_codtGuideEndTime.SetStatus(COleDateTime::invalid);

    DWORD dwBytes = sizeof(m_lTuningSpace);
    rc = TSS_GetTuningIDs(SZDTVLOADGUID, (DWORD *)&m_lTuningSpace, dwBytes);
    if((!rc) /*|| (dwBytes != sizeof(m_lTuningSpace)) GFS - How cound this be true?*/)
        return EXIT_FAIL_GETTUNINGSPACE;

m_covTuningSpace = m_lTuningSpace;

    //aux
    rs = NULL;
    r = NULL;
    bp = NULL;
    g = NULL;
    sg = NULL;
    sr = NULL;
    // main
    n = NULL;
    s = NULL;
    c = NULL;
    cp = NULL;
    csr = NULL;
    e = NULL;
    ep = NULL;
    ts = NULL;
    t = NULL;

    return EXIT_OK;
}

ExitCodeList CLoadApp::ProcessInput(BOOLEAN fPartialUpdate, CdbDBEngine &db)
{
    ExitCodeList rc = EXIT_OK;

    COleDateTime m_odtStart(COleDateTime::GetCurrentTime());
    m_covNow = m_odtStart + m_odtsTimeZoneAdjust;

CString csWSP;
csWSP.LoadString(IDS_LOADERWORKSPACE);

    try
    {
OpenTables();

db[csWSP].BeginTrans();

Handle(fPartialUpdate);

        ClearOldEntries(db);  // delete anything from mpg time span that wasn't refreshed.

ClearDanglingRefs(db);  // cleanup unused auxiliary records

BlockCommit(db, EPGLDR_ACTIVE_COMMIT_STARTING, EPGLDR_ACTIVE_COMMIT_ENDING);

CloseTables();
}
    catch (CException *e)
    {
        e->Delete();

db[csWSP].Rollback();

        return (EXIT_FAIL_CEXCEPTION); // failed
    }
    catch (CdbException cdbe)
    {
db[csWSP].Rollback();

return (EXIT_FAIL_DBEXCEPTION);
    }
catch (ExitCodeList rc)
    {
db[csWSP].Rollback();

return (rc);
    }
catch (...)
    {
db[csWSP].Rollback();

return (EXIT_FAIL);
    }

#ifdef _DEBUG
    if (afxTraceFlags & traceDatabase)
    {
        COleDateTime end_parse(COleDateTime::GetCurrentTime());
        COleDateTimeSpan duration(end_parse - m_odtStart);
        afxDump << "end parse. length = " << ((ULONG)duration.GetTotalSeconds()) << "\r\n";
    }
#endif

    return rc;
}

// execute deletes on each table in proper order for
// all records whose last tx hasn't been updated and
// who's attached to stuff that overlaps in the mpg's time frame
void CLoadApp::ClearOldEntries(CdbDBEngine &db)
{
CString csWSP;
csWSP.LoadString(IDS_LOADERWORKSPACE);

    try
    {
CdbDatabase database = db[csWSP][(LONG) 0];
db[csWSP].BeginTrans();

COleDateTime codtStartTimeMinusDay = m_codtGuideStartTime;
COleDateTimeSpan codtsDelta;
codtsDelta.SetDateTimeSpan(1, 0, 0, 0);

codtStartTimeMinusDay -= codtsDelta;

// delete old timeslots with end time < mpg start time
// this removes any showings that are finished
        ExecuteActionQuery(database, IDS_DELETE_EXPIRED_TS, & (COleVariant) m_lTuningSpace, & (COleVariant) codtStartTimeMinusDay);

        // delete unupdated timeslots with last update < now and start time < guide range end time
        // this removes any showings that were in the mpg last time the loader ran
        // but that aren't there now
        ExecuteActionQuery(database, IDS_DELETE_OMITTED_TS, & (COleVariant) m_lTuningSpace,
&m_covNow, & (COleVariant) m_codtGuideStartTime, & (COleVariant) m_codtGuideEndTime);

        // the previous actions may have left episode or channels records which aren't referenced
        // by any time slots.

Commit(db);

#ifdef _DEBUG
        if (afxTraceFlags & traceDatabase)
            TRACE0("clear old entries committed\r\n");
#endif
    }
    catch (CException *e)
    {
        e->Delete();

db[csWSP].Rollback();

#ifdef _DEBUG
afxDump << "ClearOldEntries CException catch handler\r\n";
#endif
        throw e;
    }
    catch (...)
    {
db[csWSP].Rollback();

#ifdef _DEBUG
afxDump << "ClearOldEntries ... catch handler\r\n";
#endif
        throw (EXIT_FAIL);
    }
}

// execute deletes on each table in proper order for
// all auxiliary record which aren't used by anyone
// we now delete these dangling records and this completes the differencing portion
// of the partial update
void CLoadApp::ClearDanglingRefs(CdbDBEngine &db)
{
CString csWSP;
csWSP.LoadString(IDS_LOADERWORKSPACE);

try
{
CdbDatabase database = db[csWSP][(LONG) 0];
db[csWSP].BeginTrans();

        ExecuteActionQuery(database, IDS_DELETE_DANGLING_C);
        ExecuteActionQuery(database, IDS_DELETE_DANGLING_E);
        ExecuteActionQuery(database, IDS_DELETE_DANGLING_S);
ExecuteActionQuery(database, IDS_DELETE_DANGLING_THEME);

Commit(db);

#ifdef _DEBUG
        if (afxTraceFlags & traceDatabase) {
            TRACE0("dangling deletes committed\r\n");
        }
#endif
    }
    catch (CException *e)
    {
        e->Delete();

db[csWSP].Rollback();

#ifdef _DEBUG
afxDump << "ClearDanglingRefs CException catch handler\r\n";
#endif
        throw e;
    }
catch (...)
{
db[csWSP].Rollback();

#ifdef _DEBUG
afxDump << "ClearDanglingRefs ... catch handler\r\n";
#endif
        throw (EXIT_FAIL);
    }
}

// This method executes a query in the database
void
CLoadApp::ExecuteActionQuery(CdbDatabase &qd, int iStringID, COleVariant *p0
, COleVariant *p1, COleVariant *p2, COleVariant *p3)
{
    CString csDelQuery;

  if ((*m_pfnForceQuit)())
throw (EXIT_ABORT);

csDelQuery.LoadString(iStringID);

CdbQueryDef qdbdd;

qdbdd = qd.QueryDefs.Item((LPCTSTR) csDelQuery);
    if (p0 != NULL)
        qdbdd.Parameters[(LONG) 0].SetValue(*p0);
    if (p1 != NULL)
        qdbdd.Parameters[(LONG) 1].SetValue(*p1);
    if (p2 != NULL)
        qdbdd.Parameters[(LONG) 2].SetValue(*p2);
    if (p3 != NULL)
        qdbdd.Parameters[(LONG) 3].SetValue(*p3);

    qdbdd.Execute();

    return;
}

void
CLoadApp::Commit(CdbDBEngine &db, LONG lStartMessage, LONG lEndMessage)
{
UINT uiMessage = RegisterWindowMessage(SZLOADERSTUBGUID);

if(0 != lStartMessage)
::PostMessage(HWND_BROADCAST, uiMessage, lStartMessage, 0);

CString csWSP;
csWSP.LoadString(IDS_LOADERWORKSPACE);
db.Idle();
db[csWSP].CommitTrans();

if(0 != lEndMessage)
::PostMessage(HWND_BROADCAST, uiMessage, lEndMessage, 0);
}

void
CLoadApp::BlockCommit(CdbDBEngine &db, LONG lStartMessage, LONG lEndMessage)
{
UINT uiMessage = RegisterWindowMessage(SZLOADERSTUBGUID);

if(0 != lStartMessage)
::SendMessageTimeout(HWND_BROADCAST, uiMessage, lStartMessage, 0,
SMTO_NORMAL, 5 * 1000, NULL);
CString csWSP;
csWSP.LoadString(IDS_LOADERWORKSPACE);
db.Idle();
db[csWSP].CommitTrans();

if(0 != lEndMessage)
::PostMessage(HWND_BROADCAST, uiMessage, lEndMessage, 0);
}

// Open recordsets for each of the tables
// Set each recordset to proper index
void
CLoadApp::OpenTables(VOID)
{
     // aux
    rs = new CRatingSystemRecordset();
    rs->OpenIndexed(IDS_RS_ADDKEY, dbOpenTable, NULL, 0);

    r = new CRatingRecordset();
    r->OpenIndexed(IDS_R_ADDKEY, dbOpenTable, NULL, 0);

    bp = new CBroadcastPropertyRecordset();
    bp->OpenIndexed(IDS_BP_ADDKEY, dbOpenTable, NULL, 0);

    g = new CGenreRecordset();
    g->OpenIndexed(IDS_G_ADDKEY, dbOpenTable, NULL, 0);

    sg = new CSubGenreRecordset();
    sg->OpenIndexed(IDS_SG_ADDKEY, dbOpenTable, NULL, 0);

    sr = new CStreamTypeRecordset();
    sr->OpenIndexed(IDS_SR_ADDKEY, dbOpenTable, NULL, 0);

    // main
    n = new CNetworkRecordset();
    n->OpenIndexed(IDS_N_ADDKEY, dbOpenTable, NULL, 0);

    s = new CStationRecordset();
    s->OpenIndexed(IDS_S_ADDKEY, dbOpenTable, NULL, 0);

    c = new CChannelTRecordset();
    c->OpenIndexed(IDS_C_ADDKEY, dbOpenTable, NULL, 0);

    cp = new CChannelPropertyRecordset();
    cp->OpenIndexed(IDS_CP_ADDKEY, dbOpenTable, NULL, 0);

    csr = new CChannelStreamRecordset();
    csr->OpenIndexed(IDS_CSR_ADDKEY, dbOpenTable, NULL, 0);

    e = new CEpisodeTRecordset();
    e->OpenIndexed(IDS_E_ADDKEY, dbOpenTable, NULL, 0);

    ep = new CEpisodePropertyRecordset();
    ep->OpenIndexed(IDS_EP_ADDKEY, dbOpenTable, NULL, 0);

    ts = new CTimeSlotRecordset();
    ts->OpenIndexed(IDS_TS_ADDKEY, dbOpenTable, NULL, 0);

    t = new CThemeRecordset();
    t->OpenIndexed(IDS_T_ADDKEY, dbOpenTable, NULL, 0);
}

// close all of the tables
void
CLoadApp::CloseTables(void)
{
    //aux
    if (rs != NULL) {
        rs->CloseRecordset();
        delete rs;
        rs = NULL;
    }
    if (r != NULL) {
        r->CloseRecordset();
        delete r;
        r = NULL;
    }
    if (bp != NULL) {
        bp->CloseRecordset();
        delete bp;
        bp = NULL;
    }
    if (g != NULL) {
        g->CloseRecordset();
        delete g;
        g = NULL;
    }
    if (sg != NULL) {
        sg->CloseRecordset();
        delete sg;
        sg = NULL;
    }
    if (sr != NULL) {
        sr->CloseRecordset();
        delete sr;
        sr = NULL;
    }
    // main
    if (n != NULL) {
        n->CloseRecordset();
        delete n;
        n = NULL;
    }
    if (s != NULL) {
        s->CloseRecordset();
        delete s;
        s = NULL;
    }
    if (c != NULL) {
        c->CloseRecordset();
        delete c;
        c = NULL;
    }
    if (cp != NULL) {
        cp->CloseRecordset();
        delete cp;
        cp = NULL;
    }
    if (csr != NULL) {
        csr->CloseRecordset();
        delete csr;
        csr = NULL;
    }
    if (e != NULL) {
        e->CloseRecordset();
        delete e;
        e = NULL;
    }
    if (ep != NULL) {
        ep->CloseRecordset();
        delete ep;
        ep = NULL;
    }
    if (ts != NULL) {
        ts->CloseRecordset();
        delete ts;
        ts = NULL;
    }
    if (t != NULL) {
        t->CloseRecordset();
        delete t;
        t = NULL;
    }
}

// Put data into the Guide Database
VOID
CLoadApp::Handle(BOOL fPartialUpdate)
{
// Add a station
CStationcs(AFX_RFX_LONG_PSEUDO_NULL, "WGFS", "Sample Station"
, 0// Network ID
, "mylogo"// Logo
, "The Sample station");// Description
s->UpdateRS(cs);

// Add a channel
COleDateTime codtDummy = COleDateTime(1999, 12, 30, 0, 0, 0);
CChannelTcct(AFX_RFX_LONG_PSEUDO_NULL
, -2// Tuning space
, 241// Channel number
, codtDummy// Start time
, codtDummy// End time
, 0// Length
, cs.StationID()// Station ID
, "The Sample Channel"// Description
, 0// Enhancement ID
, 0// Rating ID
, 0// Display mask
, 0// Payment address
, 0// Payment token
, COleDateTime::GetCurrentTime() + m_odtsTimeZoneAdjust); // Last update

c->UpdateRS(cct);

// Add an episode
CEpisodeT cet(AFX_RFX_LONG_PSEUDO_NULL
, "The Sample Show"// Title
, "Bringing you samples from around the world"// Description
, 0// Enhancement ID
, 0// Display mask
, 0// Theme ID
, 0// Rating ID
, 255// Abbreviation
, COleDateTime::GetCurrentTime() + m_odtsTimeZoneAdjust);// last update
e->UpdateRS(cet);

// Put the show in a time slot
// Start the show at the top of the next hour
COleDateTime codtStart = COleDateTime::GetCurrentTime();
codtStart.SetDateTime(codtStart.GetYear(), codtStart.GetMonth(), codtStart.GetDay()
, codtStart.GetHour()+1, 0, 0);
// Make it a half hour show
COleDateTime codtEnd = codtStart + COleDateTimeSpan(0, 0, 30, 0);

ts->UpdateRS(CTimeSlot(AFX_RFX_LONG_PSEUDO_NULL
, cct.ChannelID()// Channel ID
, cet.EpisodeID()// Eppisode ID
, codtStart// Start time
, codtEnd// End time
, 30// Length
, 0// Payment address
, 0// Payment token
, COleDateTime::GetCurrentTime() + m_odtsTimeZoneAdjust// Last update
, FALSE// Pay-per-view
, FALSE// Closed caption
, FALSE// Stereo
, FALSE// Re-run
, FALSE// Tape inhibited
, FALSE// Other properties
, FALSE// Alternate data
, FALSE));// Alternate audio

}


LOAD.H

// Load.h : main header file for the LOAD DLL
//

#ifndef __AFXWIN_H__
#error include 'stdafx.h' before including this file for PCH
#endif

#include "resource.h"// main symbols

// turn off warning about debug info truncation
#pragma warning(disable:4786)

#include <epgldrx.h>
#include <cmdproc.h>
#include "RatingSy.h"
#include "Rating.h"
#include "BrProp.h"
#include "Genre.h"
#include "SubGenre.h"
#include "StreamTy.h"
#include "ChannelT.h"
#include "ChProp.h"
#include "ChanStr.h"
#include "EpisodeT.h"
#include "EpProp.h"
#include "TimeSlot.h"
#include "Station.h"
#include "Network.h"
#include "Theme.h"

typedef unsigned char UBYTE;

#ifdef _DEBUG
#define THROWASSERT(f, errorcode)ASSERT(f)
#endif

#ifdef NDEBUG
#define THROWASSERT(f, errorcode) \
do \
{ \
if (!(f)) \
throw (errorcode); \
} while (0);
#endif

/////////////////////////////////////////////////////////////////////////////
// CLoadApp
// See Load.cpp for the implementation of this class
//

class CLoadApp : public CWinApp
{
public:
CLoadApp();

ExitCodeList EPG_DBLoad(int &argc, _TCHAR **argv, CdbDBEngine &db, PFNFORCEQUIT pfnForceQuit);

// Overrides
// ClassWizard generated virtual function overrides
//{{AFX_VIRTUAL(CLoadApp)
//}}AFX_VIRTUAL

//{{AFX_MSG(CLoadApp)
// NOTE - the ClassWizard will add and remove member functions here.
//    DO NOT EDIT what you see in these blocks of generated code !
//}}AFX_MSG
DECLARE_MESSAGE_MAP()

protected:
    LONGm_lTuningSpace;
    COleVariant m_covTuningSpace, m_covNow;
    COleDateTimeSpan m_odtsTimeZoneAdjust;
    COleDateTimem_codtGuideStartTime, m_codtGuideEndTime;
    WORDm_wGuideLength;

CdbDBEngine *m_pDAODB;
    PFNFORCEQUIT m_pfnForceQuit;

    ExitCodeList InitMembers(void);
ExitCodeList ProcessInput(BOOLEAN fPartialUpdate, CdbDBEngine &db);

VOIDHandle(BOOL fPartialUpdate);

void Commit(CdbDBEngine &db, LONG lStartMessage = 0, LONG lEndMessage = 0);
void BlockCommit(CdbDBEngine &db, LONG lStartMessage = 0, LONG lEndMessage = 0);
    void OpenTables(VOID);
    void ClearOldEntries(CdbDBEngine &db);
    void ClearDanglingRefs(CdbDBEngine &db);
    void ExecuteActionQuery(CdbDatabase &db, int iStringID, COleVariant *p0 = NULL, COleVariant *p1 = NULL, COleVariant *p2 = NULL, COleVariant *p3 = NULL);
    void CloseTables();

    // aux
CRatingSystemRecordset *rs;
    CRatingRecordset *r;
    CBroadcastPropertyRecordset *bp;
    CGenreRecordset *g;
    CSubGenreRecordset *sg;
    CStreamTypeRecordset *sr;
    CThemeRecordset *t;
   // main
    CNetworkRecordset *n;
    CStationRecordset *s;
    CChannelTRecordset *c;
    CChannelPropertyRecordset *cp;
    CChannelStreamRecordset *csr;
    CEpisodeTRecordset *e;
    CEpisodePropertyRecordset *ep;
    CTimeSlotRecordset *ts;

    class CLoadCommandLineProc : public CCommandLineProc
    {
    public:
        BOOLEAN m_fPartial;
        CString m_csRead;
        CLoadCommandLineProc(void);

    protected:
        void Read(CString &csArg);
        void Partial(CString &csArg);
        void Help(CString &csArg);
        friend CCommandLineProc::CArgProcTable;
        BOOLEAN GetPositionalArgs(int &argc, _TCHAR **argv);
    } m_clpCmds;
};

/////////////////////////////////////////////////////////////////////////////


CMDPROC.CPP

/////////////////////////////////////////////////////////////////////////////
// cmdproc.cpp
// Copyright (C) 1996 Microsoft Corp.
//
//  more flexible replacement for mfc CCommandLineInfo

/////////////////////////////////////////////////////////////////////////////
// CCommandLineProc

#include "stdafx.h"
#include "cmdproc.h"

// NOTE: this member should be used from inside a set of try/catch
// since there is a remote chance that some of the string handling
// could throw memory exceptions
BOOLEAN CCommandLineProc::ProcessCommandLine(int iSC, int &argc, _TCHAR **argv)
{
    CString csSwitchChars;
    csSwitchChars.LoadString(iSC);
    CString csParam;

    if (acapArgs[0].m_Cmd == NULL) {
        return TRUE;
    }
  int i = 1;
    while (i < argc) {
        csParam = argv[i];
if (!_tcscspn(csParam, csSwitchChars))
{
            // its a switch
// remove flag specifier
csParam = csParam.Right(csParam.GetLength() - 1);
            // find the function for this switch
            CString csSwitch, csArg;

            for (int j = 0; acapArgs[j].m_Cmd != NULL; j++) {
                csSwitch.LoadString(acapArgs[j].m_iIDS);
                if (!_tcsnccmp(csParam, csSwitch, csSwitch.GetLength())) {
                    break;
                }
            }
            if (acapArgs[j].m_Cmd != NULL) {
                csArg = csParam.Right(csParam.GetLength() - csSwitch.GetLength());
                (this->*(acapArgs[j].m_Cmd))(csArg);
                DeleteArg(i, argc, argv);
            } else {
                i++;  // skip this one
            }
} else {
            // its positional so skip it.
            i++;
        }

}
    return GetPositionalArgs(argc, argv);
}

BOOLEAN CCommandLineProc::GetPositionalArgs(int &argc, _TCHAR **argv)
{
    // default implementation provides no positional args
    return TRUE;
}


RESOURCE.H

//{{NO_DEPENDENCIES}}
// Microsoft Developer Studio generated include file.
// Used by Load.rc
//
#define IDS_SWPARTIAL                   102
#define IDS_SWHELP                      103
#define IDS_SWITCHCHARS                 104
#define IDS_USAGE                       105
#define IDS_S_ADDKEY                    135
#define IDS_BP_ADDKEY                   136
#define IDS_C_ADDKEY                    137
#define IDS_CP_ADDKEY                   138
#define IDS_CSR_ADDKEY                  139
#define IDS_E_ADDKEY                    140
#define IDS_EP_ADDKEY                   141
#define IDS_G_ADDKEY                    142
#define IDS_R_ADDKEY                    143
#define IDS_RS_ADDKEY                   144
#define IDS_SC_ADDKEY                   145
#define IDS_SR_ADDKEY                   146
#define IDS_TS_ADDKEY                   147
#define IDS_SG_ADDKEY                   148
#define IDS_N_ADDKEY                    149
#define IDS_DELETE_GENRE                201
#define IDS_DELETE_STREAM               202
#define IDS_DELETE_EPISODE              203
#define IDS_DELETE_CHANNEL              204
#define IDS_DELETE_DANGLING_BP          205
#define IDS_DELETE_DANGLING_S           206
#define IDS_DELETE_DANGLING_THEME       207
#define IDS_DELETE_DANGLING_E           208
#define IDS_DELETE_DANGLING_C           209
#define IDS_DELETE_EXPIRED_TS           210
#define IDS_DELETE_OMITTED_TS           211
#define IDS_CC                          236
#define IDS_CC_NAME                     237
#define IDS_CC_PICTOGRAM                240
#define IDS_T_ADDKEY                    245
#define IDS_MISC                        246
#define IDS_C_SEEK                      247
#define IDS_STEREO                      249
#define IDS_STEREO_NAME                 250
#define IDS_STEREO_PICTOGRAM            251
#define IDS_PPV                         252
#define IDS_PPV_NAME                    253
#define IDS_PPV_PICTOGRAM               254
#define IDS_RERUN                       255
#define IDS_RERUN_NAME                  256
#define IDS_RERUN_PICTOGRAM             257
#define IDS_RERUN_PARSE                 258
#define IDS_BLACKWHITE                  259
#define IDS_NUDITY                      260
#define IDS_VIOLENCE                    261
#define IDS_ADULT_SITUATIONS            262
#define IDS_ADULT_THEMES                263
#define IDS_ADULT_LANGUAGE              264
#define IDS_DESCRIPTION_START           265
#define IDS_DESCRIPTION_MID             266
#define IDS_DESCRIPTION_END             267
#define IDS_RATING_SYSTEM_NAME          268
#define IDS_RATING_SYSTEM_DESC          269
#define IDS_LOADERWORKSPACE             270
#define IDS_SWREAD                      271

// Next default values for new objects
//
#ifdef APSTUDIO_INVOKED
#ifndef APSTUDIO_READONLY_SYMBOLS
#define _APS_NEXT_RESOURCE_VALUE        129
#define _APS_NEXT_COMMAND_VALUE         32771
#define _APS_NEXT_CONTROL_VALUE         1000
#define _APS_NEXT_SYMED_VALUE           101
#endif
#endif


STDAFX.CPP

// stdafx.cpp : source file that includes just the standard includes
//SSLoad.pch will be the pre-compiled header
//stdafx.obj will contain the pre-compiled type information

#include "stdafx.h"


STDAFX.H

// stdafx.h : include file for standard system include files,
//  or project specific include files that are used frequently, but
//      are changed infrequently
//

#define VC_EXTRALEAN// Exclude rarely-used stuff from Windows headers
#define _AFX_NO_DB_SUPPORT
#define _AFX_NO_DAO_SUPPORT

#include <afxwin.h>         // MFC core and standard components
#include <afxext.h>         // MFC extensions

#ifndef _AFX_NO_OLE_SUPPORT
#include <afxole.h>         // MFC OLE classes
#include <afxdisp.h>        // MFC OLE automation classes
#endif // _AFX_NO_OLE_SUPPORT

#include <dbdao.h>


README.TXT

ActiveX component that schedules a Broadcast Architecture show reminder.

This Readme contains the following sections:
* Summary Briefly describes the sample
* More InformationDetails how to compile and run the sample
* About SCHSAMPDescribes the sample in more detail.
* Using SCHSAMPExplains how to use SCHSAMP from a Web page.

For more information about how to write applications that schedule show reminders, see`` Scheduling Show Reminders `` in the Broadcast Architecture SDK documentation.

SUMMARY
=========
The SCHSAMP sample, Schsamp.dll, is an ActiveX component that schedules a show reminder using the IScheduledItems interface available from Television System Services, Tssadmin.dll. TV Viewer is used to display the reminder dialog when the reminder runs.

SCHSAMP was developed using Visual Basic 5.0.

MORE INFORMATION
================
Before you can compile or use this sample, you must first install the
Broadcasting Architecture. This installs and registers
Microsoft Television System Services and TV Viewer, both of which are
required for SCHSAMP to run.

The following information describes the SCHSAMP sample.

To Compile SCHSAMP
-------------------
Open the SCHSAMP project file, Schsamp.vdp, in Visual Basic 5.0.
From the File menu, select Make SchSamp.dll.

To compile the component into a .Cab file for distribution
on the internet, use the Application Setup Wizard provided with
Visual Basic 5.0. Choose Create Internet Download Setup.

This control is unsigned. If you wish to distribute a version of
SCHSAMP on the Web you should sign the component. For instructions on
how to sign a .Cab file, see the Internet Client SDK.

To Set Up the Programming Environment
----------------------------------------------------
First, create a new ActiveX DLL project. Set the class to global, multiuse. Then set a project reference to the Microsoft Television Services, Tssadmin.dll. This will give you access to the TelevisionServices, TaskTrigger, and ScheduledItems objects. If you are unable to locate Microsoft Television Services in References, check that the optional TV Viewer component of Microsoft(r) Windows(r) 98 is installed on your machine.
You must also set a reference to Microsoft DAO 3.5 Object library. This enables your application to create the DAO workspace required by the ScheduledItems object.

To Run SCHSAMP
---------------
The SCHSAMP sample includes a version of the component that has already
been compiled into a .Cab file for delivery through a web page. The .Cab
file has not been signed, and thus in order to run the sample you must set
security in Internet Explorer 4.0 to allow unsigned controls to run.

To do this, go to the View menu and select Internet Options. Click the
Security tab.  Set Security settings for the appropriate zone.  If you plan
to run SCHSAMP from your machine, this should be Local Intranet zone.

Once the security is properly set, open SHCSAMP.HTML with Internet Explorer 4.0.
The SCHSAMP component will automatically download and install on your machine.
To run the script that sets the show reminder, click the Schedule Reminder button.

-------NOTE --------NOTE ----------NOTE ----------NOTE ---------NOTE ---
Note that you cannot set a reminder for a show that has already occurred.
The HTML Web currently is scripted to set a reminder for the show "Maid to Order"
on 8/5/97 at 3:00PM. If the current date is after 8/5/97, the sample will not run.
To correct this, edit the following lines of the HTML file:

SchSamp.Episode = "Maid to Order"
SchSamp.Network = ""
SchSamp.Duration = "120"
SchSamp.ShowTime = "8/5/97 3:00:00 PM"

Change the preceeding lines to reflect a future episode.

For best results, choose an episode from the
TV Viewer program guide. This will enable SCHSAMP to match the episode in
the Guide database and obtain description and tuning information.
-------NOTE --------NOTE ----------NOTE ----------NOTE ---------NOTE ---

Because SCHSAMP uses the IScheduledItems interface, you cannot use the
Search page of TV Viewer to view a sample set with SCHSAMP. To test whether
the reminder was set, follow the instructions detailed in Schsamp.htm.

SCHSAMP Files
--------------
SCHSAMP.HTML is an HTML/VBScript file uses SCHSAMP to set a show reminder.

SCHSAMP.CAB contains a compiled version of SCHSAMP.

SCHSAMP.VBP is the Visual Basic project file.

SCHSAMP.CLS contains the Visual Basic class module

ABOUT SCHSAMP
===============
SchSamp is an ActiveX component that schedules a TV Viewer reminder for a broadcast show. At a specified amount of time before the show starts, the reminder will run, causing TV Viewer to display a dialog box to the user. It will state that the show is about to start, and offer the user the option to Tune to that channel.
This component could be used, for example, on an television enhancement page to enable users to schedule a reminder for next week's episode.

-------NOTE --------NOTE ----------NOTE ----------NOTE ---------NOTE ---
Reminders that are set by any means other than ITVViewer::SetReminder cannot be viewed from the Search page of TV Viewer when a user selects MyReminders from the Categories list. Neither will a reminder icon appear in that program's details list. However, TV Viewer will still present a reminder dialog when the reminder runs.
-------NOTE --------NOTE ----------NOTE ----------NOTE ---------NOTE ---

USING SCHSAMP
==============
Because SchSamp is implemented as an ActiveX component, it can be called from a variety of programming environments, such as VBScript or Javascript on a Web page, Visual Basic, Java, or C++. The code examples in the following topics use Web-based VBScript to call SchSamp.

-------NOTE --------NOTE ----------NOTE ----------NOTE ---------NOTE ---
The SchSamp component is not signed. In order to run the sample you must set security in your browser to allow unsigned controls to run. For more information on how to do this, see the Readme.txt file installed with SchSamp. For information on how to sign a component for Internet download, see the Internet Client SDK.
-------NOTE --------NOTE ----------NOTE ----------NOTE ---------NOTE ---

The following topics describe how to create an instance of SchSamp, pass in episode data, and set a show reminder for the specified episode.

Inserting SCHSAMP in a Web Page
------------------------------------------------------
You can call the SchSamp component from a Web page. To create an instance of the component, insert the following object tag into the HTML file:

<OBJECT ID="MySchSamp"
CLASSID="CLSID:BE521C45-08DA-11D1-98AE-080009DC95C5"
CODEBASE="SchSamp.CAB#version=1,0,0,0">
</OBJECT>

Set the ID parameter to specify a name for this instance of the control.  In the preceding example, it is set to MySchSamp. The CLASSID parameter lists the unique identifier for the SchSamp class, and must appear exactly as above. The CODEBASE parameter points to the .Cab file that contains the compiled SchSamp component and its supporting files.

Specifying Episode Data
-------------------------------
The SchSamp component contains the following properties.

PropertyData typeDescription
----------------------------------------
EpisodeStringTitle of the episode.
NetworkStringIf applicable, the network on which the episode appears.
DurationStringLength of the episode, in minutes.
ShowTimeStringTime and date that the episode starts.
PreTimeLongThe number of minutes early that the reminder should run.

These properties store data about the episode for which you wish to set a reminder. You must set values for them before you call Schsamp.SetReminder to schedule the show reminder.
The following example uses VBScript in a Web page to set values for the SchSamp properties.

<SCRIPT LANGUAGE = VBScript>
Sub SetIt_OnClick
      'set the show's properties
      SchSamp.Episode = "Maid to Order"
      SchSamp.Network = ""
      SchSamp.Duration = "120"
      SchSamp.ShowTime = "8/5/97 3:00:00 PM"
      SchSamp.PreTime = 5

      'Schedule the reminder
      SchSamp.SetReminder
End Sub
</SCRIPT>

Note that you cannot set a reminder for a show that has already occurred. The HTML file installed with SchSamp is scripted to set a reminder for the show "Maid to Order" on 8/5/97 at 3:00PM. If the current date is after 8/5/97, the sample will not run. To correct this, edit the preceding lines to reflect a future episode:
For best results, choose an episode from the TV Viewer program guide. This will enable SchSamp to match the episode in the Guide database and obtain description and tuning information.

Scheduling the Show Reminder
---------------------------------------
Once the properties of SchSamp are set as described in the Broadcast Architecture SDK documenation topic "Specifying Episode Data", call the SchSamp.SetReminder method to create the show reminder. This is illustrated in the following example.

<SCRIPT LANGUAGE = VBScript>
  'Schedule the reminder
   SchSamp.SetReminder
</SCRIPT>


README.TXT

An MFC sample that connects to and controls TV Viewer.

Summary
=======
TVXSamp is an MFC application that connects to and controls an instance of TV Viewer. The sample has a single dialog box with buttons you can push to test its functionality. On startup, TVXSamp gets a reference to a currently running instance of TV Viewer. It uses this reference to call methods of the TV Viewer dispatch interface, ITVViewer.

For more information, see `` TV Viewer `` and `` Creating TV Viewer Controls ``
in the Broadcast Architecture Programmer's Reference.

More Information
================
The following information describes the TVXSamp sample.

To Compile TVXSamp
------------------
From the command prompt, use the following command:

nmake

To Run TVXSamp
--------------
You must start TV Viewer before you run TVXSamp.exe. Otherwise, TVXSamp will not be able to connect to TV Viewer and a run-time error will occur.

Start TVXSamp.exe either from the command line by typing "TVXSamp", or by double-clicking the TVXSamp icon from Windows Explorer. A dialog box will appear, containing the following buttons:

[Toggle TV Mode]
Toggles TV Viewer between full screen and desktop mode.

[Tune to TV Config]
Tunes TV Viewer to the TV Config channel, 1.

[Tune Back to Previous Channel]
Tunes TV Viewer to the previous channel. This is the same
functionality as a Back button in a Web browser.

TVXSamp Files
=============

Tvdisp.h
This is the header file for the TV Viewer dispatch interface.
It is created from Tvdisp.odl

TVXSamp.h
    This is the main header file for the application.  It includes other
    project specific headers (including Resource.h) and declares the
    CTVXSampApp application class.

TVXSamp.cpp
    This is the main application source file that contains the application
    class CTVXSampApp.

TVXSamp.rc
    This is a listing of all of the Microsoft Windows resources that the
    program uses.  It includes the icons, bitmaps, and cursors that are stored
    in the RES subdirectory.  This file can be directly edited in Microsoft
Developer Studio.

res\TVXSamp.ico
    This is an icon file, which is used as the application's icon.  This
    icon is included by the main resource file TVXSamp.rc.

res\TVXSamp.rc2
    This file contains resources that are not edited by Microsoft
Developer Studio.  You should place all resources not
editable by the resource editor in this file.

TVXSamp.reg
    This is an example .REG file that shows you the kind of registration
    settings the framework will set for you.  You can use this as a .REG
    file to go along with your application.

TVXSamp.odl
    This file contains the Object Description Language source code for the
    type library of your application.

TVXSamp.clw
    This file contains information used by ClassWizard to edit existing
    classes or add new classes.  ClassWizard also uses this file to store
    information needed to create and edit message maps and dialog data
    maps and to create prototype member functions.

/////////////////////////////////////////////////////////////////////////////

AppWizard creates one dialog class and automation proxy class:

TVXSampDlg.h, TVXSampDlg.cpp - the dialog
    These files contain your CTVXSampDlg class.  This class defines
    the behavior of your application's main dialog.  The dialog's
    template is in TVXSamp.rc, which can be edited in Microsoft
Developer Studio.

DlgProxy.h, DlgProxy.cpp - the automation object
    These files contain your CTVXSampDlgAutoProxy class.  This class
    is called the "automation proxy" class for your dialog, because it
    takes care of exposing the automation methods and properties that
    automation controllers can use to access your dialog.  These methods
    and properties are not exposed from the dialog class directly, because
    in the case of a modal dialog-based MFC application it is cleaner and
    easier to keep the OLE automation object separate from the user interface.

/////////////////////////////////////////////////////////////////////////////
Other standard files:

StdAfx.h, StdAfx.cpp
    These files are used to build a precompiled header (PCH) file
    named TVXSamp.pch and a precompiled types file named StdAfx.obj.

Resource.h
    This is the standard header file, which defines new resource IDs.
    Microsoft Developer Studio reads and updates this file.


DLGPROXY.H

// DlgProxy.h : TV Viewer sample application
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
// implementation file
//
//

#if !defined(AFX_DLGPROXY_H__FF52102B_0CE4_11D1_98AE_080009DC95C5__INCLUDED_)
#define AFX_DLGPROXY_H__FF52102B_0CE4_11D1_98AE_080009DC95C5__INCLUDED_

#if _MSC_VER >= 1000
#pragma once
#endif // _MSC_VER >= 1000

class CTVXSampDlg;

/////////////////////////////////////////////////////////////////////////////
// CTVXSampDlgAutoProxy command target

class CTVXSampDlgAutoProxy : public CCmdTarget
{
DECLARE_DYNCREATE(CTVXSampDlgAutoProxy)

CTVXSampDlgAutoProxy();           // protected constructor used by dynamic creation

// Attributes
public:
CTVXSampDlg* m_pDialog;

// Operations
public:

// Overrides
// ClassWizard generated virtual function overrides
//{{AFX_VIRTUAL(CTVXSampDlgAutoProxy)
public:
virtual void OnFinalRelease();
//}}AFX_VIRTUAL

// Implementation
protected:
virtual ~CTVXSampDlgAutoProxy();

// Generated message map functions
//{{AFX_MSG(CTVXSampDlgAutoProxy)
// NOTE - the ClassWizard will add and remove member functions here.
//}}AFX_MSG

DECLARE_MESSAGE_MAP()
DECLARE_OLECREATE(CTVXSampDlgAutoProxy)

// Generated OLE dispatch map functions
//{{AFX_DISPATCH(CTVXSampDlgAutoProxy)
// NOTE - the ClassWizard will add and remove member functions here.
//}}AFX_DISPATCH
DECLARE_DISPATCH_MAP()
DECLARE_INTERFACE_MAP()
};

/////////////////////////////////////////////////////////////////////////////

//{{AFX_INSERT_LOCATION}}
// Microsoft Developer Studio will insert additional declarations immediately before the previous line.

#endif // !defined(AFX_DLGPROXY_H__FF52102B_0CE4_11D1_98AE_080009DC95C5__INCLUDED_)


DLGPROXY.CPP

// DlgProxy.cpp : TV Viewer sample application
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
// implementation file
//

#include "stdafx.h"
#include "TVXSamp.h"
#include "DlgProxy.h"
#include "TVXSampDlg.h"

#ifdef _DEBUG
#define new DEBUG_NEW
#undef THIS_FILE
static char THIS_FILE[] = __FILE__;
#endif

/////////////////////////////////////////////////////////////////////////////
// CTVXSampDlgAutoProxy

IMPLEMENT_DYNCREATE(CTVXSampDlgAutoProxy, CCmdTarget)

CTVXSampDlgAutoProxy::CTVXSampDlgAutoProxy()
{
EnableAutomation();

// To keep the application running as long as an OLE automation
//object is active, the constructor calls AfxOleLockApp.
AfxOleLockApp();

// Get access to the dialog through the application's
//  main window pointer.  Set the proxy's internal pointer
//  to point to the dialog, and set the dialog's back pointer to
//  this proxy.
ASSERT (AfxGetApp()->m_pMainWnd != NULL);
ASSERT_VALID (AfxGetApp()->m_pMainWnd);
ASSERT_KINDOF(CTVXSampDlg, AfxGetApp()->m_pMainWnd);
m_pDialog = (CTVXSampDlg*) AfxGetApp()->m_pMainWnd;
m_pDialog->m_pAutoProxy = this;
}

CTVXSampDlgAutoProxy::~CTVXSampDlgAutoProxy()
{
// To terminate the application when all objects created with
// with OLE automation, the destructor calls AfxOleUnlockApp.
//  Among other things, this will destroy the main dialog
AfxOleUnlockApp();
}

void CTVXSampDlgAutoProxy::OnFinalRelease()
{
// When the last reference for an automation object is released
// OnFinalRelease is called.  The base class will automatically
// deletes the object.  Add additional cleanup required for your
// object before calling the base class.

CCmdTarget::OnFinalRelease();
}

BEGIN_MESSAGE_MAP(CTVXSampDlgAutoProxy, CCmdTarget)
//{{AFX_MSG_MAP(CTVXSampDlgAutoProxy)
// NOTE - the ClassWizard will add and remove mapping macros here.
//}}AFX_MSG_MAP
END_MESSAGE_MAP()

BEGIN_DISPATCH_MAP(CTVXSampDlgAutoProxy, CCmdTarget)
//{{AFX_DISPATCH_MAP(CTVXSampDlgAutoProxy)
// NOTE - the ClassWizard will add and remove mapping macros here.
//}}AFX_DISPATCH_MAP
END_DISPATCH_MAP()

// Note: we add support for IID_ITVXSamp to support typesafe binding
//  from VBA.  This IID must match the GUID that is attached to the
//  dispinterface in the .ODL file.

// {FF521024-0CE4-11D1-98AE-080009DC95C5}
static const IID IID_ITVXSamp =
{ 0xff521024, 0xce4, 0x11d1, { 0x98, 0xae, 0x8, 0x0, 0x9, 0xdc, 0x95, 0xc5 } };

BEGIN_INTERFACE_MAP(CTVXSampDlgAutoProxy, CCmdTarget)
INTERFACE_PART(CTVXSampDlgAutoProxy, IID_ITVXSamp, Dispatch)
END_INTERFACE_MAP()

// The IMPLEMENT_OLECREATE2 macro is defined in StdAfx.h of this project
// {FF521022-0CE4-11D1-98AE-080009DC95C5}
IMPLEMENT_OLECREATE2(CTVXSampDlgAutoProxy, "TVXSamp.Application", 0xff521022, 0xce4, 0x11d1, 0x98, 0xae, 0x8, 0x0, 0x9, 0xdc, 0x95, 0xc5)

/////////////////////////////////////////////////////////////////////////////
// CTVXSampDlgAutoProxy message handlers


RESOURCE.H

//{{NO_DEPENDENCIES}}
// Microsoft Developer Studio generated include file.
// Used by tvxsamp.rc
//
#define IDP_OLE_INIT_FAILED             100
#define IDD_TVXSAMP_DIALOG              102
#define IDR_MAINFRAME                   128
#define IDC_BUTTON1                     1000
#define IDC_BUTTON2                     1001
#define IDC_BUTTON4                     1003

// Next default values for new objects
//
#ifdef APSTUDIO_INVOKED
#ifndef APSTUDIO_READONLY_SYMBOLS
#define _APS_NEXT_RESOURCE_VALUE        129
#define _APS_NEXT_COMMAND_VALUE         32771
#define _APS_NEXT_CONTROL_VALUE         1004
#define _APS_NEXT_SYMED_VALUE           101
#endif
#endif


STDAFX.CPP

// stdafx.cpp : TV Viewer sample application
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
// implementation file
//
//
//TVXSamp.pch will be the pre-compiled header
//stdafx.obj will contain the pre-compiled type information

#include "stdafx.h"


STDAFX.H

// stdafx.h : TV Viewer sample application
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//

#if !defined(AFX_STDAFX_H__FF52102E_0CE4_11D1_98AE_080009DC95C5__INCLUDED_)
#define AFX_STDAFX_H__FF52102E_0CE4_11D1_98AE_080009DC95C5__INCLUDED_

#if _MSC_VER >= 1000
#pragma once
#endif // _MSC_VER >= 1000

#define VC_EXTRALEAN// Exclude rarely-used stuff from Windows headers

#include <afxwin.h>         // MFC core and standard components
#include <afxext.h>         // MFC extensions
#include <afxdisp.h>        // MFC OLE automation classes
#ifndef _AFX_NO_AFXCMN_SUPPORT
#include <afxcmn.h>// MFC support for Windows Common Controls
#endif // _AFX_NO_AFXCMN_SUPPORT

// This macro is the same as IMPLEMENT_OLECREATE, except it passes TRUE
//  for the bMultiInstance parameter to the COleObjectFactory constructor.
//  We want a separate instance of this application to be launched for
//  each OLE automation proxy object requested by automation controllers.
#ifndef IMPLEMENT_OLECREATE2
#define IMPLEMENT_OLECREATE2(class_name, external_name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8) \
AFX_DATADEF COleObjectFactory class_name::factory(class_name::guid, \
RUNTIME_CLASS(class_name), TRUE, _T(external_name)); \
const AFX_DATADEF GUID class_name::guid = \
{ l, w1, w2, { b1, b2, b3, b4, b5, b6, b7, b8 } };
#endif // IMPLEMENT_OLECREATE2

//{{AFX_INSERT_LOCATION}}
// Microsoft Developer Studio will insert additional declarations immediately before the previous line.

#endif // !defined(AFX_STDAFX_H__FF52102E_0CE4_11D1_98AE_080009DC95C5__INCLUDED_)


TVDISP.CPP

// tvdisp.cpp : TV Viewer sample application
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//

#include "stdafx.h"
#include "tvdisp.h"

#ifdef _DEBUG
#define new DEBUG_NEW
#undef THIS_FILE
static char THIS_FILE[] = __FILE__;
#endif

/////////////////////////////////////////////////////////////////////////////
// ITVViewer properties

/////////////////////////////////////////////////////////////////////////////
// ITVViewer operations

void ITVViewer::SetTVMode(BOOL fTVMode)
{
static BYTE parms[] =
VTS_BOOL;
InvokeHelper(0xfa1, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 fTVMode);
}

BOOL ITVViewer::IsTVMode()
{
BOOL result;
InvokeHelper(0xfa2, DISPATCH_METHOD, VT_BOOL, (void*)&result, NULL);
return result;
}

BOOL ITVViewer::IsChannelBarUp()
{
BOOL result;
InvokeHelper(0xfa3, DISPATCH_METHOD, VT_BOOL, (void*)&result, NULL);
return result;
}

BOOL ITVViewer::IsModalDialogUp()
{
BOOL result;
InvokeHelper(0xfa4, DISPATCH_METHOD, VT_BOOL, (void*)&result, NULL);
return result;
}

BOOL ITVViewer::IsLoaderActive()
{
BOOL result;
InvokeHelper(0xfa5, DISPATCH_METHOD, VT_BOOL, (void*)&result, NULL);
return result;
}

DATE ITVViewer::GlobalStartTime()
{
DATE result;
InvokeHelper(0xfa6, DISPATCH_METHOD, VT_DATE, (void*)&result, NULL);
return result;
}

DATE ITVViewer::GlobalEndTime()
{
DATE result;
InvokeHelper(0xfa7, DISPATCH_METHOD, VT_DATE, (void*)&result, NULL);
return result;
}

LPUNKNOWN ITVViewer::ChannelList()
{
LPUNKNOWN result;
InvokeHelper(0xfa8, DISPATCH_METHOD, VT_UNKNOWN, (void*)&result, NULL);
return result;
}

long ITVViewer::ViewerID()
{
long result;
InvokeHelper(0xfa9, DISPATCH_METHOD, VT_I4, (void*)&result, NULL);
return result;
}

void ITVViewer::WantNumKeys(BOOL fWantNumKeys)
{
static BYTE parms[] =
VTS_BOOL;
InvokeHelper(0xfaa, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 fWantNumKeys);
}

void ITVViewer::Tune(long lTuningSpace, long lChannelNumber, long lVideoStream, long lAudioStream, LPCTSTR bsIPStream)
{
static BYTE parms[] =
VTS_I4 VTS_I4 VTS_I4 VTS_I4 VTS_BSTR;
InvokeHelper(0xfab, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 lTuningSpace, lChannelNumber, lVideoStream, lAudioStream, bsIPStream);
}

void ITVViewer::GetCurrentTuningInfo(long* lTuningSpace, long* lChannelNumber, long* lVideoStream, long* lAudioStream, BSTR* pbsIPAddress)
{
static BYTE parms[] =
VTS_PI4 VTS_PI4 VTS_PI4 VTS_PI4 VTS_PBSTR;
InvokeHelper(0xfac, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 lTuningSpace, lChannelNumber, lVideoStream, lAudioStream, pbsIPAddress);
}

void ITVViewer::GetPreviousTuningInfo(long* lTuningSpace, long* lChannelNumber, long* lVideoStream, long* lAudioStream, BSTR* pbsIPAddress)
{
static BYTE parms[] =
VTS_PI4 VTS_PI4 VTS_PI4 VTS_PI4 VTS_PBSTR;
InvokeHelper(0xfad, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 lTuningSpace, lChannelNumber, lVideoStream, lAudioStream, pbsIPAddress);
}

void ITVViewer::SetReminder(LPUNKNOWN pEpisode, BOOL bRecord)
{
static BYTE parms[] =
VTS_UNKNOWN VTS_BOOL;
InvokeHelper(0xfae, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 pEpisode, bRecord);
}

BOOL ITVViewer::HasReminder(LPUNKNOWN pEpisode, BOOL bRecord)
{
BOOL result;
static BYTE parms[] =
VTS_UNKNOWN VTS_BOOL;
InvokeHelper(0xfaf, DISPATCH_METHOD, VT_BOOL, (void*)&result, parms,
pEpisode, bRecord);
return result;
}

void ITVViewer::DeleteReminder(LPUNKNOWN pEpisode, BOOL bRecord)
{
static BYTE parms[] =
VTS_UNKNOWN VTS_BOOL;
InvokeHelper(0xfb0, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 pEpisode, bRecord);
}

BOOL ITVViewer::HasEnhancement(LPUNKNOWN pEpisode)
{
BOOL result;
static BYTE parms[] =
VTS_UNKNOWN;
InvokeHelper(0xfb1, DISPATCH_METHOD, VT_BOOL, (void*)&result, parms,
pEpisode);
return result;
}

BOOL ITVViewer::IsCC()
{
BOOL result;
InvokeHelper(0xfb2, DISPATCH_METHOD, VT_BOOL, (void*)&result, NULL);
return result;
}

/////////////////////////////////////////////////////////////////////////////
// ITVControl properties

/////////////////////////////////////////////////////////////////////////////
// ITVControl operations

BOOL ITVControl::OnIdle()
{
BOOL result;
InvokeHelper(0xbb9, DISPATCH_METHOD, VT_BOOL, (void*)&result, NULL);
return result;
}

void ITVControl::Tune(long ltsNew, long lcnNew, long lvsNew, long lasNew, LPCTSTR bsIPNew, long ltsPrev, long lcnPrev, long lvsPrev, long lasPrev, LPCTSTR bsIPPrev)
{
static BYTE parms[] =
VTS_I4 VTS_I4 VTS_I4 VTS_I4 VTS_BSTR VTS_I4 VTS_I4 VTS_I4 VTS_I4 VTS_BSTR;
InvokeHelper(0xbba, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 ltsNew, lcnNew, lvsNew, lasNew, bsIPNew, ltsPrev, lcnPrev, lvsPrev, lasPrev, bsIPPrev);
}

void ITVControl::TearDown()
{
InvokeHelper(0xbbb, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

void ITVControl::SyncEvent(long iEvent, LPCTSTR pParm1, LPCTSTR pParm2)
{
static BYTE parms[] =
VTS_I4 VTS_BSTR VTS_BSTR;
InvokeHelper(0xbbc, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 iEvent, pParm1, pParm2);
}

void ITVControl::EpisodeStatusChanged(long iChange, LPUNKNOWN pEpi)
{
static BYTE parms[] =
VTS_I4 VTS_UNKNOWN;
InvokeHelper(0xbbd, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 iChange, pEpi);
}

void ITVControl::PowerChange(BOOL bPowerOn, BOOL bUIAllowed)
{
static BYTE parms[] =
VTS_BOOL VTS_BOOL;
InvokeHelper(0xbbf, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 bPowerOn, bUIAllowed);
}

void ITVControl::OnTVFocus()
{
InvokeHelper(0xbc0, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

void ITVControl::SetOutput(LPCTSTR bsDeviceName)
{
static BYTE parms[] =
VTS_BSTR;
InvokeHelper(0xbc1, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 bsDeviceName);
}

BOOL ITVControl::GetCC()
{
BOOL result;
InvokeHelper(0xbc2, DISPATCH_METHOD, VT_BOOL, (void*)&result, NULL);
return result;
}

void ITVControl::SetCC(BOOL bCC)
{
static BYTE parms[] =
VTS_BOOL;
InvokeHelper(0xbc3, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 bCC);
}


TVDISP.H

// tvdisp.h : TV Viewer sample application
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//
/////////////////////////////////////////////////////////////////////////////
// ITVViewer wrapper class

class ITVViewer : public COleDispatchDriver
{
public:
ITVViewer() {}// Calls COleDispatchDriver default constructor
ITVViewer(LPDISPATCH pDispatch) : COleDispatchDriver(pDispatch) {}
ITVViewer(const ITVViewer& dispatchSrc) : COleDispatchDriver(dispatchSrc) {}

// Attributes
public:

// Operations
public:
void SetTVMode(BOOL fTVMode);
BOOL IsTVMode();
BOOL IsChannelBarUp();
BOOL IsModalDialogUp();
BOOL IsLoaderActive();
DATE GlobalStartTime();
DATE GlobalEndTime();
LPUNKNOWN ChannelList();
long ViewerID();
void WantNumKeys(BOOL fWantNumKeys);
void Tune(long lTuningSpace, long lChannelNumber, long lVideoStream, long lAudioStream, LPCTSTR bsIPStream);
void GetCurrentTuningInfo(long* lTuningSpace, long* lChannelNumber, long* lVideoStream, long* lAudioStream, BSTR* pbsIPAddress);
void GetPreviousTuningInfo(long* lTuningSpace, long* lChannelNumber, long* lVideoStream, long* lAudioStream, BSTR* pbsIPAddress);
void SetReminder(LPUNKNOWN pEpisode, BOOL bRecord);
BOOL HasReminder(LPUNKNOWN pEpisode, BOOL bRecord);
void DeleteReminder(LPUNKNOWN pEpisode, BOOL bRecord);
BOOL HasEnhancement(LPUNKNOWN pEpisode);
BOOL IsCC();
};
/////////////////////////////////////////////////////////////////////////////
// ITVControl wrapper class

class ITVControl : public COleDispatchDriver
{
public:
ITVControl() {}// Calls COleDispatchDriver default constructor
ITVControl(LPDISPATCH pDispatch) : COleDispatchDriver(pDispatch) {}
ITVControl(const ITVControl& dispatchSrc) : COleDispatchDriver(dispatchSrc) {}

// Attributes
public:

// Operations
public:
BOOL OnIdle();
void Tune(long ltsNew, long lcnNew, long lvsNew, long lasNew, LPCTSTR bsIPNew, long ltsPrev, long lcnPrev, long lvsPrev, long lasPrev, LPCTSTR bsIPPrev);
void TearDown();
void SyncEvent(long iEvent, LPCTSTR pParm1, LPCTSTR pParm2);
void EpisodeStatusChanged(long iChange, LPUNKNOWN pEpi);
void PowerChange(BOOL bPowerOn, BOOL bUIAllowed);
void OnTVFocus();
void SetOutput(LPCTSTR bsDeviceName);
BOOL GetCC();
void SetCC(BOOL bCC);
};


TVDISPID.H

// tvdispid.h : TV Viewer sample application
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.

#ifndef __TVDISPID_H__
#define __TVDISPID_H__

#ifdef __MKTYPLIB__

// Sync event notifications
typedef enum tvsyncevent
{
//Loader sync events
//Corresponding messages from epgldrx.h
//EPGLDR_STARTING
//EPGLDR_ACTIVE_COMMIT_STARTING
//EPGLDR_ACTIVE_COMMIT_ENDING
//EPGLDR_PASSIVE_COMMIT_STARTING
//EPGLDR_PASSIVE_COMMIT_ENDING
//EPGLDR_ENDING

//Viewer sync events
keViewerLogin= 107,
keViewerChange= 108,
keCurrentViewerChannelListChange= 109,

//Other sync events
keSysTimeChange= 110
} TVSYNCEVENT;

// EpisodeStatusChanged notification enums
typedef enum episodestatus
{
keReminderStatus= 1,
kePurchaseStatus= 2,
keDSSEmailStatus= 3
} EPISODESTATUS;

#endif

// Dispatch IDs

// ITVControl

#define dispidOnIdle3001
#define dispidTuneControl3002
#define dispidTearDown3003
#define dispidSyncEvent3004
#define dispidEpisodeStatusChanged3005
#define dispidPowerChange3007
#define dispidOnTVFocus   3008
#define dispidTVSetOutput3009
#define dispidGetCC   3010
#define dispidSetCC   3011

// ITVExplorer

#define dispidSetTVMode4001
#define dispidIsTVMode4002
#define dispidIsChannelBarUp4003
#define dispidIsModalDialogUp4004
#define dispidIsLoaderActive4005
#define dispidGlobalStartTime4006
#define dispidGlobalEndTime4007
#define dispidChannelList4008
#define dispidViewerID4009
#define dispidWantNumKeys4010
#define dispidTVXTune4011
#define dispidGetCurrentTuningInfo4012
#define dispidGetPreviousTuningInfo4013
#define dispidSetReminder4014
#define dispidHasReminder4015
#define dispidDeleteReminder4016
#define dispidHasEnhancement            4017
#define dispidIsCC                      4018

#endif // __TVDISPID_H__


TVXSAMP.CPP

//---------------------------------------------------------------------------------
// TVXSampDlg.cpp : TV Viewer sample application
//---------------------------------------------------------------------------------
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For more information about writing applications that interact
// with TV Viewer, see `` Creating TV Viewer Controls ``
// in the Broadcast Architecture Programmer's Reference.
//
//

#include "stdafx.h"
#include "TVXSamp.h"
#include "TVXSampDlg.h"
#include "Tvdisp.h"
#include <initguid.h>

DEFINE_GUID(IID_ITVViewer,0x3F8A2EA1L,0xC171,0x11CF,0x86,0x8C,0x00,0x80,0x5F,0x2C,0x11,0xCE);
DEFINE_GUID(IID_ITVDisp, 0x3F8A2EA1L, 0xC171,0x11cf,0x86,0x8C,0x00,0x80,0x5F,0x2C,0x11,0xCE);
DEFINE_GUID(CLSID_TVViewer,0x5543DD10L,0xB41D,0x11CF,0x86,0x82,0x00,0x80,0x5F,0x2C,0x11,0xCE);

extern ITVViewer *TVX;

#ifdef _DEBUG
#define new DEBUG_NEW
#undef THIS_FILE
static char THIS_FILE[] = __FILE__;
#endif

/////////////////////////////////////////////////////////////////////////////
// CTVXSampApp

BEGIN_MESSAGE_MAP(CTVXSampApp, CWinApp)
//{{AFX_MSG_MAP(CTVXSampApp)
// NOTE - the ClassWizard will add and remove mapping macros here.
//    DO NOT EDIT what you see in these blocks of generated code!
//}}AFX_MSG
ON_COMMAND(ID_HELP, CWinApp::OnHelp)
END_MESSAGE_MAP()

/////////////////////////////////////////////////////////////////////////////
// CTVXSampApp construction

CTVXSampApp::CTVXSampApp()
{
// TODO: add construction code here,
// Place all significant initialization in InitInstance
}

/////////////////////////////////////////////////////////////////////////////
// The one and only CTVXSampApp object

CTVXSampApp theApp;

/////////////////////////////////////////////////////////////////////////////
// CTVXSampApp initialization

BOOL CTVXSampApp::InitInstance()
{
// Initialize OLE libraries
if (!AfxOleInit())
{
AfxMessageBox(IDP_OLE_INIT_FAILED);
return FALSE;
}

AfxEnableControlContainer();

//--------------< code that gets a reference to TV Viewer >-------------
//---------------------------------------------------------------------------------
/*
The following code gets a reference to TV Viewer which
TVXSamp uses to call the ITVViewer methods.
This is implemented during TVXSamp's initialization
to ensure that it connects to TV Viewer before
calling the ITVViewer methods.

TV Viewer must be running or else the following code will fail.
*/
HRESULT hr = 0;
IUnknown *punk;
IDispatch *dispatch;

hr = GetActiveObject(CLSID_TVViewer,NULL,&punk);
if (SUCCEEDED(hr))
{
hr=punk->QueryInterface(IID_IDispatch,(void**) &dispatch);
punk->Release();
if (SUCCEEDED(hr))
{
TVX=new ITVViewer(dispatch);
}
}

// Standard initialization
// If you are not using these features and wish to reduce the size
//  of your final executable, you should remove from the following
//  the specific initialization routines you do not need.

// Parse the command line to see if launched as OLE server
if (RunEmbedded() || RunAutomated())
{
// Register all OLE server (factories) as running.  This enables the
//  OLE libraries to create objects from other applications.
COleTemplateServer::RegisterAll();
}
else
{
// When a server application is launched stand-alone, it is a good idea
//  to update the system registry in case it has been damaged.
COleObjectFactory::UpdateRegistryAll();
}

CTVXSampDlg dlg;
m_pMainWnd = &dlg;
int nResponse = dlg.DoModal();
if (nResponse == IDOK)
{
// TODO: Place code here to handle when the dialog is
//  dismissed with OK

}
else if (nResponse == IDCANCEL)
{
// TODO: Place code here to handle when the dialog is
//  dismissed with Cancel

}

// Since the dialog has been closed, return FALSE so that we exit the
//  application, rather than start the application's message pump.
return FALSE;
}


TVXSAMP.H

// TVXSamp.h : TV Viewer sample application
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//
//
//

#if !defined(AFX_TVXSAMP_H__FF521027_0CE4_11D1_98AE_080009DC95C5__INCLUDED_)
#define AFX_TVXSAMP_H__FF521027_0CE4_11D1_98AE_080009DC95C5__INCLUDED_

#if _MSC_VER >= 1000
#pragma once
#endif // _MSC_VER >= 1000

#ifndef __AFXWIN_H__
#error include 'stdafx.h' before including this file for PCH
#endif

#include "resource.h"// main symbols

/////////////////////////////////////////////////////////////////////////////
// CTVXSampApp:
// See TVXSamp.cpp for the implementation of this class
//

class CTVXSampApp : public CWinApp
{
public:
CTVXSampApp();

// Overrides
// ClassWizard generated virtual function overrides
//{{AFX_VIRTUAL(CTVXSampApp)
public:
virtual BOOL InitInstance();
//}}AFX_VIRTUAL

// Implementation

//{{AFX_MSG(CTVXSampApp)
// NOTE - the ClassWizard will add and remove member functions here.
//    DO NOT EDIT what you see in these blocks of generated code !
//}}AFX_MSG
DECLARE_MESSAGE_MAP()
};

/////////////////////////////////////////////////////////////////////////////

//{{AFX_INSERT_LOCATION}}
// Microsoft Developer Studio will insert additional declarations immediately before the previous line.

#endif // !defined(AFX_TVXSAMP_H__FF521027_0CE4_11D1_98AE_080009DC95C5__INCLUDED_)


TVXSAMPDLG.CPP

//---------------------------------------------------------------------------------
// TVXSampDlg.cpp : TV Viewer sample application
//---------------------------------------------------------------------------------
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For more information about writing applications that interact
// with TV Viewer, see `` Creating TV Viewer Controls ``
// in the Broadcast Architecture Programmer's Reference.
//
//

#include "stdafx.h"
#include "TVXSamp.h"
#include "TVXSampDlg.h"
#include "DlgProxy.h"
#include "Tvdisp.h"
#include <atlbase.h>

#ifdef _DEBUG
#define new DEBUG_NEW
#undef THIS_FILE
static char THIS_FILE[] = __FILE__;
#endif

ITVViewer *TVX;

/////////////////////////////////////////////////////////////////////////////
// CTVXSampDlg dialog

IMPLEMENT_DYNAMIC(CTVXSampDlg, CDialog);

CTVXSampDlg::CTVXSampDlg(CWnd* pParent /*=NULL*/)
: CDialog(CTVXSampDlg::IDD, pParent)
{
//{{AFX_DATA_INIT(CTVXSampDlg)
// NOTE: the ClassWizard will add member initialization here
//}}AFX_DATA_INIT
// Note that LoadIcon does not require a subsequent DestroyIcon in Win32
m_hIcon = AfxGetApp()->LoadIcon(IDR_MAINFRAME);
m_pAutoProxy = NULL;
}

CTVXSampDlg::~CTVXSampDlg()
{
// If there is an automation proxy for this dialog, set
//  its back pointer to this dialog to NULL, so it knows
//  the dialog has been deleted.
if (m_pAutoProxy != NULL)
m_pAutoProxy->m_pDialog = NULL;
}

void CTVXSampDlg::DoDataExchange(CDataExchange* pDX)
{
CDialog::DoDataExchange(pDX);
//{{AFX_DATA_MAP(CTVXSampDlg)
// NOTE: the ClassWizard will add DDX and DDV calls here
//}}AFX_DATA_MAP
}

BEGIN_MESSAGE_MAP(CTVXSampDlg, CDialog)
//{{AFX_MSG_MAP(CTVXSampDlg)
ON_WM_PAINT()
ON_WM_QUERYDRAGICON()
ON_WM_CLOSE()
ON_BN_CLICKED(IDC_BUTTON1, OnButton1)
ON_BN_CLICKED(IDC_BUTTON2, OnButton2)
ON_BN_CLICKED(IDC_BUTTON4, OnButton4)
//}}AFX_MSG_MAP
END_MESSAGE_MAP()

/////////////////////////////////////////////////////////////////////////////
// CTVXSampDlg message handlers

BOOL CTVXSampDlg::OnInitDialog()
{
CDialog::OnInitDialog();

// Set the icon for this dialog.  The framework does this automatically
//  when the application's main window is not a dialog
SetIcon(m_hIcon, TRUE);// Set big icon
SetIcon(m_hIcon, FALSE);// Set small icon

// TODO: Add extra initialization here

return TRUE;  // return TRUE  unless you set the focus to a control
}

// If you add a minimize button to your dialog, you will need the code below
//  to draw the icon.  For MFC applications using the document/view model,
//  this is automatically done for you by the framework.

void CTVXSampDlg::OnPaint()
{
if (IsIconic())
{
CPaintDC dc(this); // device context for painting

SendMessage(WM_ICONERASEBKGND, (WPARAM) dc.GetSafeHdc(), 0);

// Center icon in client rectangle
int cxIcon = GetSystemMetrics(SM_CXICON);
int cyIcon = GetSystemMetrics(SM_CYICON);
CRect rect;
GetClientRect(&rect);
int x = (rect.Width() - cxIcon + 1) / 2;
int y = (rect.Height() - cyIcon + 1) / 2;

// Draw the icon
dc.DrawIcon(x, y, m_hIcon);
}
else
{
CDialog::OnPaint();
}
}

// The system calls this to obtain the cursor to display while the user drags
//  the minimized window.
HCURSOR CTVXSampDlg::OnQueryDragIcon()
{
return (HCURSOR) m_hIcon;
}

// Automation servers should not exit when a user closes the UI
//  if a controller still holds on to one of its objects.  These
//  message handlers make sure that if the proxy is still in use,
//  then the UI is hidden but the dialog remains around if it
//  is dismissed.

void CTVXSampDlg::OnClose()
{
if (CanExit())
CDialog::OnClose();
}

void CTVXSampDlg::OnOK()
{
if (CanExit())
CDialog::OnOK();
}

void CTVXSampDlg::OnCancel()
{
if (CanExit())
CDialog::OnCancel();
}

BOOL CTVXSampDlg::CanExit()
{
// If the proxy object is still around, then the automation
//  controller is still holding on to this application.  Leave
//  the dialog around, but hide its UI.
if (m_pAutoProxy != NULL)
{
ShowWindow(SW_HIDE);
return FALSE;
}

return TRUE;
}

//-----------< event handler that toggles TV Viewer mode >-----------
//---------------------------------------------------------------------------------
/*
The following code implements an event handler
that toggles TV Viewer between desktop and full
screen mode when the user clicks Button1. It checks
which mode TV Viewer is displaying in, and toggles
it to the other mode. For example, if TV Viewer is
in desktop mode, this method sets it to full screen
mode and vide versa.
*/

void CTVXSampDlg::OnButton1()
{

//check whether TV Viewer is in
//full screen mode
if (TVX->IsTVMode())
{
//if it is,
//change the mode to desktop
TVX->SetTVMode(false);
}
else
{
//if it is not,
//change the mode to full screen
TVX->SetTVMode(true);
}

}

//-----< event handler that tunes TV Viewer to a new channel >------
//---------------------------------------------------------------------------------
/*
The following code implements an event handler
that tunes TV Viewer to the TV configuration
channel when they click Button2.

The TV configuration channel was chosen for
this example because it is installed with TV Viewer
and is present on all client machines.
*/
void CTVXSampDlg::OnButton2()
{

//Tune TVViewer to channel 1 of tuning space -2
//the audio and video substreams have been set to
//-1, causing TV Viewer to use the default values.

TVX->Tune(-2,1,-1,-1,NULL);

}

//---------< event handler that tunes to a previous channel >-----------
//---------------------------------------------------------------------------------
/*
The following code implements an event handler that
tunes TV Viewer to the previously displayed channel
when the user clicks Button4.
*/

void CTVXSampDlg::OnButton4()
{
long lTuningSpacePrev;
long lChannelNumberPrev;
long lAudioStreamPrev;
long lVideoStreamPrev;
BSTR bstrIPAddressPrev;

//get the tuning information about the previous channel
//from TV Viewer
TVX->GetPreviousTuningInfo(&lTuningSpacePrev, &lChannelNumberPrev,
 &lVideoStreamPrev, &lAudioStreamPrev, &bstrIPAddressPrev);

if ((lTuningSpacePrev != NULL) && (lChannelNumberPrev != NULL))
{
//Tune TV Viewer to the previous channel
TVX->Tune(lTuningSpacePrev, lChannelNumberPrev,
lVideoStreamPrev, lAudioStreamPrev, (LPCTSTR) bstrIPAddressPrev);
}

}


TVXSAMPDLG.H

// TVXSampDlg.h : TV Viewer sample application
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//
//
//

#if !defined(AFX_TVXSAMPDLG_H__FF521029_0CE4_11D1_98AE_080009DC95C5__INCLUDED_)
#define AFX_TVXSAMPDLG_H__FF521029_0CE4_11D1_98AE_080009DC95C5__INCLUDED_

#if _MSC_VER >= 1000
#pragma once
#endif // _MSC_VER >= 1000

class CTVXSampDlgAutoProxy;

/////////////////////////////////////////////////////////////////////////////
// CTVXSampDlg dialog

class CTVXSampDlg : public CDialog
{
DECLARE_DYNAMIC(CTVXSampDlg);
friend class CTVXSampDlgAutoProxy;

// Construction
public:
CTVXSampDlg(CWnd* pParent = NULL);// standard constructor
virtual ~CTVXSampDlg();

// Dialog Data
//{{AFX_DATA(CTVXSampDlg)
enum { IDD = IDD_TVXSAMP_DIALOG };
// NOTE: the ClassWizard will add data members here
//}}AFX_DATA

// ClassWizard generated virtual function overrides
//{{AFX_VIRTUAL(CTVXSampDlg)
protected:
virtual void DoDataExchange(CDataExchange* pDX);// DDX/DDV support
//}}AFX_VIRTUAL

// Implementation
protected:
CTVXSampDlgAutoProxy* m_pAutoProxy;
HICON m_hIcon;

BOOL CanExit();

// Generated message map functions
//{{AFX_MSG(CTVXSampDlg)
virtual BOOL OnInitDialog();
afx_msg void OnPaint();
afx_msg HCURSOR OnQueryDragIcon();
afx_msg void OnClose();
virtual void OnOK();
virtual void OnCancel();
afx_msg void OnButton1();
afx_msg void OnButton2();
afx_msg void OnButton4();
afx_msg void OnSetReminder();
//}}AFX_MSG
DECLARE_MESSAGE_MAP()
};

//{{AFX_INSERT_LOCATION}}
// Microsoft Developer Studio will insert additional declarations immediately before the previous line.

#endif // !defined(AFX_TVXSAMPDLG_H__FF521029_0CE4_11D1_98AE_080009DC95C5__INCLUDED_)


README.TXT

------------------------------------------------------------------
    Microsoft Broadcast Architecture SDK UseVideo Readme File
                         August 1997
------------------------------------------------------------------

             (c) Copyright Microsoft Corporation, 1997

CONTENTS
========

Using the Video ActiveX Control

SUMMARY
=======

The UseVideo samples demonstrate presenting audio and video
in an application, a Web browser, and in a control you create.
The following four programs are contained in the UseVideo sample:

1. Video Test Project (VidCntrl) demonstrates a project containing a
   standard Visual Basic form that hosts and manipulates an instance
   of the Video ActiveX control.

2. Video Web Page (WebTune) demonstrates embedding and using the
   Video ActiveX control in a Web page.

3. Video Test Control (Vid_Tune) demonstrates creating a control that
   contains the Video ActiveX control as a constituent control.

4. Video MFC Test describes building an application for Windows with
   C++ classes from the Microsoft Foundation Class Library (MFC).

In addition to presenting audio and video, these samples show how to embed
a Video ActiveX control in your program and how to select different devices
to provide input to such a control. If your computer contains a tuner card,
these samples show how to tune to a channel.

/////////////////////////////////////////////////////////////////////////////
MORE INFORMATION
================

The following information describes running the UseVideo samples.
For information on system requirements, see the Client Hardware Requirements
section of the the Broadcast Architecture Device-Driver Development Kit (DDK).

NOTE: For these samples to have maximum value, you should have the
      following components installed:

   1. Microsoft  Windows  98, including the optional TV Viewer component.

   2. Microsoft Visual Basic version 5.0. For more information on installing
      and using Visual Basic 5.0, see the Visual Basic 5.0 documentation.

   3. Microsoft Visual C++ version 5.0. For more information on installing
      and using Visual C++ 5.0, including the Microsoft Foundation Class
      (MFC) Library, see the Visual C++ 5.0 documentation.

/////////////////////////////////////////////////////////////////////////////
To Run VidCntrl
-----------------------------

1. Start Microsoft Visual Basic 5.0.

2. When the New Project dialog box appears, select the Existing tab and
   open the VidCntrl.vbp project file.

3. From the Run menu, select Start.

4. When the Video Control Test form appears in run mode, click the
   File Source (Async.) item in the list box to select it for the
   video control s input source. Enter the file name of a particular
   MPEG-1 file along with the required path to locate such file in
   the text box and click the Set Input command button to assign the
   file you specified as the input source for audio and video. Click the
   Play button to play the file, click the Pause button to temporarily
   suspend playing, click the Stop command button to stop the file.
   Click the Volume slider to change the intensity of the video control s
   sound and the Balance slider to change the video control s stereo balance.

5. If your computer contains a tuner card for analog television, click
   the WDM TvTuner item in the list box to select it for the video control s
   input source. Enter a channel number in the text box and click the
   Set Input button to tune your card to the channel number you specified.

VidCntrl Files
------------

VidCntrl.frm
    This file contains the form image in addition to the images of all the
    elements on the form and the code to manipulate the video control.
    The form's code uses the following properties and methods of the video control
    and other objects associated with video control:
    a. Declares and allocates storage for variables of BPCDevices and
       BPCDeviceBase object types.
    b. Obtains a reference to each device of the video control's Devices property.
    c. Obtains the name of each device with the BPCDeviceBase Name property.
    d. Determines if the computer contains any tuner cards that supports the tuning
       space for Analog Cable TV with the video control's TSDeviceCount method.
    e. If so, tunes to a channel with the video control's Tune method.
    f. Sets the video control's Input property equal to one of the devices in
       the video control's Devices property.
    g. Determines if the video control's input source is from a tuner with the
       BPCDeviceBase HasChannel property.
    h. If so, sets the channel number of the tuner with the BPCDeviceBase Channel
       property.
    i. Determines if the the video control's input source is from a file with the
       BPCDeviceBase HasFilename property.
    j. If so, sets the name of the file with the BPCDeviceBase filename property.
    k. For file sources, plays, pauses, stops, changes the volume and balance with the
       video control's Run, Pause, Stop, Volume, and Balance properties respectively.

VidCntrl.vbp
    This file is the makefile for the project.

/////////////////////////////////////////////////////////////////////////////
To Run WebTune
-------------

1. Start Microsoft Internet Explorer 4.0 (IE4).

2. In IE4, select the menu command File, Open.
   When the Open dialog box appears, click on Browse and locate
   the Vid_Test.htm file, and then click Open. When the Open
   dialog box reappears, click OK.

3. When the Web page loads and IE4 displays the page's text and objects,
   enter the file name of a particular MPEG-1 file along with the required
   path to locate such file in the text box. Click the Set File button to
   assign the file you specified as the input source for audio and video
   and to play the file and click the Stop File button to stop the file.

4. If your computer contains a tuner card for analog television, enter
   a channel number in the text box and click the Set Chan button to
   tune your card to the channel number you specified.

WebTune File
------------

Vid_Test.htm
    This file is an HTML document that contains the text, input elements,
    the Video ActiveX control object, and code written in VBScript that
    manipulates the video control. The code enclosed in the SCRIPT tag
    uses all the same properties and methods as those used in the VidCntrl.frm
    code.

/////////////////////////////////////////////////////////////////////////////
To Run Vid_Tune
-------------

1. Start Microsoft Visual Basic 5.0.

2. When the New Project dialog box appears, select the Existing tab and
   open the Vid_Tune.vbg group project file.

3. From the Run menu, select Start.

4. When the form for the video test control appears in run mode, enter
   the file name of a particular MPEG-1 file along with the required path
   to locate such file in the text box.

5. Click the File button to assign the MPEG-1 file you specified as the
   input source for audio and video and to play the file and click the Stop
   button to stop playing the file.

6. If your computer contains a tuner card for analog television, click any
   of the channel buttons to assign the WDM TvTuner as the input source for
   audio and video and to tune your card to the channel number specified by
   the button.

Vid_Tune Files
------------

Vid_Tune.ctl
    This file contains the images of all the elements on the control's
    designer and the code to manipulate the video control. The designer's code
    uses all the same properties and methods as those used in the VidCntrl.frm
    code. In addition, code in the designer exposes custom properties, creates
    and raises a click event, and creates the MyTune method.

Test_Vid.frm
    This file contains the form image, the image of the Video Test control,
    and the code to manipulate the Video Test control. The form's code contains
    the click event procedure that calls the Video Test control's MyTune method.

Vid_Tune.vbp
    This file is the makefile for the Video Test Control project.

Test_Vid.vbp
    This file is the makefile for the test project that verifies the Video
    Test Control.

Vid_Tune.vbg
    This file is the group file containing the Control project and the test
    project.

/////////////////////////////////////////////////////////////////////////////
To Run VideoMFC
-----------------------------

1. Start Microsoft Visual C++ 5.0.

2. From the File menu, select Open Workspace.

3. When the Open Workspace dialog box appears, go to the appropriate
   directory and open the VdMFC.mak file.

4. From the Build menu, select the Win32 Release configuration from
   the Set Active Configuration menu item. After setting the project
   configuration, select Build VdMFC.exe from the Build menu. After
   building the project, select Execute VdMFC.exe from the Build menu.

5. When the VdMFC application starts, click the File Source (Async.)
   item in the list box to select it for the Vid control's input source.
   Enter the file name of a particular MPEG-1 file along with the required
   path to locate such file in the edit box. Click the Set Input command
   button to assign the MPEG-1 file you specified as the input source for
   audio and video. Click the Set File Name and then Play command buttons
   to start playing the MPEG-1 file you specified. Click the Pause command
   button to temporarily suspend playing. Click the Stop command button to
   stop playing the file.

6. If your computer contains a tuner card for analog television, click the
   WDM TvTuner item in the list box and then the Set Input command button
   to select it for the video control's input source. Enter a channel number
   in the edit box and then click the Set Channels command button to tune
   your card to the channel number you specified. Click the On/Off Video
   command button to allow the Vid control to receive video or to prevent it
   from receiving video.

/////////////////////////////////////////////////////////////////////////////
To Run VideoMFC from the command line
-----------------------------

1. Open a Command Prompt window, switch to the directory on your
   computer that contains the makefile (VdMFC.mak) and the source files
   for the video MFC application, and then type the following exactly
   as shown including the case of the text:
   NMAKE /f "VdMFC.mak" CFG="VdMFC - Win32 Release"

2. To run the built VdMFC application, switch to the \Release directory
   created within the directory containing the source files and type VdMFC.

VideoMFC Files
------------
The MFC AppWizard created all but one of the skeleton files for the VdMFC
application. Most of the files did not require modification. The following
summaries of the contents of each of the files that make up VdMFC are divided
into either the group requiring modifications or not.

*********************
NOT CREATED BY MFC APPWIZARD
*********************
Vidtypes.h
    This file contains the definitions for all the constants and interfaces
    that make up the Vid control. This file was not generated by the MFC
    AppWizard. This file was added to the project.

*********************
NO EDITING REQUIRED
*********************
VdMFC.h
    Main header file for the application that includes other project-specific
    headers (including Resource.h) and defines the CVdMFCApp application class.
    This file was generated by the MFC AppWizard and did not require editing.

VdMFC.cpp
    This is the main application source file that contains the application
    class CVdMFCApp. This file was generated by the MFC AppWizard and did not
    require editing.

VdMFC.rc
    Lists all of the Microsoft Windows resources that the VdMFC application
    uses including the icon stored in the RES subdirectory. This file was
    generated by the MFC AppWizard and did not require editing.

res\VdMFC.ico
    This is an icon file, which is used as the application's icon.  This
    icon is included by the main resource file VdMFC.rc.

res\VdMFC.rc2
    This file contains resources that are not edited by Microsoft Developer
    Studio. This file was generated by the MFC AppWizard and did not
    require editing.

VdMFC.mak
    This file is the makefile for the project.

VdMFC.dsp
    This file is the project file.

StdAfx.h, StdAfx.cpp
    These files are used to build a precompiled header (PCH) file
    named VdMFC.pch and a precompiled types file named StdAfx.obj.
    These files were generated by the MFC AppWizard and did not
    require editing.

Resource.h
    This is the standard header file, which defines new resource IDs.
    This file was generated by the MFC AppWizard and did not
    require editing.

bpcvid.h, bpcvid.cpp
    These files contain the CBPCVid class, which defines the behavior
    of the object that provides streaming video functionality. These
    files were generated by the MFC AppWizard and did not require editing.

bpcbase.h, bpcbase.cpp
    These files contain the CBPCDeviceBase class, which defines the behavior
    of the object that represents either an input or an output device for
    the Vid control. These files were generated by the MFC AppWizard and
    did not require editing.

*********************
EDITING REQUIRED
*********************
VdMFCDlg.h, VdMFCDlg.cpp - the dialog
    These files contain the CVdMFCDlg class. This class defines the
    behavior of the application's main dialog. These files were generated
    by the MFC AppWizard. The following additions were made to these files:
    a. Includes the header files that define the CBPCVid, CBPCDevices, and
       CBPCDeviceBase classes and the data types and interfaces for the Vid
       control.
    b. ClassWizard was used to create variable names for the Vid control and
       for values typed in the edit box for setting channels (m_channel) and
       for strings typed in the edit box for setting file names (m_filename).
       The class definition was edited to create protected variables for the
       list box (box) and an available input or output device for the Vid
       control (m_id). The class definition was also edited to create a private
       variable for a pointer to the IBPCDeviceBase interface.
    c. The constructor for this class initializes the channel and file name
       variable.
    d. The DoDataExchange() method for this class associates the variable names
       with the appropriate elements.
    e. The class definition declares methods to be associated with click events
       for elements of the user interface. The class implementation associates
       the click events with the ON_BN_CLICKED() macro.
    f. The OnInitDialog() method for this class was edited to:
       Assign the list-box control of the user interface to the CListBox
       variable, box.
       Obtain pointers to unknown and enumerate-variant objects that are part
       of the MFC library.
       Declare and allocate a CBPCDevices object and assign the collection of
       all the available input and output devices for the Vid control to it.
       Assign the unknown object to the value returned from the custom
       CBPCDevices::GetNewEnum() method.
       Query the unknown object to obtain an enumerate-variant object and then
       release the unknown object.
       Enter a while loop set to repeat until there are no more variants in
       the enumerate-variant object.
       Get the next variant in the enumerate-variant object and obtain a dispatch
       for such a variant. Declare and allocate a CBPCDeviceBase object and assign
       the dispatch value of the obtained variant to such an object. Retrieve the
       name of the device-base object with the CBPCDeviceBase::GetName() method
       and add it to the list box. Clear the variant.
       After exiting the while loop, release the enumerate-variant object.
    g. The OnSetInput() and OnSetOutput() methods for this class were implemented to:
       Obtain pointers to unknown and enumerate-variant objects.
       Obtain an interface pointer to IBPCDeviceBase defined in Vidtypes.h.
       Declare and allocate a CBPCDevices object and assign the collection of
       all the available input and output devices for the Vid control to it.
       Assign the unknown object to the value returned from the custom
       CBPCDevices::GetNewEnum() method.
       Query the unknown object to obtain an enumerate-variant object and then
       release the unknown object.
       Enter a for loop set to repeat the number of times determined by the
       CBPCVid::GetDeviceCount() method.
       For each iteration of the loop:
         Obtain the next variant in the enumerate-variant object.
         Query the variant object to obtain an IBPCDeviceBase interface pointer.
         Get the name property of the device with the interface's get_Name() method.
         Gets the selected item in the list box and then gets the string
         associated with the item.
         If this string is the same as the device name, assign the video control's
         input and output to that particular device with the SetInput() and
         SetOutput() methods of the CBPCVid class. Also, assign the device to
         the private member variable for the device, m_pDeviceBase.
    h. The OnSetChannel() method for this class was implemented to dispatch a
       pointer to the selected item of the list box, then attach such pointer
       to a CBPCDeviceBase variable with the CBPCDeviceBase::AttachDispatch()
       method, and then assign the channel number specified in the edit box with
       the CBPCDeviceBase::SetChannel() method.
    i. The OnVideoOn() method for this class was implemented to reverse the
       VideoOn value of the Vid control by first retrieving such value and then
       setting it to the opposite value.
    j. The OnSetFile() method for this class was implemented to assign the file
       name specified in the edit box with the CBPCVid::SetFileName() method.
    k. The OnPlay(), OnPause(), and OnStop() methods for this class were
       implemented to play, suspend play, and stop the file with the Run(),
       Pause(), and Stop() methods respectively of the CBPCVid class.

bpcdev.h, bpcdev.cpp
    These files contain the CBPCDevices class, which defines the behavior
    of the object that represents a collection of all the available input
    and output devices for the Vid control. These files were generated
    by the MFC AppWizard.
    A declaration and an implementation were added for the GetNewEnum()
    method. This method retrieves an unknown object that refers to an
    enumerate-variant object.


VID_TUNE.TXT

The Vid_Tune directory contains a Visual Basic group comprising
a Visual Basic control and a Visual Basic project to test the
control. The Visual Basic control contains a Video ActiveX control
as a constituent control.


VIDCNTRL.TXT

The VidCntrl directory contains a Visual Basic project
that uses the Video ActiveX control.


VIDEOMFC.TXT

The VideoMFC directory contains a Visual C++ project
workspace that uses the Video ActiveX control.


BPCBASE.H

//
// bpcbase.h: Defines the CBPCDeviceBase class
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//
#if !defined(AFX_BPCDEVICEBASE_H__4E088A12_0E75_11D1_A073_00A0C9054174__INCLUDED_)
#define AFX_BPCDEVICEBASE_H__4E088A12_0E75_11D1_A073_00A0C9054174__INCLUDED_

#if _MSC_VER >= 1000
#pragma once
#endif // _MSC_VER >= 1000
// Machine generated IDispatch wrapper class(es) created by Microsoft Visual C++

// NOTE: Do not modify the contents of this file.  If this class is regenerated by
//  Microsoft Visual C++, your modifications will be overwritten.

/////////////////////////////////////////////////////////////////////////////
// CBPCDeviceBase wrapper class

class CBPCDeviceBase : public COleDispatchDriver
{
public:
CBPCDeviceBase() {}// Calls COleDispatchDriver default constructor
CBPCDeviceBase(LPDISPATCH pDispatch) : COleDispatchDriver(pDispatch) {}
CBPCDeviceBase(const CBPCDeviceBase& dispatchSrc) : COleDispatchDriver(dispatchSrc) {}

// Attributes
public:

// Operations
public:
CString GetName();
BOOL GetHasFilename();
BOOL GetHasCA();
BOOL GetIsInput();
BOOL GetIsOutput();
BOOL GetHasChannel();
long GetStatus();
CString GetProdName();
CString GetFileName();
void SetFileName(LPCTSTR lpszNewValue);
long GetChannel();
void SetChannel(long nNewValue);
BOOL GetChannelAvailable(long nChannel);
long GetImageSourceWidth();
long GetImageSourceHeight();
long GetCurrentState();
double GetCurrentPosition();
void SetCurrentPosition(double newValue);
double GetDuration();
double GetPrerollTime();
void SetPrerollTime(double newValue);
double GetRate();
void SetRate(double newValue);
long GetCountryCode();
void SetCountryCode(long nNewValue);
long GetVideoFrequency();
long GetAudioFrequency();
long GetDefaultVideoType();
void SetDefaultVideoType(long nNewValue);
long GetDefaultAudioType();
void SetDefaultAudioType(long nNewValue);
long GetVideoSubchannel();
void SetVideoSubchannel(long nNewValue);
long GetAudioSubchannel();
void SetAudioSubchannel(long nNewValue);
void SetVolume(long nNewValue);
long GetVolume();
void SetBalance(long nNewValue);
long GetBalance();
void SetPower(BOOL bNewValue);
BOOL GetPower();
void SetOverScan(long nNewValue);
long GetOverScan();
long GetProviderRating();
BOOL GetProviderStatus();
long GetProviderEPGMask();
LPDISPATCH GetHistoryItems();
LPDISPATCH GetEmailMessages();
CString GetUserName_();
void SetUserName(LPCTSTR lpszNewValue);
CString GetUserArea();
void SetUserArea(LPCTSTR lpszNewValue);
LPDISPATCH GetItemDetails(long Priority, LPDISPATCH pInDetails);
long Command(long nCommand);
void Run();
void Pause();
void Stop();
void Refresh();
void ResetProviderSystem();
LPDISPATCH BuyItem(long Priority, LPDISPATCH pInDetails);
LPDISPATCH CancelItem(LPDISPATCH pInDetails);
void DisplayConfigDialog();
void HandleCardChaining(BOOL fOK);
};

//{{AFX_INSERT_LOCATION}}
// Microsoft Developer Studio will insert additional declarations immediately before the previous line.

#endif // !defined(AFX_BPCDEVICEBASE_H__4E088A12_0E75_11D1_A073_00A0C9054174__INCLUDED_)


BPCDEV.CPP

//
// bpcdev.cpp: Implements the CBPCDevices class
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//
// Machine generated IDispatch wrapper class(es) created by Microsoft Visual C++

// NOTE: Do not modify the contents of this file.  If this class is regenerated by
//  Microsoft Visual C++, your modifications will be overwritten.

#include "stdafx.h"
#include "bpcdev.h"

// Dispatch interfaces referenced by this interface
#include "BPCBase.h"

/////////////////////////////////////////////////////////////////////////////
// CBPCDevices properties

/////////////////////////////////////////////////////////////////////////////
// CBPCDevices operations

long CBPCDevices::GetCount()
{
long result;
InvokeHelper(0x5dd, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

LPUNKNOWN CBPCDevices::GetNewEnum()
{
LPUNKNOWN lpUnk = NULL;
InvokeHelper(-4, DISPATCH_PROPERTYGET, VT_UNKNOWN, (void*)&lpUnk, NULL);
return lpUnk;
}

void CBPCDevices::SetHWnd(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x5de, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

void CBPCDevices::SetLcid(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x5df, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

void CBPCDevices::SetNotify(LPDISPATCH newValue)
{
static BYTE parms[] =
VTS_DISPATCH;
InvokeHelper(0x5e0, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

long CBPCDevices::GetColorKey()
{
long result;
InvokeHelper(0x5e2, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCDevices::SetColorKey(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x5e2, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCDevices::GetPriority()
{
long result;
InvokeHelper(0x5e3, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCDevices::SetPriority(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x5e3, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

CBPCDeviceBase CBPCDevices::GetInput()
{
LPDISPATCH pDispatch;
InvokeHelper(0x5e4, DISPATCH_PROPERTYGET, VT_DISPATCH, (void*)&pDispatch, NULL);
return CBPCDeviceBase(pDispatch);
}

void CBPCDevices::SetInput(LPDISPATCH newValue)
{
static BYTE parms[] =
VTS_DISPATCH;
InvokeHelper(0x5e4, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

CBPCDeviceBase CBPCDevices::GetOutput()
{
LPDISPATCH pDispatch;
InvokeHelper(0x5e5, DISPATCH_PROPERTYGET, VT_DISPATCH, (void*)&pDispatch, NULL);
return CBPCDeviceBase(pDispatch);
}

void CBPCDevices::SetOutput(LPDISPATCH newValue)
{
static BYTE parms[] =
VTS_DISPATCH;
InvokeHelper(0x5e5, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

BOOL CBPCDevices::GetVideoOn()
{
BOOL result;
InvokeHelper(0x411, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, NULL);
return result;
}

void CBPCDevices::SetVideoOn(BOOL bNewValue)
{
static BYTE parms[] =
VTS_BOOL;
InvokeHelper(0x411, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 bNewValue);
}

CBPCDeviceBase CBPCDevices::Item(const VARIANT& v)
{
LPDISPATCH pDispatch;
static BYTE parms[] =
VTS_VARIANT;
InvokeHelper(0x5dc, DISPATCH_METHOD, VT_DISPATCH, (void*)&pDispatch, parms,
&v);
return CBPCDeviceBase(pDispatch);
}

void CBPCDevices::Tune(long lTuningSpace, long Channel, long VideoSubchannel, long AudioSubchannel)
{
static BYTE parms[] =
VTS_I4 VTS_I4 VTS_I4 VTS_I4;
InvokeHelper(0x5e6, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 lTuningSpace, Channel, VideoSubchannel, AudioSubchannel);
}

long CBPCDevices::TSDeviceCount(long lTuningSpace)
{
long result;
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x5e7, DISPATCH_METHOD, VT_I4, (void*)&result, parms,
lTuningSpace);
return result;
}


BPCDEV.H

//
// bpcdev.h: Defines the CBPCDevices class
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//
#if !defined(AFX_BPCDEVICES_H__4E088A11_0E75_11D1_A073_00A0C9054174__INCLUDED_)
#define AFX_BPCDEVICES_H__4E088A11_0E75_11D1_A073_00A0C9054174__INCLUDED_

#if _MSC_VER >= 1000
#pragma once
#endif // _MSC_VER >= 1000
// Machine generated IDispatch wrapper class(es) created by Microsoft Visual C++

// NOTE: Do not modify the contents of this file.  If this class is regenerated by
//  Microsoft Visual C++, your modifications will be overwritten.

// Dispatch interfaces referenced by this interface
class CBPCDeviceBase;

/////////////////////////////////////////////////////////////////////////////
// CBPCDevices wrapper class

class CBPCDevices : public COleDispatchDriver
{
public:
CBPCDevices() {}// Calls COleDispatchDriver default constructor
CBPCDevices(LPDISPATCH pDispatch) : COleDispatchDriver(pDispatch) {}
CBPCDevices(const CBPCDevices& dispatchSrc) : COleDispatchDriver(dispatchSrc) {}

// Attributes
public:

// Operations
public:
long GetCount();
void SetHWnd(long nNewValue);
void SetLcid(long nNewValue);
void SetNotify(LPDISPATCH newValue);
long GetColorKey();
void SetColorKey(long nNewValue);
long GetPriority();
void SetPriority(long nNewValue);
CBPCDeviceBase GetInput();
void SetInput(LPDISPATCH newValue);
CBPCDeviceBase GetOutput();
void SetOutput(LPDISPATCH newValue);
BOOL GetVideoOn();
void SetVideoOn(BOOL bNewValue);
CBPCDeviceBase Item(const VARIANT& v);
void Tune(long lTuningSpace, long Channel, long VideoSubchannel, long AudioSubchannel);
long TSDeviceCount(long lTuningSpace);
LPUNKNOWN GetNewEnum();
};

//{{AFX_INSERT_LOCATION}}
// Microsoft Developer Studio will insert additional declarations immediately before the previous line.

#endif // !defined(AFX_BPCDEVICES_H__4E088A11_0E75_11D1_A073_00A0C9054174__INCLUDED_)


BPCVID.CPP

//
// bpcvid.cpp: Implements the CBPCVid class
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//
// Machine generated IDispatch wrapper class(es) created by Microsoft Visual C++

// NOTE: Do not modify the contents of this file.  If this class is regenerated by
//  Microsoft Visual C++, your modifications will be overwritten.

#include "stdafx.h"
#include "bpcvid.h"

// Dispatch interfaces referenced by this interface
#include "BPCBase.h"
#include "BPCDev.h"

/////////////////////////////////////////////////////////////////////////////
// CBPCVid

IMPLEMENT_DYNCREATE(CBPCVid, CWnd)

/////////////////////////////////////////////////////////////////////////////
// CBPCVid properties

/////////////////////////////////////////////////////////////////////////////
// CBPCVid operations

BOOL CBPCVid::GetPower()
{
BOOL result;
InvokeHelper(0x3f0, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, NULL);
return result;
}

void CBPCVid::SetPower(BOOL bNewValue)
{
static BYTE parms[] =
VTS_BOOL;
InvokeHelper(0x3f0, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 bNewValue);
}

double CBPCVid::GetStartTime()
{
double result;
InvokeHelper(0x3ea, DISPATCH_PROPERTYGET, VT_R8, (void*)&result, NULL);
return result;
}

void CBPCVid::SetStartTime(double newValue)
{
static BYTE parms[] =
VTS_R8;
InvokeHelper(0x3ea, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

double CBPCVid::GetStopTime()
{
double result;
InvokeHelper(0x3eb, DISPATCH_PROPERTYGET, VT_R8, (void*)&result, NULL);
return result;
}

void CBPCVid::SetStopTime(double newValue)
{
static BYTE parms[] =
VTS_R8;
InvokeHelper(0x3eb, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

BOOL CBPCVid::GetVideoOn()
{
BOOL result;
InvokeHelper(0x3ec, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, NULL);
return result;
}

void CBPCVid::SetVideoOn(BOOL bNewValue)
{
static BYTE parms[] =
VTS_BOOL;
InvokeHelper(0x3ec, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 bNewValue);
}

BOOL CBPCVid::GetClosedCaption()
{
BOOL result;
InvokeHelper(0x3ed, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, NULL);
return result;
}

void CBPCVid::SetClosedCaption(BOOL bNewValue)
{
static BYTE parms[] =
VTS_BOOL;
InvokeHelper(0x3ed, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 bNewValue);
}

BOOL CBPCVid::GetDebug()
{
BOOL result;
InvokeHelper(0x3ee, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, NULL);
return result;
}

void CBPCVid::SetDebug(BOOL bNewValue)
{
static BYTE parms[] =
VTS_BOOL;
InvokeHelper(0x3ee, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 bNewValue);
}

long CBPCVid::GetDeviceCount()
{
long result;
InvokeHelper(0x3e9, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

CBPCDeviceBase CBPCVid::GetInput()
{
LPDISPATCH pDispatch;
InvokeHelper(0x3fc, DISPATCH_PROPERTYGET, VT_DISPATCH, (void*)&pDispatch, NULL);
return CBPCDeviceBase(pDispatch);
}

void CBPCVid::SetInput(LPDISPATCH newValue)
{
static BYTE parms[] =
VTS_DISPATCH;
InvokeHelper(0x3fc, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

CBPCDeviceBase CBPCVid::GetOutput()
{
LPDISPATCH pDispatch;
InvokeHelper(0x3fd, DISPATCH_PROPERTYGET, VT_DISPATCH, (void*)&pDispatch, NULL);
return CBPCDeviceBase(pDispatch);
}

void CBPCVid::SetOutput(LPDISPATCH newValue)
{
static BYTE parms[] =
VTS_DISPATCH;
InvokeHelper(0x3fd, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

long CBPCVid::GetColorKey()
{
long result;
InvokeHelper(0x3f4, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCVid::SetColorKey(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x3f4, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

CString CBPCVid::GetFileName()
{
CString result;
InvokeHelper(0x3f5, DISPATCH_PROPERTYGET, VT_BSTR, (void*)&result, NULL);
return result;
}

void CBPCVid::SetFileName(LPCTSTR lpszNewValue)
{
static BYTE parms[] =
VTS_BSTR;
InvokeHelper(0x3f5, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 lpszNewValue);
}

long CBPCVid::GetPriority()
{
long result;
InvokeHelper(0x3f6, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCVid::SetPriority(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x3f6, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCVid::GetVolume()
{
long result;
InvokeHelper(0x3f9, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCVid::SetVolume(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x3f9, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCVid::GetBalance()
{
long result;
InvokeHelper(0x3fa, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCVid::SetBalance(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x3fa, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCVid::GetImageSourceHeight()
{
long result;
InvokeHelper(0x3fb, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

long CBPCVid::GetImageSourceWidth()
{
long result;
InvokeHelper(0x3f2, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

short CBPCVid::GetMovieWindowSetting()
{
short result;
InvokeHelper(0x3f3, DISPATCH_PROPERTYGET, VT_I2, (void*)&result, NULL);
return result;
}

void CBPCVid::SetMovieWindowSetting(short nNewValue)
{
static BYTE parms[] =
VTS_I2;
InvokeHelper(0x3f3, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCVid::GetCurrentState()
{
long result;
InvokeHelper(0x3fe, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

double CBPCVid::GetCurrentPosition()
{
double result;
InvokeHelper(0x3ff, DISPATCH_PROPERTYGET, VT_R8, (void*)&result, NULL);
return result;
}

void CBPCVid::SetCurrentPosition(double newValue)
{
static BYTE parms[] =
VTS_R8;
InvokeHelper(0x3ff, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

double CBPCVid::GetDuration()
{
double result;
InvokeHelper(0x400, DISPATCH_PROPERTYGET, VT_R8, (void*)&result, NULL);
return result;
}

double CBPCVid::GetPrerollTime()
{
double result;
InvokeHelper(0x3f1, DISPATCH_PROPERTYGET, VT_R8, (void*)&result, NULL);
return result;
}

void CBPCVid::SetPrerollTime(double newValue)
{
static BYTE parms[] =
VTS_R8;
InvokeHelper(0x3f1, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

double CBPCVid::GetRate()
{
double result;
InvokeHelper(0x402, DISPATCH_PROPERTYGET, VT_R8, (void*)&result, NULL);
return result;
}

void CBPCVid::SetRate(double newValue)
{
static BYTE parms[] =
VTS_R8;
InvokeHelper(0x402, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

long CBPCVid::GetLocaleID()
{
long result;
InvokeHelper(0x403, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCVid::SetLocaleID(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x403, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

LPDISPATCH CBPCVid::GetFont()
{
LPDISPATCH result;
InvokeHelper(DISPID_FONT, DISPATCH_PROPERTYGET, VT_DISPATCH, (void*)&result, NULL);
return result;
}

void CBPCVid::SetFont(LPDISPATCH newValue)
{
static BYTE parms[] =
VTS_DISPATCH;
InvokeHelper(DISPID_FONT, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

short CBPCVid::GetDisplayMode()
{
short result;
InvokeHelper(0x401, DISPATCH_PROPERTYGET, VT_I2, (void*)&result, NULL);
return result;
}

void CBPCVid::SetDisplayMode(short nNewValue)
{
static BYTE parms[] =
VTS_I2;
InvokeHelper(0x401, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCVid::GetHWnd()
{
long result;
InvokeHelper(DISPID_HWND, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

CBPCDevices CBPCVid::GetDevices()
{
LPDISPATCH pDispatch;
InvokeHelper(0x409, DISPATCH_PROPERTYGET, VT_DISPATCH, (void*)&pDispatch, NULL);
return CBPCDevices(pDispatch);
}

void CBPCVid::Run()
{
InvokeHelper(0x404, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

void CBPCVid::Pause()
{
InvokeHelper(0x405, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

void CBPCVid::Stop()
{
InvokeHelper(0x406, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

void CBPCVid::Close()
{
InvokeHelper(0x407, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

void CBPCVid::Open(LPCTSTR FileName)
{
static BYTE parms[] =
VTS_BSTR;
InvokeHelper(0x408, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 FileName);
}

void CBPCVid::Login(LPCTSTR UserName, LPCTSTR Password)
{
static BYTE parms[] =
VTS_BSTR VTS_BSTR;
InvokeHelper(0x3f8, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 UserName, Password);
}

void CBPCVid::Tune(long lTuningSpace, long Channel, long VideoSubchannel, long AudioSubchannel)
{
static BYTE parms[] =
VTS_I4 VTS_I4 VTS_I4 VTS_I4;
InvokeHelper(0x40b, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 lTuningSpace, Channel, VideoSubchannel, AudioSubchannel);
}

long CBPCVid::TSDeviceCount(long lTuningSpace)
{
long result;
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x40c, DISPATCH_METHOD, VT_I4, (void*)&result, parms,
lTuningSpace);
return result;
}

void CBPCVid::Refresh()
{
InvokeHelper(DISPID_REFRESH, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

void CBPCVid::AboutBox()
{
InvokeHelper(0xfffffdd8, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}


BPCVID.H

//
// bpcvid.h: Defines the CBPCVid class
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//
#if !defined(AFX_BPCVID_H__4E088A10_0E75_11D1_A073_00A0C9054174__INCLUDED_)
#define AFX_BPCVID_H__4E088A10_0E75_11D1_A073_00A0C9054174__INCLUDED_

#if _MSC_VER >= 1000
#pragma once
#endif // _MSC_VER >= 1000
// Machine generated IDispatch wrapper class(es) created by Microsoft Visual C++

// NOTE: Do not modify the contents of this file.  If this class is regenerated by
//  Microsoft Visual C++, your modifications will be overwritten.

// Dispatch interfaces referenced by this interface
class CBPCDeviceBase;
class CBPCDevices;

/////////////////////////////////////////////////////////////////////////////
// CBPCVid wrapper class

class CBPCVid : public CWnd
{
protected:
DECLARE_DYNCREATE(CBPCVid)
public:
CLSID const& GetClsid()
{
static CLSID const clsid
= { 0x31263ec0, 0x2957, 0x11cf, { 0xa1, 0xe5, 0x0, 0xaa, 0x9e, 0xc7, 0x97, 0x0 } };
return clsid;
}
virtual BOOL Create(LPCTSTR lpszClassName,
LPCTSTR lpszWindowName, DWORD dwStyle,
const RECT& rect,
CWnd* pParentWnd, UINT nID,
CCreateContext* pContext = NULL)
{ return CreateControl(GetClsid(), lpszWindowName, dwStyle, rect, pParentWnd, nID); }

    BOOL Create(LPCTSTR lpszWindowName, DWORD dwStyle,
const RECT& rect, CWnd* pParentWnd, UINT nID,
CFile* pPersist = NULL, BOOL bStorage = FALSE,
BSTR bstrLicKey = NULL)
{ return CreateControl(GetClsid(), lpszWindowName, dwStyle, rect, pParentWnd, nID,
pPersist, bStorage, bstrLicKey); }

// Attributes
public:

// Operations
public:
BOOL GetPower();
void SetPower(BOOL bNewValue);
double GetStartTime();
void SetStartTime(double newValue);
double GetStopTime();
void SetStopTime(double newValue);
BOOL GetVideoOn();
void SetVideoOn(BOOL bNewValue);
BOOL GetClosedCaption();
void SetClosedCaption(BOOL bNewValue);
BOOL GetDebug();
void SetDebug(BOOL bNewValue);
long GetDeviceCount();
CBPCDeviceBase GetInput();
void SetInput(LPDISPATCH newValue);
CBPCDeviceBase GetOutput();
void SetOutput(LPDISPATCH newValue);
long GetColorKey();
void SetColorKey(long nNewValue);
CString GetFileName();
void SetFileName(LPCTSTR lpszNewValue);
long GetPriority();
void SetPriority(long nNewValue);
long GetVolume();
void SetVolume(long nNewValue);
long GetBalance();
void SetBalance(long nNewValue);
long GetImageSourceHeight();
long GetImageSourceWidth();
short GetMovieWindowSetting();
void SetMovieWindowSetting(short nNewValue);
long GetCurrentState();
double GetCurrentPosition();
void SetCurrentPosition(double newValue);
double GetDuration();
double GetPrerollTime();
void SetPrerollTime(double newValue);
double GetRate();
void SetRate(double newValue);
long GetLocaleID();
void SetLocaleID(long nNewValue);
LPDISPATCH GetFont();
void SetFont(LPDISPATCH newValue);
short GetDisplayMode();
void SetDisplayMode(short nNewValue);
long GetHWnd();
CBPCDevices GetDevices();
void Run();
void Pause();
void Stop();
void Close();
void Open(LPCTSTR FileName);
void Login(LPCTSTR UserName, LPCTSTR Password);
void Tune(long lTuningSpace, long Channel, long VideoSubchannel, long AudioSubchannel);
long TSDeviceCount(long lTuningSpace);
void Refresh();
void AboutBox();
};

//{{AFX_INSERT_LOCATION}}
// Microsoft Developer Studio will insert additional declarations immediately before the previous line.

#endif // !defined(AFX_BPCVID_H__4E088A10_0E75_11D1_A073_00A0C9054174__INCLUDED_)


RESOURCE.H

// resource.h: Header file defining new resource IDs.
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//
//{{NO_DEPENDENCIES}}
// Microsoft Developer Studio generated include file.
// Used by VdMFC.rc
//
#define IDD_VDMFC_DIALOG                102
#define IDR_MAINFRAME                   128
#define IDC_LISTBOX                     1000
#define IDC_EDITFILENAME                1004
#define IDC_SETINPUT                    1005
#define IDC_SETOUTPUT                   1006
#define IDC_VIDCNTRL                    1007
#define IDC_EDITCHANNEL                 1008
#define IDC_SETFILENAME                 1009
#define IDC_SETCHANNEL                  1010
#define IDC_VIDEOON                     1011
#define IDC_PLAY                        1012
#define IDC_PAUSE                       1013
#define IDC_STOP                        1014

// Next default values for new objects
//
#ifdef APSTUDIO_INVOKED
#ifndef APSTUDIO_READONLY_SYMBOLS
#define _APS_NEXT_RESOURCE_VALUE        130
#define _APS_NEXT_COMMAND_VALUE         32771
#define _APS_NEXT_CONTROL_VALUE         1006
#define _APS_NEXT_SYMED_VALUE           101
#endif
#endif


STDAFX.CPP

// stdafx.cpp : source file that includes just the standard includes
//VdMFC.pch will be the pre-compiled header
//stdafx.obj will contain the pre-compiled type information
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//

#include "stdafx.h"


STDAFX.H

// stdafx.h : include file for standard system include files,
//  or project specific include files that are used frequently, but
//      are changed infrequently
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//

#if !defined(AFX_STDAFX_H__4E088A0A_0E75_11D1_A073_00A0C9054174__INCLUDED_)
#define AFX_STDAFX_H__4E088A0A_0E75_11D1_A073_00A0C9054174__INCLUDED_

#if _MSC_VER >= 1000
#pragma once
#endif // _MSC_VER >= 1000

#define VC_EXTRALEAN// Exclude rarely-used stuff from Windows headers

#include <afxwin.h>         // MFC core and standard components
#include <afxext.h>         // MFC extensions
#include <afxdisp.h>        // MFC OLE automation classes
#ifndef _AFX_NO_AFXCMN_SUPPORT
#include <afxcmn.h>// MFC support for Windows Common Controls
#endif // _AFX_NO_AFXCMN_SUPPORT

//{{AFX_INSERT_LOCATION}}
// Microsoft Developer Studio will insert additional declarations immediately before the previous line.

#endif // !defined(AFX_STDAFX_H__4E088A0A_0E75_11D1_A073_00A0C9054174__INCLUDED_)


VDMFC.CPP

// VdMFC.cpp : Defines the class behaviors for the application.
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//

#include "stdafx.h"
#include "VdMFC.h"
#include "VdMFCDlg.h"

#ifdef _DEBUG
#define new DEBUG_NEW
#undef THIS_FILE
static char THIS_FILE[] = __FILE__;
#endif

/////////////////////////////////////////////////////////////////////////////
// CVdMFCApp

BEGIN_MESSAGE_MAP(CVdMFCApp, CWinApp)
//{{AFX_MSG_MAP(CVdMFCApp)
// NOTE - the ClassWizard will add and remove mapping macros here.
//    DO NOT EDIT what you see in these blocks of generated code!
//}}AFX_MSG
ON_COMMAND(ID_HELP, CWinApp::OnHelp)
END_MESSAGE_MAP()

/////////////////////////////////////////////////////////////////////////////
// CVdMFCApp construction

CVdMFCApp::CVdMFCApp()
{
// TODO: add construction code here,
// Place all significant initialization in InitInstance
}

/////////////////////////////////////////////////////////////////////////////
// The one and only CVdMFCApp object

CVdMFCApp theApp;

/////////////////////////////////////////////////////////////////////////////
// CVdMFCApp initialization

BOOL CVdMFCApp::InitInstance()
{
AfxEnableControlContainer();

// Standard initialization
// If you are not using these features and wish to reduce the size
//  of your final executable, you should remove from the following
//  the specific initialization routines you do not need.

#ifdef _AFXDLL
Enable3dControls();// Call this when using MFC in a shared DLL
#else
Enable3dControlsStatic();// Call this when linking to MFC statically
#endif

CVdMFCDlg dlg;
m_pMainWnd = &dlg;
int nResponse = dlg.DoModal();
if (nResponse == IDOK)
{
// TODO: Place code here to handle when the dialog is
//  dismissed with OK
}
else if (nResponse == IDCANCEL)
{
// TODO: Place code here to handle when the dialog is
//  dismissed with Cancel
}

// Since the dialog has been closed, return FALSE so that we exit the
//  application, rather than start the application's message pump.
return FALSE;
}


VDMFC.H

// VdMFC.h : main header file for the VDMFC application
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//

#if !defined(AFX_VDMFC_H__4E088A06_0E75_11D1_A073_00A0C9054174__INCLUDED_)
#define AFX_VDMFC_H__4E088A06_0E75_11D1_A073_00A0C9054174__INCLUDED_

#if _MSC_VER >= 1000
#pragma once
#endif // _MSC_VER >= 1000

#ifndef __AFXWIN_H__
#error include 'stdafx.h' before including this file for PCH
#endif

#include "resource.h"// main symbols

/////////////////////////////////////////////////////////////////////////////
// CVdMFCApp:
// See VdMFC.cpp for the implementation of this class
//

class CVdMFCApp : public CWinApp
{
public:
CVdMFCApp();

// Overrides
// ClassWizard generated virtual function overrides
//{{AFX_VIRTUAL(CVdMFCApp)
public:
virtual BOOL InitInstance();
//}}AFX_VIRTUAL

// Implementation

//{{AFX_MSG(CVdMFCApp)
// NOTE - the ClassWizard will add and remove member functions here.
//    DO NOT EDIT what you see in these blocks of generated code !
//}}AFX_MSG
DECLARE_MESSAGE_MAP()
};

/////////////////////////////////////////////////////////////////////////////

//{{AFX_INSERT_LOCATION}}
// Microsoft Developer Studio will insert additional declarations immediately before the previous line.

#endif // !defined(AFX_VDMFC_H__4E088A06_0E75_11D1_A073_00A0C9054174__INCLUDED_)


VDMFCDLG.CPP

//
// VdMFCDlg.cpp: Implements the CVdMFCDlg class, which is
//               the application's main dialog.
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//

#include "stdafx.h"
#include <initguid.h>
#include "VdMFC.h"
#include "VdMFCDlg.h"

#ifdef _DEBUG
#define new DEBUG_NEW
#undef THIS_FILE
static char THIS_FILE[] = __FILE__;
#endif

/////////////////////////////////////////////////////////////////////////////
// CVdMFCDlg dialog

CVdMFCDlg::CVdMFCDlg(CWnd* pParent /*=NULL*/)
: CDialog(CVdMFCDlg::IDD, pParent)
{
//{{AFX_DATA_INIT(CVdMFCDlg)
m_channel = 0;
m_filename = _T("");
//}}AFX_DATA_INIT
// Note that LoadIcon does not require a subsequent DestroyIcon in Win32
m_hIcon = AfxGetApp()->LoadIcon(IDR_MAINFRAME);
}

void CVdMFCDlg::DoDataExchange(CDataExchange* pDX)
{
CDialog::DoDataExchange(pDX);
//{{AFX_DATA_MAP(CVdMFCDlg)
DDX_Control(pDX, IDC_VIDCNTRL, m_CVid);
DDX_Text(pDX, IDC_EDITCHANNEL, m_channel);
DDX_Text(pDX, IDC_EDITFILENAME, m_filename);
//}}AFX_DATA_MAP
}

BEGIN_MESSAGE_MAP(CVdMFCDlg, CDialog)
//{{AFX_MSG_MAP(CVdMFCDlg)
ON_WM_PAINT()
ON_WM_QUERYDRAGICON()
ON_BN_CLICKED(IDC_SETINPUT, OnSetInput)
ON_BN_CLICKED(IDC_SETOUTPUT, OnSetOutput)
ON_BN_CLICKED(IDC_SETCHANNEL, OnSetChannel)
ON_BN_CLICKED(IDC_SETFILENAME, OnSetFile)
ON_BN_CLICKED(IDC_PLAY, OnPlay)
ON_BN_CLICKED(IDC_PAUSE, OnPause)
ON_BN_CLICKED(IDC_STOP, OnStop)
ON_BN_CLICKED(IDC_VIDEOON, OnVideoOn)
//}}AFX_MSG_MAP
END_MESSAGE_MAP()

/////////////////////////////////////////////////////////////////////////////
// CVdMFCDlg message handlers

BOOL CVdMFCDlg::OnInitDialog()
{
CDialog::OnInitDialog();

// Set the icon for this dialog.  The framework does this automatically
//  when the application's main window is not a dialog
SetIcon(m_hIcon, TRUE);// Set big icon
SetIcon(m_hIcon, FALSE);// Set small icon

// Assign the list-box control to the CListBox variable and
// then verify.
VERIFY( box.SubclassDlgItem( IDC_LISTBOX, this ) );

// Obtain pointers to unknown and enumerate-variant objects.

LPUNKNOWN lpunk;
LPENUMVARIANT lpenumvar;

// Declare and allocate a Devices object and assign the
// collection of all the available input and output devices
// for the video control to this object.
CBPCDevices pDevices = m_CVid.GetDevices();

// Assign the unknown object to the value returned from the
// GetNewEnum function. GetNewEnum is a custom function added
// to the CBPCDevices class.
lpunk = pDevices.GetNewEnum();

// Query the unknown object to obtain an enumerate-variant
// object and then release the unknown object.
if( lpunk == NULL )
return FALSE;

VERIFY( SUCCEEDED( lpunk->QueryInterface( IID_IEnumVARIANT, ( void** )&lpenumvar ) ) );
lpunk->Release();

long celt;
COleVariant var;

// While there are still devices that can provide input or
// output for the video control, construct a DeviceBase object
// from the next variant obtained from the enumerate-variant
// object and add the device's name to the list box.
while( S_OK == lpenumvar->Next( 1, &var, ( unsigned long* )&celt ) )
{
ASSERT( var.vt == VT_DISPATCH );
CBPCDeviceBase id( var.pdispVal );
box.AddString( id.GetName() );

var.Clear();
}

// Release the enumerate-variant object.
lpenumvar->Release();

return TRUE;  // return TRUE  unless you set the focus to a control
}

// If you add a minimize button to your dialog, you will need the code below
//  to draw the icon.  For MFC applications using the document/view model,
//  this is automatically done for you by the framework.

void CVdMFCDlg::OnPaint()
{
if (IsIconic())
{
CPaintDC dc(this); // device context for painting

SendMessage(WM_ICONERASEBKGND, (WPARAM) dc.GetSafeHdc(), 0);

// Center icon in client rectangle
int cxIcon = GetSystemMetrics(SM_CXICON);
int cyIcon = GetSystemMetrics(SM_CYICON);
CRect rect;
GetClientRect(&rect);
int x = (rect.Width() - cxIcon + 1) / 2;
int y = (rect.Height() - cyIcon + 1) / 2;

// Draw the icon
dc.DrawIcon(x, y, m_hIcon);
}
else
{
CDialog::OnPaint();
}
}

// The system calls this to obtain the cursor to display while the user drags
//  the minimized window.
HCURSOR CVdMFCDlg::OnQueryDragIcon()
{
return (HCURSOR) m_hIcon;
}

void CVdMFCDlg::OnSetInput()
{
LPUNKNOWN lpunk;
LPENUMVARIANT lpenumvar;
BOOL bFound = FALSE;
IBPCDeviceBase* pDevice;

CBPCDevices pDevices = m_CVid.GetDevices();
lpunk = pDevices.GetNewEnum(); //GetNewEnum custom function see
   //details

if( lpunk == NULL )
return;

VERIFY( SUCCEEDED( lpunk->QueryInterface( IID_IEnumVARIANT, ( void** )&lpenumvar ) ) );
lpunk->Release();

for( int i = 0; i < m_CVid.GetDeviceCount(); i++ )
{
long celt;
COleVariant var;

if( SUCCEEDED( lpenumvar->Next( 1, &var, (unsigned long*)&celt ) ) )
{
var.punkVal->QueryInterface( IID_IBPCDeviceBase, (void**)&pDevice );

if( pDevice != NULL )
{
BSTR bsDeviceName;
pDevice->get_Name( &bsDeviceName );
CString str( bsDeviceName );
SysFreeString( bsDeviceName );

CString string;
int sel = box.GetCurSel();

if( sel == LB_ERR )
{
AfxMessageBox( "Please select a device from the list" );
pDevice->Release();
lpenumvar->Release();
var.Clear();
return;
}
box.GetText( sel, string );

if( str == string )
{
m_CVid.SetInput( pDevice );
m_pDeviceBase = pDevice;
bFound = TRUE;
}
pDevice->Release();
}
var.Clear();
}
if( bFound )
break;
}
ASSERT( lpenumvar != NULL );
lpenumvar->Release();
}

void CVdMFCDlg::OnSetOutput()
{
LPUNKNOWN lpunk;
LPENUMVARIANT lpenumvar;
BOOL bFound = FALSE;
IBPCDeviceBase* pDevice;

CBPCDevices pDevices = m_CVid.GetDevices();
lpunk = pDevices.GetNewEnum(); //GetNewEnum custom function see
   //details

if( lpunk == NULL )
return;

VERIFY( SUCCEEDED( lpunk->QueryInterface( IID_IEnumVARIANT, ( void** )&lpenumvar ) ) );
lpunk->Release();

for( int i = 0; i < m_CVid.GetDeviceCount(); i++ )
{
long celt;
COleVariant var;

if( SUCCEEDED( lpenumvar->Next( 1, &var, (unsigned long*)&celt ) ) )
{
var.punkVal->QueryInterface( IID_IBPCDeviceBase, (void**)&pDevice );

if( pDevice != NULL )
{
BSTR bsDeviceName;
pDevice->get_Name( &bsDeviceName );
CString str( bsDeviceName );
SysFreeString( bsDeviceName );

CString string;
int sel = box.GetCurSel();

if( sel == LB_ERR )
{
AfxMessageBox( "Please select a device from the list" );
pDevice->Release();
lpenumvar->Release();
var.Clear();
return;
}
box.GetText( sel, string );

if( str == string )
{
m_CVid.SetOutput( pDevice );
m_pDeviceBase = pDevice;
bFound = TRUE;
}
pDevice->Release();
}
var.Clear();
}
if( bFound )
break;
}
ASSERT( lpenumvar != NULL );
lpenumvar->Release();
}

void CVdMFCDlg::OnVideoOn()
{
m_CVid.SetVideoOn( !m_CVid.GetVideoOn() );

}

void CVdMFCDlg::OnSetChannel()
{
UpdateData( TRUE );
 CBPCDeviceBase id;

id.AttachDispatch( m_pDeviceBase, FALSE );
id.SetChannel( m_channel );
}

void CVdMFCDlg::OnSetFile()
{
UpdateData( TRUE );
m_CVid.SetFileName( m_filename );

}

void CVdMFCDlg::OnPlay()
{
m_CVid.Run();

}

void CVdMFCDlg::OnPause()
{
m_CVid.Pause();

}

void CVdMFCDlg::OnStop()
{
m_CVid.Stop();

}


VDMFCDLG.H

//
// VdMFCDlg.h: Defines the CVdMFCDlg class, which defines the
//             behavior of the application's main dialog.
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//
//{{AFX_INCLUDES()
#include "bpcvid.h"
#include "bpcbase.h"
#include "bpcdev.h"
#include "vidtypes.h"
//}}AFX_INCLUDES

#if !defined(AFX_VDMFCDLG_H__4E088A08_0E75_11D1_A073_00A0C9054174__INCLUDED_)
#define AFX_VDMFCDLG_H__4E088A08_0E75_11D1_A073_00A0C9054174__INCLUDED_

#if _MSC_VER >= 1000
#pragma once
#endif // _MSC_VER >= 1000

/////////////////////////////////////////////////////////////////////////////
// CVdMFCDlg dialog

class CVdMFCDlg : public CDialog
{
// Construction
public:
CVdMFCDlg(CWnd* pParent = NULL);// standard constructor

// Dialog Data
//{{AFX_DATA(CVdMFCDlg)
enum { IDD = IDD_VDMFC_DIALOG };
CBPCVidm_CVid;
longm_channel;
CStringm_filename;
//}}AFX_DATA

// ClassWizard generated virtual function overrides
//{{AFX_VIRTUAL(CVdMFCDlg)
protected:
virtual void DoDataExchange(CDataExchange* pDX);// DDX/DDV support
//}}AFX_VIRTUAL

// Implementation
protected:
CListBox box;
CBPCDeviceBase m_id;
HICON m_hIcon;

// Generated message map functions
//{{AFX_MSG(CVdMFCDlg)
virtual BOOL OnInitDialog();
afx_msg void OnPaint();
afx_msg HCURSOR OnQueryDragIcon();
afx_msg void OnSetChannel();
afx_msg void OnPause();
afx_msg void OnVideoOn();
afx_msg void OnStop();
afx_msg void OnSetInput();
afx_msg void OnSetOutput();
afx_msg void OnPlay();
afx_msg void OnSetFile();
//}}AFX_MSG

DECLARE_MESSAGE_MAP()
private:
IBPCDeviceBase* m_pDeviceBase;
};

//{{AFX_INSERT_LOCATION}}
// Microsoft Developer Studio will insert additional declarations immediately before the previous line.

#endif // !defined(AFX_VDMFCDLG_H__4E088A08_0E75_11D1_A073_00A0C9054174__INCLUDED_)


BPCBASE.CPP

//
// bpcbase.cpp: Implements the CBPCDeviceBase class
//
// Copyright (C) 1997 Microsoft Corporation
// All rights reserved.
//
// This source code is only intended as a supplement to the
// Broadcast Architecture Programmer's Reference.
// For detailed information regarding Broadcast
// Architecture, see the reference.
//
// Machine generated IDispatch wrapper class(es) created by Microsoft Visual C++

// NOTE: Do not modify the contents of this file.  If this class is regenerated by
//  Microsoft Visual C++, your modifications will be overwritten.

#include "stdafx.h"
#include "bpcbase.h"

/////////////////////////////////////////////////////////////////////////////
// CBPCDeviceBase properties

/////////////////////////////////////////////////////////////////////////////
// CBPCDeviceBase operations

CString CBPCDeviceBase::GetName()
{
CString result;
InvokeHelper(0x3e9, DISPATCH_PROPERTYGET, VT_BSTR, (void*)&result, NULL);
return result;
}

BOOL CBPCDeviceBase::GetHasFilename()
{
BOOL result;
InvokeHelper(0x3ed, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, NULL);
return result;
}

BOOL CBPCDeviceBase::GetHasCA()
{
BOOL result;
InvokeHelper(0x410, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, NULL);
return result;
}

BOOL CBPCDeviceBase::GetIsInput()
{
BOOL result;
InvokeHelper(0x3ea, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, NULL);
return result;
}

BOOL CBPCDeviceBase::GetIsOutput()
{
BOOL result;
InvokeHelper(0x3eb, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, NULL);
return result;
}

BOOL CBPCDeviceBase::GetHasChannel()
{
BOOL result;
InvokeHelper(0x3ec, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, NULL);
return result;
}

long CBPCDeviceBase::GetStatus()
{
long result;
InvokeHelper(0x3ef, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

CString CBPCDeviceBase::GetProdName()
{
CString result;
InvokeHelper(0x3f0, DISPATCH_PROPERTYGET, VT_BSTR, (void*)&result, NULL);
return result;
}

CString CBPCDeviceBase::GetFileName()
{
CString result;
InvokeHelper(0x3f1, DISPATCH_PROPERTYGET, VT_BSTR, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetFileName(LPCTSTR lpszNewValue)
{
static BYTE parms[] =
VTS_BSTR;
InvokeHelper(0x3f1, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 lpszNewValue);
}

long CBPCDeviceBase::GetChannel()
{
long result;
InvokeHelper(0x3f2, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetChannel(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x3f2, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

BOOL CBPCDeviceBase::GetChannelAvailable(long nChannel)
{
BOOL result;
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x3f5, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, parms,
nChannel);
return result;
}

long CBPCDeviceBase::GetImageSourceWidth()
{
long result;
InvokeHelper(0x3f7, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

long CBPCDeviceBase::GetImageSourceHeight()
{
long result;
InvokeHelper(0x3f8, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

long CBPCDeviceBase::GetCurrentState()
{
long result;
InvokeHelper(0x412, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

double CBPCDeviceBase::GetCurrentPosition()
{
double result;
InvokeHelper(0x3f9, DISPATCH_PROPERTYGET, VT_R8, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetCurrentPosition(double newValue)
{
static BYTE parms[] =
VTS_R8;
InvokeHelper(0x3f9, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

double CBPCDeviceBase::GetDuration()
{
double result;
InvokeHelper(0x3fa, DISPATCH_PROPERTYGET, VT_R8, (void*)&result, NULL);
return result;
}

double CBPCDeviceBase::GetPrerollTime()
{
double result;
InvokeHelper(0x3fb, DISPATCH_PROPERTYGET, VT_R8, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetPrerollTime(double newValue)
{
static BYTE parms[] =
VTS_R8;
InvokeHelper(0x3fb, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

double CBPCDeviceBase::GetRate()
{
double result;
InvokeHelper(0x3fc, DISPATCH_PROPERTYGET, VT_R8, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetRate(double newValue)
{
static BYTE parms[] =
VTS_R8;
InvokeHelper(0x3fc, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 newValue);
}

long CBPCDeviceBase::GetCountryCode()
{
long result;
InvokeHelper(0x3fd, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetCountryCode(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x3fd, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCDeviceBase::GetVideoFrequency()
{
long result;
InvokeHelper(0x3fe, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

long CBPCDeviceBase::GetAudioFrequency()
{
long result;
InvokeHelper(0x3ff, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

long CBPCDeviceBase::GetDefaultVideoType()
{
long result;
InvokeHelper(0x400, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetDefaultVideoType(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x400, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCDeviceBase::GetDefaultAudioType()
{
long result;
InvokeHelper(0x401, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetDefaultAudioType(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x401, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCDeviceBase::GetVideoSubchannel()
{
long result;
InvokeHelper(0x402, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetVideoSubchannel(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x402, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCDeviceBase::GetAudioSubchannel()
{
long result;
InvokeHelper(0x403, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetAudioSubchannel(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x403, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

void CBPCDeviceBase::SetVolume(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x407, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCDeviceBase::GetVolume()
{
long result;
InvokeHelper(0x407, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetBalance(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x408, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCDeviceBase::GetBalance()
{
long result;
InvokeHelper(0x408, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetPower(BOOL bNewValue)
{
static BYTE parms[] =
VTS_BOOL;
InvokeHelper(0x40b, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 bNewValue);
}

BOOL CBPCDeviceBase::GetPower()
{
BOOL result;
InvokeHelper(0x40b, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetOverScan(long nNewValue)
{
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x413, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 nNewValue);
}

long CBPCDeviceBase::GetOverScan()
{
long result;
InvokeHelper(0x413, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

long CBPCDeviceBase::GetProviderRating()
{
long result;
InvokeHelper(0x51d, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

BOOL CBPCDeviceBase::GetProviderStatus()
{
BOOL result;
InvokeHelper(0x51e, DISPATCH_PROPERTYGET, VT_BOOL, (void*)&result, NULL);
return result;
}

long CBPCDeviceBase::GetProviderEPGMask()
{
long result;
InvokeHelper(0x519, DISPATCH_PROPERTYGET, VT_I4, (void*)&result, NULL);
return result;
}

LPDISPATCH CBPCDeviceBase::GetHistoryItems()
{
LPDISPATCH result;
InvokeHelper(0x520, DISPATCH_PROPERTYGET, VT_DISPATCH, (void*)&result, NULL);
return result;
}

LPDISPATCH CBPCDeviceBase::GetEmailMessages()
{
LPDISPATCH result;
InvokeHelper(0x521, DISPATCH_PROPERTYGET, VT_DISPATCH, (void*)&result, NULL);
return result;
}

CString CBPCDeviceBase::GetUserName_()
{
CString result;
InvokeHelper(0x51b, DISPATCH_PROPERTYGET, VT_BSTR, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetUserName(LPCTSTR lpszNewValue)
{
static BYTE parms[] =
VTS_BSTR;
InvokeHelper(0x51b, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 lpszNewValue);
}

CString CBPCDeviceBase::GetUserArea()
{
CString result;
InvokeHelper(0x51c, DISPATCH_PROPERTYGET, VT_BSTR, (void*)&result, NULL);
return result;
}

void CBPCDeviceBase::SetUserArea(LPCTSTR lpszNewValue)
{
static BYTE parms[] =
VTS_BSTR;
InvokeHelper(0x51c, DISPATCH_PROPERTYPUT, VT_EMPTY, NULL, parms,
 lpszNewValue);
}

LPDISPATCH CBPCDeviceBase::GetItemDetails(long Priority, LPDISPATCH pInDetails)
{
LPDISPATCH result;
static BYTE parms[] =
VTS_I4 VTS_DISPATCH;
InvokeHelper(0x518, DISPATCH_PROPERTYGET, VT_DISPATCH, (void*)&result, parms,
Priority, pInDetails);
return result;
}

long CBPCDeviceBase::Command(long nCommand)
{
long result;
static BYTE parms[] =
VTS_I4;
InvokeHelper(0x3f4, DISPATCH_METHOD, VT_I4, (void*)&result, parms,
nCommand);
return result;
}

void CBPCDeviceBase::Run()
{
InvokeHelper(0x40c, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

void CBPCDeviceBase::Pause()
{
InvokeHelper(0x40e, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

void CBPCDeviceBase::Stop()
{
InvokeHelper(0x40d, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

void CBPCDeviceBase::Refresh()
{
InvokeHelper(0x40f, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

void CBPCDeviceBase::ResetProviderSystem()
{
InvokeHelper(0x515, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

LPDISPATCH CBPCDeviceBase::BuyItem(long Priority, LPDISPATCH pInDetails)
{
LPDISPATCH result;
static BYTE parms[] =
VTS_I4 VTS_DISPATCH;
InvokeHelper(0x516, DISPATCH_METHOD, VT_DISPATCH, (void*)&result, parms,
Priority, pInDetails);
return result;
}

LPDISPATCH CBPCDeviceBase::CancelItem(LPDISPATCH pInDetails)
{
LPDISPATCH result;
static BYTE parms[] =
VTS_DISPATCH;
InvokeHelper(0x517, DISPATCH_METHOD, VT_DISPATCH, (void*)&result, parms,
pInDetails);
return result;
}

void CBPCDeviceBase::DisplayConfigDialog()
{
InvokeHelper(0x51a, DISPATCH_METHOD, VT_EMPTY, NULL, NULL);
}

void CBPCDeviceBase::HandleCardChaining(BOOL fOK)
{
static BYTE parms[] =
VTS_BOOL;
InvokeHelper(0x523, DISPATCH_METHOD, VT_EMPTY, NULL, parms,
 fOK);
}


WEBTUNE.TXT

The WebTune directory contains an HTML document that
Internet Explorer uses to display a Video ActiveX control.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.


User-Defined Variables

The Stream Compiler language supports user-defined variables. These can be useful when you find that you must use the same value frequently.

For example, at the beginning of the stream list, you might create a constant called "interval", to represent how often files should be rebroadcast:

Interval = 30.0 ;

User-defined variables may be used anywhere in the stream list in place of literal expressions, as in:

00:06:00:00 "Segment7.htm" repeat Interval until ShowLength;

User-defined variables may also be used to establish fixed points within the show, so that subsequent events can be specified relative to these points. For example, the starting times of the major acts of a program episode could be defined as:

ActI = 00:01:10.0
ActII = 00:09:45.0
ActIII = 00:18:30.0

Given these user-defined variables, it becomes possible to specify times relative to the beginning of each act, rather than the beginning of each show. For example, the following expression specifies 1:25 into the third act, which is actually 19:55 into the show:

ActIII + 1:25:00