Creating Triggers

Triggers are real-time events under ATVEF; they are executed on the broadcast client as soon as they are received. Therefore, the enhancement files must be packaged and sent to the client before they can be triggered by a call to IATVEFSend::SendTrigger.

An ATVEF trigger is simply a text string consisting of a required URL, followed by a series of optional attribute/value pairs and a checksum. The URL will typically be a "local ID" in the form "lid://namespace/filename" that refers to a file previously sent to the client in a package. The namespace identifier corresponds to the content-location parameter in the IATVEFPackage::AddFile method and provides a way to group related files. The namespace can be specified in various ways; for more details, see the ATVEF specification.

The client is responsible for unpacking the files and navigating the local ID URL to find the file. The simplest form of trigger consists simply of an URL specifying an HTML page or graphic to display, for example:

lid://unique123@xyz.com/page1.htm

Note that it is also possible under the ATVEF specification to pass in an "http://" URL to direct the client to retrieve the file from the Web, although this method is inherently more risky and also assumes the client has a live Internet connection.

Three optional trigger attributes are also defined by the specification: name, script, and expires. The SendTrigger method does not use the expires attribute since expiration times can be applied to files when they are added to packages. For a complete description of how triggers and their attributes are handled on ATVEF-compliant clients, refer to the ATVEF specification. Pass in a NULL string in SendTrigger for any attribute you don't need to use. The following example assumes that page1.htm has been previously packaged and sent to the client. The method call shown here will cause the client to retrieve page1.htm from the "unique123@xyz.com" namespace and display it immediately, and then invoke an ECMAScript function called doSomething that is defined in page1.htm. (For information on how to obtain the pISend pointer, see Co-creating an Inserter or Multicast Class Instance.)

pISend->SendTrigger(
        L"lid://unique123@xyz.com/page1.htm", //local URL
        L"Welcome to Revolutionary Video",    //human-readable name
         L"doSomething()" //ECMAScript fragment
         };