Updating addons broken by private browsing changes

  • Revision slug: Updating_addons_broken_by_private_browsing_changes
  • Revision title: Updating addons broken by private browsing changes
  • Revision id: 340569
  • Created:
  • Creator: jdm
  • Is current revision? No
  • Comment

Revision Content

After reading this document, contact Josh Matthews with further questions or clarifications, or file a bug if your extension has stopped working due to a change described here and you are having trouble updating it.

How do I know if my addon is affected by these changes?

If your code refers to any of the following interfaces:

FF 15:
nsIDOMStorageManager

FF 16:
nsITransferable

FF 18:
imgICache
mozIAsyncFavicons
nsIFaviconService
nsIWebBrowserPersist

FF 19:
nsIContentPrefService
nsIDownloadManager
nsIDownload
nsIHttpAuthManager
nsIStrictTransportSecurityService

FF 20:
nsIPrivateBrowsingService

Furthermore, if your code uses any of these common chrome APIs:

FF 19:
saveURL

saveInternal
openLinkIn


FF 20:
OpenBrowserWindow
gPrivateBrowsingUI

Finally, if your code watches for any of these observer notifications:
private-browsing
private-browsing-cancel-vote
private-browsing-change-granted
private-browsing-transition-complete


Then your addon will require updating to correctly support the new per-window private browser feature in Firefox 20 (and will require updating to work correctly in releases of Firefox since the ones listed).

IDLs

nsITransferable: see Using the clipboard for information about the new init method.

imgICache: this must no longer be obtained as a service. See the imgICache article for more information.

mozIAsyncFavicons/nsIFaviconService: setAndFetchFaviconForPage/setAndLoadFaviconForPage now take a required privacy status argument, either nsIFaviconService.FAVICON_LOAD_PRIVATE or nsIFaviconService.FAVICON_LOAD_NON_PRIVATE.

nsIWebBrowserPersist: saveURI gained a new argument, see the nsIWebBrowserPersist docs for more information.

nsIContentPrefService: getPref, setPref, hasPref, hasCachedPref, removePref, removeGroupedPrefs, removePrefsByName, getPrefs, and getPrefsByName all take a required nsILoadContext argument to indicate the privacy status of the pref in question. Use PrivateBrowsingUtils.getPrivacyContextFromWindow(win) to obtain it from the relevant window.

nsIDownloadManager/nsIDownload:

  • Integer download IDs (and specifically the id property of nsIDownload) are deprecated, and don't allow access to private downloads. All downloads now use GUIDs, and contain a new guid property.
  • nsIDownload now has retry, cancel, remove, pause, and resume methods which should be used instead of deprecated similarly-named nsIDownloadManager methods.
  • nsIDownload's getDownload method is deprecated; use the asynchronous getDownloadByGUID method instead.
  • nsIDownloadManager now has activePrivateDownloads, activePrivateDownloadCount, and privateDBConnection members to complement the existing public ones
  • nsIDownloadManager's addListener method is deprecated. addPrivacyAwareListener should be used instead, or no notifications will be received for private downloads
  • New download-manager-remove-download-guid notification, which passes an nsISupportsCString subject for the GUID or null


nsIHttpAuthManager: setAuthIdentity and getAuthIdentity now take an optional boolean parameter to indicate whether the identity is classified as private.

nsIStrictTransportSecurityService: processStsHeader, removeStsState, isStsHost, and isStsUri now take a flags parameter that understands nsISocketProvider.NO_PERMANENT_STORAGE or nothing.

nsIPrivateBrowsingService: this service is deprecated, and as of Firefox 20 the value returned by privateBrowsingEnabled should not be trusted.

 

Observer notifications

None of the ones listed above will be sent as of Firefox 20. The supporting per-window private browsing article explains further about the equivalent notifications, which are all backwards compatible through to Firefox 12 (and are sent side-by-side with the global private browsing notifications in older versions).
 

Chrome APIs

