IScheduledItems::Add

[This is preliminary documentation and subject to change.]

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