sbIRemoteSecurityEvent.idl

Go to the documentation of this file.

/*
//
// BEGIN SONGBIRD GPL
//
// This file is part of the Songbird web player.
//
// Copyright(c) 2005-2008 POTI, Inc.
// http://songbirdnest.com
//
// This file may be licensed under the terms of of the
// GNU General Public License Version 2 (the "GPL").
//
// Software distributed under the License is distributed
// on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
// express or implied. See the GPL for the specific language
// governing rights and limitations.
//
// You should have received a copy of the GPL along with this
// program. If not, go to http://www.gnu.org/licenses/gpl.html
// or write to the Free Software Foundation, Inc.,
// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
//
// END SONGBIRD GPL
//
*/

#include "nsISupports.idl"

interface nsIDOMDocument;
interface nsIDOMEvent;
interface nsIURI;

/*
Event: SecurityEvent

A <SecurityEvent> is passed to any event handlers listening for
security permissions status related events fired on the document object.

Note that the <Songbird> object must be accessed before any events will be
raised. This will likely change in the future.

Example:
  The JavaScript code.

  (start code)
  var myDiv;
  
  function load() {
    document.addEventListener('RemoteAPIPermissionChanged', handleEvent, true);
    document.addEventListener('RemoteAPIPermissionDenied', handleEvent, true);
    
    myDiv = document.getElementById("output");

    // Enumerate some items in the mainLibrary.
    var listener = {
      onEnumerationBegin: function() {
      },
      onEnumeratedItem: function(list, item) {
        var artistName = item.getProperty("http://songbirdnest.com/data/1.0#artistName");
        var trackName = item.getProperty("http://songbirdnest.com/data/1.0#trackName");
        
        //I love this track.
        var msg = "I love this song, it's by " + 
                  artistName + 
                  " and I think the track name is " + 
                  trackName;
                  
        myDiv.appendChild( document.createTextNode(msg) );
        myDiv.appendChild( document.createElement("br") );

        // Returning CANCEL stops the enumeration process, returning CONTINUE
        // or omitting the return statement continues.
        return Components.interfaces.sbIMediaListEnumerationListener.CONTINUE;
      },
      onEnumerationEnd: function() {
        var msg = "I like a lot of tracks."
        
        // I like a lot of tracks.
        myDiv.appendChild( document.createTextNode(msg) );
      }
    };
    
    // Attempt to enumerate all items
    songbird.mainLibrary.enumerateAllItems(listener, 0);
  }

  function unload() {
    document.removeEventListener('RemoteAPIPermissionChanged', handleEvent, true);
    document.removeEventListener('RemoteAPIPermissionDenied', handleEvent, true);
  }

  function handleEvent(aEvent) {
    var msg = "";

    if ( aEvent.type == 'RemoteAPIPermissionDenied' ) {
      msg = "You have opted to not configure Songbird so our webpage can interact " +
            "with it at its fullest. Please open tools->options and configure the " +
            "RemoteAPI preferences to allow us XYZ permissions. " + 
            "Below are the permissions that were requested.";
            
      myDiv.appendChild( document.createTextNode(msg) );
      
      myDiv.appendChild( document.createElement("br") );
      
      myDiv.appendChild( document.createTextNode(aEvent.category + 
                                                 " ( " + aEvent.categoryID + " ) , " + 
                                                 aEvent.hasAccess));
    }
    else if( aEvent.type == "RemoteAPIPermissionChanged" ) {
      msg = "Thanks! You've granted the following permissions:";
      
      myDiv.appendChild( document.createTextNode(msg) );
      
      myDiv.appendChild( document.createElement("br") );
      
      myDiv.appendChild( document.createTextNode(aEvent.category + 
                                                 " ( " + aEvent.categoryID + " ) , " + 
                                                 aEvent.hasAccess) );
      myDiv.appendChild(document.createElement("br"));
    }
    
    try {
      myDiv.appendChild(document.createTextNode(aEvent.originalTarget.location));
    } catch (e) { }
      
      myDiv.appendChild(document.createElement("br"));
    
    try {
      myDiv.appendChild(document.createTextNode(aEvent.type));
    } catch (e) { }
      
      myDiv.appendChild(document.createElement("br"));
  }
  (end code)

  And then don't forget to add this to your HTML code.

  (start code)
  <body onload="load();" onunload="unload();"> 
    <div id="output">
    </div>
  </body>
  (end code)

  See Also:
    <MediaItem>
    <http://developer.mozilla.org/en/docs/DOM:event>
    <http://developer.mozilla.org/en/docs/DOM:element.addEventListener>
*/

[scriptable, uuid(2faa8d0f-b3b0-4545-b06b-2ce92d53e7e3)]
 interface sbIRemoteSecurityEvent : nsISupports
{
  /*
  Prop: siteScope

  The <Security> site scope.

  Type:
    URI
  */
  readonly attribute nsIURI siteScope;

  /*
  Prop: category

  The <Security> category.

  Type: 
    String
  */
  readonly attribute AString category;

  /*
  Prop: categoryID

  The <Security> category ID. This is the internal ID for the <category>.

  Type:
    String
  */
  readonly attribute AString categoryID;

  /*
  Prop: hasAccess

  Indicates if access is granted for the <Security> category.

  Type: 
    Boolean
  */
  readonly attribute boolean hasAccess;
};

[scriptable, uuid(422A0C68-C4A3-40c6-974D-37D1E71BAE8C)]
interface sbIMutableRemoteSecurityEvent : nsISupports
{
  void initSecurityEvent(in nsIDOMDocument aDoc, in nsIURI aSiteScope, in AString aCategory, in AString aCategoryID, in boolean aHasAccess);
};