OpenBrowserWindow: takes an optional parameter to indicate desired properties of the window. Passing {private: true} will cause a private window to open, otherwise the window will always be non-private. Use {private: PrivateBrowsingUtils.isWindowPrivate(window)} to open a window that matches the current window's privacy status.

openLinkIn: can receive an extra private boolean property in the parameter object.

internalSave: takes a new required Document argument (prior to the optional boolean and string arguments) indicating the document which originated the save action.

gPrivateBrowsingUI: can no longer be used to control private browsing of any kind. Any new private browsing session should be opened using OpenBrowserWindow, and any queries for private browsing status should use PrivateBrowsingUtils.isWindowPrivate(win) on a relevant window object.

saveURL: takes a new required Document argument indicating the source of the URL being saved.

Revision Source

<p>After reading this document, contact <a href="http://mailto:josh@joshmatthews.net" title="http://mailto:josh@joshmatthews.net">Josh Matthews</a> with further questions or clarifications, or <a href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox&amp;component=Extension%20Compatibility&amp;blocked=pbnextensions&amp;cc=josh@joshmatthews.net" title="https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox&amp;component=Extension%20Compatibility&amp;blocked=pbnextensions&amp;cc=josh@joshmatthews.net">file a bug</a> if your extension has stopped working due to a change described here and you are having trouble updating it.</p>
<h2>How do I know if my addon is affected by these changes?</h2>
<p>If your code refers to any of the following interfaces:</p>
<pre>
<u>FF 15:</u>
<code>nsIDOMStorageManager</code>

<u>FF 16:</u>
<code>nsITransferable</code>

<u>FF 18:</u><code>
imgICache
mozIAsyncFavicons
nsIFaviconService
nsIWebBrowserPersist</code>

<u>FF 19:</u><code>
nsIContentPrefService
nsIDownloadManager
nsIDownload
nsIHttpAuthManager
nsIStrictTransportSecurityService</code>

<u>FF 20:</u>
<code>nsIPrivateBrowsingService
</code></pre>
<p>Furthermore, if your code uses any of these common chrome APIs:</p>
<pre>
<u>FF 19</u>:
<code>saveURL</code>

<code>saveInternal
openLinkIn
</code>

<u>FF 20:</u>
<code>OpenBrowserWindow
gPrivateBrowsingUI</code>
</pre>
<p>Finally, if your code watches for any of these observer notifications:<br />
  <code>private-browsing<br />
  private-browsing-cancel-vote<br />
  private-browsing-change-granted<br />
  private-browsing-transition-complete</code><br />
  <br />
  Then your addon will require updating to correctly support the new per-window private browser feature in Firefox 20 (and will require updating to work correctly in releases of Firefox since the ones listed).</p>
<h2>IDLs</h2>
<p><strong>nsITransferable</strong>: see <a href="https://developer.mozilla.org/en-US/docs/Using_the_Clipboard" title="https://developer.mozilla.org/en-US/docs/Using_the_Clipboard">Using the clipboard</a> for information about the new <code>init</code> method.<br />
  <br />
  <strong>imgICache</strong>: this must no longer be obtained as a service. See <a href="https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/imgICache" title="https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/imgICache">the imgICache article</a> for more information.<br />
  <br />
  <strong>mozIAsyncFavicons</strong>/<strong>nsIFaviconService</strong>: <code>setAndFetchFaviconForPage</code>/<code>setAndLoadFaviconForPage</code> now take a required privacy status argument, either <code>nsIFaviconService.FAVICON_LOAD_PRIVATE</code> or <code>nsIFaviconService.FAVICON_LOAD_NON_PRIVATE</code>.<br />
  <br />
  <strong>nsIWebBrowserPersist</strong>: <code>saveURI</code> gained a new argument, see <a href="https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsIWebBrowserPersist" title="https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsIWebBrowserPersist">the nsIWebBrowserPersist docs</a> for more information.<br />
  <br />
  <strong>nsIContentPrefService</strong>: <code>getPref</code>, <code>setPref</code>, <code>hasPref</code>, <code>hasCachedPref</code>, <code>removePref</code>, <code>removeGroupedPrefs</code>, <code>removePrefsByName</code>, <code>getPrefs</code>, and <code>getPrefsByName</code> all take a required <code>nsILoadContext</code> argument to indicate the privacy status of the pref in question. Use <code>PrivateBrowsingUtils.getPrivacyContextFromWindow(win)</code> to obtain it from the relevant window.<br />
  <br />
  <strong>nsIDownloadManager</strong>/<strong>nsIDownload</strong>:</p>
