ITelevisionServices::LoadEnhancementsFromFile

[This is preliminary documentation and subject to change.]

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\tmulticast_address\tmulticast_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