Class: MediaAgent

Superclasses

Observable, SourceManager

Syntax

 MediaAgent::init spec

Description

MediaAgents are ``bare processing engines''. They do not create or rely upon a user-interface. Instead, the script that creates the object manipulates it directly and if a user-interface is desired, that script must create and bind the UI to the agent. The protocol for communicating between the agent and the UI follows the Mash Observer model. In fact, since the observer abstraction is completely general, any object can attach itself to a MediaAgent as an observer, not just UIs.

Note: This is an abstract base class. Do not create objects directly of this class (note either SRM or RTP might be subclasses)

Methods

• install-key

  
  
  
  
      $agent install-key $key

  Instruct the media-agent to perform encryption and decryption of all data sent to or received from the network. The format of the key is as specified by the SDP specification. XXX put format here.
   
•  reset

  
  
  
  
          $agent reset $spec

  Reset the address specifier of the underlying session in question. This allows the network objects to be dynamically reconfigured to facilitate higher-level control protocols that might instruct an application to switch multicast sessions or speak to a different unicast destination.
   
• shutdown

  
  
  
  
     $agent shutdown

  Gracefully tear down the underlying session. Set or query the media associated with this session. Please note that the media is automatically set by the init method of this class. Programmers should not invoke this method directly to set the media.

  Returns: In syntax (1), it returns a string that represents the media associated with this session. In syntax (2), the return value is undefined.

• set-bandwidth

        set-bandwidth $bps

Set the network bandwidth used by the underlying media transmission protocols to bps bits per second. XXX Explain enforcement?

• register

• unregister

Observer method called when a source generates activity (i.e., when data packets are received from a src). Subsequent calls to this method for source src are suppressed until the clear_busy method is called for that source. Name change: data_trigger? trigger?

• clear_busy

  See above.

• notify

• activate

Observer method called when data packets from source src are received for the first time. Sources are classified as either passive or active, depending on whether they generate data (i.e., a passive source is really just a receiver). Thus the activate method is invoked when a source goes from the passive status to the active status. This allows an observer (or a sub-class) to set up a data pipeline to handle the new stream (e.g., a video decoder pipeline).

• deactivate

Observer method called when the source src transitions from the active state to the passive state. This transition occurs after some configurable amount of time elapses without that source generating any data packets. In response, an observer (or a sub-class) might deallocate state that was created to handle the media flow.

• change_format

Observer method called when the source src transitions from the active state to the passive state. Should be prepared to detect and handle one call per packet? (in case the sender process is broken)

• update_source_info
  Observer method called when any sender identification information assocaited with source src changes. In response, the observer might update the user interface display.

• grayout
  (another trigger?) \

• embolden

(another trigger?)

    1.  set file [$session header_file]
or  2.  $session header_file $file

Query or set the header file object associated with this session. file must be an object of class HeaderFile.

Returns: In syntax (1), it returns an object of class HeaderFile if the header file has previously been set, otherwise it returns an empty string. In syntax (2), the return value is undefined.
 

• save_in:

  
  
  
  
      1.  set directory [$session save_in]
  or  2.  $session save_in $directory

  Query or set the directory name in which the stream data and index files for this session are stored.

  Returns: In syntax (1), it returns the name of the directory in which stream data and index files are stored, if the directory has previously been set, otherwise it returns an empty string. In syntax (2), the return value is undefined.
   

• session_id:

  
  
  
  
      1.  set session_id [$session session_id]
  or  2.  $session session_id $session_id

  Query or set the session-id associated with this session. session_id is simply a string that contains valid filename characters (directory separator characters are not permitted). The session-id is used as a prefix for data and index filenames.

  Returns: In syntax (1), it returns the session-id string if it has previously been set, otherwise it returns an empty string. In syntax (2), the return value is undefined.
   

• generate_filename:

  
  
  
  
   set path [$session generate_filename]

  Return a filename that is guaranteed to be unique across all streams and all sessions that are part of this recorder process. The filename does not contain the ".dat" or ".idx" extension. The filename has the following format:

  
  
  
  
       <dir>/<session_id>-<media><media_count>-<count>

  where dir is the value returned by the save_in method, session_id is the value returned by the session_id method (if the session_id field is empty, that part of the filename, including the following hyphen, is eliminated), media is the value returned by the media method, media_count is a media-specific counter, so that two sessions with the same media will not collide on their filenames, and count is a session-specific counter, so different streams within a session have different filenames.

  Returns: A filename that can be used by the ArchiveStream/Record objects to create data and index files for new streams.

Observable events

new_stream:

$session notify_observers new_stream <stream>

Invoked when the recording session detects a new source and creates a new stream object for it. stream must be an object of a class that is subclassed from ArchiveStream.

$session notify_observers stream_done <stream>

Invoked when the recording session detects an existing source has vanished. stream must be an object of a class that is subclassed from ArchiveStream.

Related Objects:

Putting it all together 

Putting it all together