<ul>
  <li>Integer download IDs (and specifically the <code>id</code> property of <code>nsIDownload)</code> are deprecated, and don't allow access to private downloads. All downloads now use GUIDs, and contain a new guid property.</li>
  <li><code>nsIDownload</code> now has <code>retry</code>, <code>cancel</code>, <code>remove</code>, <code>pause</code>, and <code>resume</code> methods which should be used instead of deprecated similarly-named <code>nsIDownloadManager</code> methods.</li>
  <li><code>nsIDownload</code>'s <code>getDownload</code> method is deprecated; use the asynchronous <code>getDownloadByGUID</code> method instead.</li>
  <li><code>nsIDownloadManager</code> now has <code>activePrivateDownloads</code>, <code>activePrivateDownloadCount</code>, and <code>privateDBConnection</code> members to complement the existing public ones</li>
  <li><code>nsIDownloadManager</code>'s <code>addListener</code> method is deprecated. <code>addPrivacyAwareListener</code> should be used instead, or no notifications will be received for private downloads</li>
  <li>New <code>download-manager-remove-download-guid</code> notification, which passes an <code>nsISupportsCString</code> subject for the GUID or <code>null</code></li>
</ul>
<p><br />
  <strong>nsIHttpAuthManager</strong>: <code>setAuthIdentity</code> and <code>getAuthIdentity</code> now take an optional boolean parameter to indicate whether the identity is classified as private.<br />
  <br />
  <strong>nsIStrictTransportSecurityService</strong>: <code>processStsHeader</code>, <code>removeStsState</code>, <code>isStsHost</code>, and <code>isStsUri</code> now take a flags parameter that understands <code>nsISocketProvider.NO_PERMANENT_STORAGE</code> or nothing.<br />
  <br />
  <strong>nsIPrivateBrowsingService</strong>: this service is deprecated, and as of Firefox 20 the value returned by privateBrowsingEnabled should not be trusted.</p>
<p>&nbsp;</p>
<h2>Observer notifications</h2>
<p>None of the ones listed above will be sent as of Firefox 20. The <a href="https://developer.mozilla.org/en-US/docs/Supporting_per-window_private_browsing" title="https://developer.mozilla.org/en-US/docs/Supporting_per-window_private_browsing">supporting per-window private browsing</a> article explains further about the equivalent notifications, which are all backwards compatible through to Firefox 12 (and are sent side-by-side with the global private browsing notifications in older versions).<br />
  &nbsp;</p>
<h2>Chrome APIs</h2>
<p><strong>OpenBrowserWindow</strong><strong>:</strong> takes an optional parameter to indicate desired properties of the window. Passing <code>{private: true}</code> will cause a private window to open, otherwise the window will always be non-private. Use <code>{private: PrivateBrowsingUtils.isWindowPrivate(window)}</code> to open a window that matches the current window's privacy status.<br />
  <br />
  <strong>openLinkIn</strong><strong>:</strong> can receive an extra <code>private</code> boolean property in the parameter object.<br />
  <br />
  <strong>internalSave</strong>: takes a new required Document argument (prior to the optional boolean and string arguments) indicating the document which originated the save action.<br />
  <br />
  <strong>gPrivateBrowsingUI</strong>: can no longer be used to control private browsing of any kind. Any new private browsing session should be opened using <code>OpenBrowserWindow</code>, and any queries for private browsing status should use <code>PrivateBrowsingUtils.isWindowPrivate(win)</code> on a relevant window object.<br />
  <br />
  <strong>saveURL</strong>: takes a new required Document argument indicating the source of the URL being saved.</p>
Revert to this revision