Using IScheduledItems to Schedule a Show Reminder

[This is preliminary documentation and subject to change.]

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

    PathTvx.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.