Creating an Announcement

After a CSendATVEFInserter or CSendATVEFMulticast object is initialized, the next step is to create an announcement.

An internal announcement data structure is created automatically when a CSendATVEFInserter or CSendATVEFMulticast object is co-created; the structure persists, maintaining its state, for the lifetime of the object. The announcement is not deleted or automatically modified after being sent and remains available if it needs to be sent again. This allows you to resend an announcement as often as you like. To prepare a "new" announcement, simply modify the fields that need to be changed.

Some announcement fields are initially empty and some are set to a default value. A content server application fills in or modifies the fields through the various methods of the IATVEFAnnouncement interface, which is implemented by the CSendATVEFInserter and CSendATVEFMulticast classes.

Since any modification to the announcement disconnects the trigger and package tunnels, you must call IATVEFSend::Connect again after modifying the announcement. This reestablishes all connections so that you can call IATVEFSend::SendAnnouncement IATVEFSend::SendTrigger and IATVEFSend::SendPackage as often as necessary to send the announcement, with its associated triggers and packages, until the next time the announcement is modified.

The ATVEF specification for announcements is based on SDP, the Session Description Protocol (RFC 2737), although some fields which are optional in SDP are required under ATVEF. An announcement packet consists of a Session Announcement Protocol (SAP) header (inserted automatically) and a text payload, which is the SDP announcement that your application must create through the methods of IATVEFAnnouncement. For detailed descriptions of the announcement fields, see RFC 2327, and the ATVEF specification. For more information on how to obtain the pIAnnouncement pointer, see Co-creating an Inserter or Multicast Class Instance.

The following example illustrates the method calls involved in creating an initial announcement with the minimum required fields, and then shows the resulting announcement that would be sent to broadcast clients.

char* szIPaddress = "126.125.231.114"; //originating host
// inet_addr returns the address in network order
// so we use ntohl to convert to host order
ULONG ulIP = ntohl(inet_addr(szIPAddress));
 
//set the "IPAddress" identifier in the owner ("o=") field
pIAnnouncement->SetSendingIP(ulIP);
 
// Set the "user name" identifier in the owner ("o=") field
// must not contain any spaces. Call this method only if you need to
// specify a login other than the default "-"
pIAnnouncement->SetUserName(L"myLogin");
 
// Set the "session ID" identifier in the owner ("o=") field
// The Session ID, together with the other identifiers
// in the owner field, should uniquely identify this broadcast.
// How you create the Session ID is up to you.
pIAnnouncement->SetSessionID(uiSessionID);
 
// Set the "version" identifier in the owner ("o=") field
// the announcement version should increment each time
// session data is modified. 
pIAnnouncement->SetVersion(uiVersion);
 
// Set the name ("s=") field. Typically this is the 
// name of the enhanced video program.
pIAnnouncement->SetSessionName(L"Revolutionary Video");
 
// Set the e-mail ("e=") or phone ("p=") field
// depending on which method is called. Only one is required.
pIAnnouncement->AddEmail(L"myemail@greatbroadcaster.com");
 
// Set the time ("t=") field
// stopTime may be set to zero since the "SetSecondsToEnd"
// method informs clients of the ending time
DATE startTime;
SYSTEMTIME  SystemTime ;
 
    // create a start time
    ZeroMemory (& SystemTime, sizeof SystemTime) ;
    SystemTime.wYear    = 1999 ;
    SystemTime.wMonth   = 12 ;
    SystemTime.wDay     = 31 ;
    SystemTimeToVariantTime (& SystemTime, & startTime) ;
 
// add a "t=" field
pIAnnouncement->SetStartStopTime(startTime, 0);
 
//set the "a=tve:size" field
pIAnnouncement->SetMaxCacheSize(999999);
 
ULONG ulDest = ntohl(inet_addr("225.10.10.10"));
pIAnnouncement->ConfigureDataAndTriggerTransmission(
                  ulDest, // IP address
                  4001,  //data port; trigger set to 4002
                  127,    //time-to-live 
                  9600  //maximum bit rate
                  );

The resulting announcement (shown in the following table) is ready to be sent. It contains the minimum information necessary to constitute a valid ATVEF announcement. Additional optional fields may be included. For more details, see IATVEFAnnouncement.

Note  In the ATVEF specification, announcements are sent on a well-known IP address (224.0.1.113) and port (2670). This IP address and port have been registered with the IANA.