Songbird / Development / Songbird Add-Ons API Documentation

components/remoteapi/public/sbIRemoteSecurityEvent.idl

00001 /*
00002 //
00003 // BEGIN SONGBIRD GPL
00004 //
00005 // This file is part of the Songbird web player.
00006 //
00007 // Copyright(c) 2005-2008 POTI, Inc.
00008 // http://songbirdnest.com
00009 //
00010 // This file may be licensed under the terms of of the
00011 // GNU General Public License Version 2 (the "GPL").
00012 //
00013 // Software distributed under the License is distributed
00014 // on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
00015 // express or implied. See the GPL for the specific language
00016 // governing rights and limitations.
00017 //
00018 // You should have received a copy of the GPL along with this
00019 // program. If not, go to http://www.gnu.org/licenses/gpl.html
00020 // or write to the Free Software Foundation, Inc.,
00021 // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
00022 //
00023 // END SONGBIRD GPL
00024 //
00025 */
00026 
00027 #include "nsISupports.idl"
00028 
00029 interface nsIDOMDocument;
00030 interface nsIDOMEvent;
00031 interface nsIURI;
00032 
00033 /*
00034 Event: SecurityEvent
00035 
00036 A <SecurityEvent> is passed to any event handlers listening for
00037 security permissions status related events fired on the document object.
00038 
00039 Note that the <Songbird> object must be accessed before any events will be
00040 raised. This will likely change in the future.
00041 
00042 Example:
00043   The JavaScript code.
00044 
00045   (start code)
00046   var myDiv;
00047   
00048   function load() {
00049     document.addEventListener('RemoteAPIPermissionChanged', handleEvent, true);
00050     document.addEventListener('RemoteAPIPermissionDenied', handleEvent, true);
00051     
00052     myDiv = document.getElementById("output");
00053 
00054     // Enumerate some items in the mainLibrary.
00055     var listener = {
00056       onEnumerationBegin: function() {
00057       },
00058       onEnumeratedItem: function(list, item) {
00059         var artistName = item.getProperty("http://songbirdnest.com/data/1.0#artistName");
00060         var trackName = item.getProperty("http://songbirdnest.com/data/1.0#trackName");
00061         
00062         //I love this track.
00063         var msg = "I love this song, it's by " + 
00064                   artistName + 
00065                   " and I think the track name is " + 
00066                   trackName;
00067                   
00068         myDiv.appendChild( document.createTextNode(msg) );
00069         myDiv.appendChild( document.createElement("br") );
00070 
00071         // Returning CANCEL stops the enumeration process, returning CONTINUE
00072         // or omitting the return statement continues.
00073         return Components.interfaces.sbIMediaListEnumerationListener.CONTINUE;
00074       },
00075       onEnumerationEnd: function() {
00076         var msg = "I like a lot of tracks."
00077         
00078         // I like a lot of tracks.
00079         myDiv.appendChild( document.createTextNode(msg) );
00080       }
00081     };
00082     
00083     // Attempt to enumerate all items
00084     songbird.mainLibrary.enumerateAllItems(listener, 0);
00085   }
00086 
00087   function unload() {
00088     document.removeEventListener('RemoteAPIPermissionChanged', handleEvent, true);
00089     document.removeEventListener('RemoteAPIPermissionDenied', handleEvent, true);
00090   }
00091 
00092   function handleEvent(aEvent) {
00093     var msg = "";
00094 
00095     if ( aEvent.type == 'RemoteAPIPermissionDenied' ) {
00096       msg = "You have opted to not configure Songbird so our webpage can interact " +
00097             "with it at it's fullest. Please open tools->options and configure the " +
00098             "RemoteAPI preferences to allow us XYZ permissions. " + 
00099             "Below are the permissions that were requested.";
00100             
00101       myDiv.appendChild( document.createTextNode(msg) );
00102       
00103       myDiv.appendChild( document.createElement("br") );
00104       
00105       myDiv.appendChild( document.createTextNode(aEvent.category + 
00106                                                  " ( " + aEvent.categoryID + " ) , " + 
00107                                                  aEvent.hasAccess));
00108     }
00109     else if( aEvent.type == "RemoteAPIPermissionChanged" ) {
00110       msg = "Thanks! You've granted the following permissions:";
00111       
00112       myDiv.appendChild( document.createTextNode(msg) );
00113       
00114       myDiv.appendChild( document.createElement("br") );
00115       
00116       myDiv.appendChild( document.createTextNode(aEvent.category + 
00117                                                  " ( " + aEvent.categoryID + " ) , " + 
00118                                                  aEvent.hasAccess) );
00119       myDiv.appendChild(document.createElement("br"));
00120     }
00121     
00122     try {
00123       myDiv.appendChild(document.createTextNode(aEvent.originalTarget.location));
00124     } catch (e) { }
00125       
00126       myDiv.appendChild(document.createElement("br"));
00127     
00128     try {
00129       myDiv.appendChild(document.createTextNode(aEvent.type));
00130     } catch (e) { }
00131       
00132       myDiv.appendChild(document.createElement("br"));
00133   }
00134   (end code)
00135 
00136   And then don't forget to add this to your HTML code.
00137 
00138   (start code)
00139   <body onload="load();" onunload="unload();"> 
00140     <div id="output">
00141     </div>
00142   </body>
00143   (end code)
00144 
00145   See Also:
00146     <MediaItem>
00147     <http://developer.mozilla.org/en/docs/DOM:event>
00148     <http://developer.mozilla.org/en/docs/DOM:element.addEventListener>
00149 */
00150 
00156 [scriptable, uuid(2faa8d0f-b3b0-4545-b06b-2ce92d53e7e3)]
00157  interface sbIRemoteSecurityEvent : nsISupports
00158 {
00159   /*
00160   Prop: siteScope
00161 
00162   The <Security> site scope.
00163 
00164   Type:
00165     URI
00166   */
00167   readonly attribute nsIURI siteScope;
00168 
00169   /*
00170   Prop: category
00171 
00172   The <Security> category.
00173 
00174   Type: 
00175     String
00176   */
00177   readonly attribute AString category;
00178 
00179   /*
00180   Prop: categoryID
00181 
00182   The <Security> category ID. This is the internal ID for the <category>.
00183 
00184   Type:
00185     String
00186   */
00187   readonly attribute AString categoryID;
00188 
00189   /*
00190   Prop: hasAccess
00191 
00192   Indicates if access is granted for the <Security> category.
00193 
00194   Type: 
00195     Boolean
00196   */
00197   readonly attribute boolean hasAccess;
00198 };
00199 
00200 [scriptable, uuid(422A0C68-C4A3-40c6-974D-37D1E71BAE8C)]
00201 interface sbIMutableRemoteSecurityEvent : nsISupports
00202 {
00203   void initSecurityEvent(in nsIDOMDocument aDoc, in nsIURI aSiteScope, in AString aCategory, in AString aCategoryID, in boolean aHasAccess);
00204 };

Generated on Tue Mar 10 14:28:55 2009 for Songbird by  doxygen 1.5.2