/*
 * Flash communication functions.
 *
 * @depends /js/jquery.js, /js/ptv.js
 */
PTV.namespace("flash");

/**
 * Interact with a particular flash player on the current page.
 * 
 * Using this object the caller can interact with a particular flash player on
 * a given HTML page. The interactions possible are:
 * 
 *   - Adding event callbacks to allow the flash player to communicate with the 
 *     current HTML page.
 *   - Removing an event callback that is no longer needed.
 *   - Send text with a particular content ID to the flash player
 *     ie myPlayer.sendTextToPlayer('xmlPlaylist', xmlPlaylistContent);
 *   - Send an object with a particular content ID to the flash player
 *     ie myPlayer.sendObjectToPlayer('jsArray', anArray);
 * 
 * Note: Not all flash players may implement all this functionality, don't
 *       expect it to be there. Discuss it with your friendly neighbourhood
 *       flash developer.
 * 
 * @param {String containerId} The id of the container with the flash player to
 *            interact with.
 */
PTV.flash.Player = function(containerId) {
  var isIE = navigator.appName.indexOf("Microsoft") != -1;
  
  /**
   * The ID of the page element holding the flash player (?)
   */
  var containerId = containerId;
  
  /**
   * The DOM reference to the flash player object.
   */
  var player = (isIE) ? window[containerId] : document[containerId];
  
  /**
   * Check whether or not the player exposes the requested function to JS.
   * 
   * Note: This does not check signature requirements, only that the named item
   *       has been exposed by Flash's external API implementation.
   * 
   * @param {String exposedName} The name of the function, etc to check whether
   *            or not the player has exposed to JS.
   * 
   * @return true if the player has exposed the requested function, etc or false
   *         if the player has not exposed anything with the requested name.
   */
  function playerHasExposed(exposedName) {
    var result = false;
    
    if(typeof player != "undefined") {
      result = typeof player[exposedName] != "undefined";
    }
    
    return result;
  }

  return {
    /**
     * The event ID for a change in what is playing in the flash player.
     */
    EV_MEDIA_CHANGE: 'MediaChange',
    
    /**
     * Get the flash player associated with this PTV.flash.Player object.
     * 
     * @return {Object} A reference to the flash player.
     */
    getPlayer: function () {
      return player;
    },
    
    /**
     * Set the container ID for the element holding the flash player.
     * 
     * @param {String containerId} The ID of the container element.
     */
    setPlayer: function(containerId) {
      containerId = containerId;
      this.player = (isIE) ? window[containerId] : document[containerId];
    },
    
    /**
     * Send some text to the flash player.
     * 
     * @param {String contentId} The ID of the content being sent.
     * @param {String textContent} The text content to send to the flash player.
     * 
     * @return true if the text was sent to the player, false otherwise.
     */
    sendTextToPlayer: function(contentId, textContent) {
      var result = false;
      if(playerHasExposed('sendTextToPlayer')) {
        player.sendTextToPlayer(contentId, textContent);
        result = true;
      }
      
      return result;
    },
    
    /**
     * Send a javascript object to the flash player.
     * 
     * @param {String contentId} A meaningful content descriptor.
     * @param {Object jsObject} A js object to pass to the flash player.
     * 
     * @return true if the object was sent to the player, false otherwise.
     */
    sendObjectToPlayer: function(contentId, jsObject) {
      var result = false;
      if(playerHasExposed('sendObjectToPlayer')) {
        player.sendObjectToPlayer(contentId, jsObject);
        result = true;
      }
      
      return result;
    },
    
    /**
     * Add a callback with a particular callback ID to the flash player.
     * 
     * @param {String eventId} The ID of the event being defined.
     * @param {function callback} The Javascript function to invoke when the
     *            flash player needs to send some data to the page.
     * 
     * @return {boolean} true if the callback was added successfully, false
     *             otherwise. 
     */
    attachEvent: function(eventId, callback) {
      return playerHasExposed('attachEvent') ? player.attachEvent(eventId, callback) : false;
    },
    
    /**
     * Remove a callback that was previously defined.
     * 
     * @param {String eventId} The ID of the event to remove.
     * 
     * @return {boolean} true if the callback was successfully removed, false
     *             otherwise.
     */
    removeEvent: function(eventId) {
      return playerHasExposed('removeEvent') ? player.removeEvent(eventId, callback) : false;
    }
  }
};