ITelevisionServices::LoadEnhancement

[This is preliminary documentation and subject to change.]

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