Platform SDK: Broadcast Architecture

IATVEFAnnouncement

The IATVEFAnnouncement interface encapsulates the formatting details of the ATVEF announcement protocol. The interface provides methods for setting optional as well as required announcement information.

When to Implement

Implemented by CSendATVEFInserter and CSendATVEFMulticast in ATVEFSnd.dll.

When to Use

Applications use the methods of this interface to prepare or modify an ATVEF-compliant announcement before it is sent out.

Methods in Vtable Order

IUnknown method	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

IATVEFAnnouncement method	Description
SetSendingIP	Sets the sending IP address in host order. Required.
SetUserName	Sets the login name of the person responsible for the content (defaults to "-"). Required.
SetSessionID	Sets the session ID. Required.
SetVersion	Sets the announcement version number. Required.
SetSessionName	Sets the session name (a human-readable string). Required.
AddEmail	Adds an e-mail address for a contact person responsible for creating the content. Required.
AddTelephone	Adds a phone number, with country code, of a person responsible for creating the content. Required.
SetStartStopTime	Specifies the start and/or stop time for the session. Required.
SetMaxCacheSize	Specifies the amount of cache space the client will need at any given time to hold the file downloads for this session. Required.
SetContentLevelID	Sets the ATVEF content level. Defaults to 1.0.
SetMessageIDHash	Sets the hash value for the SAP message ID. Defaults to 0.
SetLangID	Specifies the language in which the enhancements are written (English, French, Spanish, and so on).
SetSDPLangID	Specifies the language in which the announcement is written (English, French, Spanish, and so on).
SetPrimary	Specifies the stream associated with this announcement as the primary enhancement stream.
SetSecondsToEnd	Specifies the number of seconds in which the session will end, relative to the receipt of the announcement.
ConfigureDataAndTriggerTransmission	Sets an identical IP multicast address for the data and trigger streams.
ConfigureDataTransmission	Sets the transmission parameters for data packets.
ConfigureTriggerTransmission	Sets the transmission parameters for triggers.
SetShowLabel	Sets the optional "i=" field in the announcement to provide a human-readable string for a particular show within a session.
SetGUID	Specifies a GUID to uniquely identify files belonging to this session.
ClearAllTimes	Clears all start and stop times from the "t=" field of the announcement.
ClearEMail	Clears all e-mail addresses from the "e=" field of the announcement.
ClearTelephone	Clears all phone numbers from the "p=" field of the announcement.

Remarks

This interface allows you to create ATVEF-compliant announcements without having to worry about the formatting details of the protocol. A content server application passes in the parameter values and the IATVEFAnnouncement methods build the formatted strings. Your application is responsible for supplying all the required fields that have no default values. If you do not supply all the required fields, your call to SendAnnouncement will fail.

The internal announcement data structure is created automatically when the CSendATVEFInserter or CSendATVEFMulticast object is co-created, and persists, maintaining its state, for the lifetime of the object. This allows you to resend an announcement as often as you like without having to manage its creation or destruction. To prepare a "new" announcement, simply modify the fields that need to be changed.

To send or resend an announcement, call SendAnnouncement. Note that whenever an announcement field is updated, the trigger and package connections are disconnected, so you must call IATVEFSend::Connect to reestablish those connections to the VBI Inserter or the NIC before attempting to send triggers or packages. For more details, see IATVEFSend.

The ATVEF announcement protocol is based upon the SDP protocol (RFC 2327), although some fields which are optional in SDP are required by the ATVEF specification.

Requirements