Observer Notifications

  • Revision slug: Observer_Notifications
  • Revision title: Observer Notifications
  • Revision id: 53197
  • Created:
  • Creator: Mossop
  • Is current revision? No
  • Comment 11 words removed

Revision Content

Observer topics

The following are topics that you can observe during the course of an application. Unless otherwise noted you register for the topics using the observer service.

Application startup

These are the topics that you can observe on startup, in order of appearance.

If your component requires access to the user profile, or any services which require access to the profile (preferences, bookmarks, etc.) then a common pattern is to register with the <a href=\"en/NsICategoryManager\">category manager</a> for the app-startup topic which can be done in the component's registration code, and then in that notification register with the observer service for the profile-after-change notification.

{{ Fx_minversion_inline("3") }} Starting in Firefox 3.5 components can simply register for the profile-after-change notification in the category manager

Topic Description
xpcom-startup Called when xpcom is initialized. Many things are not available for use at this point.

{{ Note("You must register with the category manager to receive this notification.") }}

app-startup General event for application startup.

{{ Note("You must register with the category manager to receive this notification.") }}

profile-do-change This is fired after the profile has been selected. You will not be able to access user preferences, bookmarks, or anything that uses the profile folder until this event occurs. This occurs after any profile migration.
profile-after-change

This is fired after all the observers for profile-do-change have been notified.

{{ Fx_minversion_inline("3") }}You can register with the category manager to receive this notification.

final-ui-startup Triggered just before the first window for the application is displayed.
sessionstore-windows-restored

{{ Fx_minversion_inline("3") }} Sent by the session restore process to indicate that all initial browser windows have opened. Note that while the window are open and the chrome loaded the tabs in the windows may still be being restored after this notification.

{{ Note("This notification is specific to the Firefox application") }}

Application shutdown

These are the topics that you can observe on shutdown, in order of appearance.

Topic Description
quit-application-requested Something has requested that the application be shutdown. You can cancel the shutdown from here.
quit-application-granted All observers have agreed to the shutdown.
quit-application The application is about to quit. This can be in response to a normal shutdown, or a restart. {{ Note("The data value for this notification is either 'shutdown' or 'restart'.") }}
profile-change-net-teardown The network connection is going offline at this point. {{ Note("The data value for this notification is either 'shutdown-persist' or 'shutdown-cleanse'.") }}
profile-change-teardown Part of the shutdown, profile data is still available at this point. {{ Note("The data value for this notification is either 'shutdown-persist' or 'shutdown-cleanse'.") }}
profile-before-change Called just before the profile is lost. {{ Note("The data value for this notification is either 'shutdown-persist' or 'shutdown-cleanse'.") }}
xpcom-shutdown This is the end. Many things will not be available here.

Windows

These topics indicate points of interest during the lifetime of a window.

Topic Description
toplevel-window-ready Called just after a new top level window has been opened and is ready, but has not yet loaded a document.
xul-window-registered Called just after a top level XUL window is registered with the window mediator service.
xul-window-visible Called just after a XUL window is made visible.
xul-window-destroyed Called just before a XUL window is destroyed.
dom-window-destroyed {{ Fx_minversion_inline("3") }} Called just before a DOM window is destroyed.

IO Notifications

These topics can be used to watch the IO service for useful information.

Topic Description
offline-requested Called to query whether the application can go offline. The attempt to go offline can be cancelled.

{{ Note("If your code chooses to cancel the attempt to go offline, it must notify the user.") }}

network:offline-about-to-go-offline Called just before all network IO is taken offline.
network:offline-status-changed Called when the offline state has changed. {{ Note("The data value for this notification 'offline' or 'online' to indicate the new state.") }}

HTTP requests

These are the topics that you can observe during a HTTP request (see Setting HTTP request headers and Creating Sandboxed HTTP Connections). Both are passed an {{ Interface("nsIHttpChannel") }} as the subject parameter.

Topic Description
http-on-modify-request Called as a http request is made. The channel is available to allow you to modify headers and such.
http-on-examine-response Called after a response has been received from the webserver. Headers are available on the channel.

Cookies

These topics indicate whenever a cookie has been changed (added, changed, cleared, or deleted) or its setting rejected by the browser. See {{ Interface("nsICookieService") }} for details.

Topic Description
cookie-changed Called upon a cookie change (added, changed, cleared, or deleted)
cookie-rejected Called when the setting of a cookie was rejected by the browser (per the user's preferences)

Extension Manager

This topic indicates when the extension manager performs some action. Note that any action will be taken the next time the application starts. See {{ Interface("nsIExtensionManager") }} for details.

Topic Data Description
em-action-requested item-installed A new extension has been installed.
em-action-requested item-upgraded A different version of an existing extension has been installed.
em-action-requested item-uninstalled An addon has been marked to be uninstalled.
em-action-requested item-enabled An addon has been enabled.
em-action-requested item-disabled An addon has been disabled.
em-action-requested item-cancel-action A previous action has been cancelled.

Idle Service

This topic indicates when actions related to the Idle Service, provided by the {{ interface("nsIIdleService") }} interface.

Topic Data Description
idle The length of time the user has been idle, in seconds. Sent when the user becomes idle.
idle-daily The length of time the user has been idle, in seconds. Sent once a day while the user is idle. {{ gecko_minversion_inline("1.9.2") }}
back The length of time the user has been idle, in seconds. Sent when the user returns from being idle.

Login Manager

This topic indicates when actions related to the Login Manager occur.

Topic Data Description
passwordmgr-found-form noAutofillForms A login is available for this form, but autofill of forms is disabled, so the form was not automatically filled out.  {{ fx_minversion_inline("3") }}
passwordmgr-found-form autocompleteOff A login is available for this form, but autocomplete is disabled.{{ fx_minversion_inline("3") }}

Session Store

This topic indicates when actions related to Session Store occur.

Topic Data Description
sessionstore-state-read   Sent immediately after session store data is read and before it's used.  {{ fx_minversion_inline("3") }}
sessionstore-state-write   Sent immediately before the session store data is written to disk. {{ fx_minversion_inline("3") }}

{{ languages( { "ja": "ja/Observer_Notifications" } ) }}

Revision Source

<h2 name="Observer_topics">Observer topics</h2>
<p>The following are topics that you can observe during the course of an application. Unless otherwise noted you register for the topics using the <a href="/en/nsIObserverService" title="en/nsIObserverService"> observer service</a>.</p>
<h3 name="Application_startup">Application startup</h3>
<p>These are the topics that you can observe on startup, in order of appearance.</p>
<p>If your component requires access to the user profile, or any services which require access to the profile (preferences, bookmarks, etc.) then a common pattern is to register with the &lt;a href=\"en/NsICategoryManager\"&gt;category manager&lt;/a&gt; for the app-startup topic which can be done in the component's registration code, and then in that notification register with the observer service for the profile-after-change notification.</p>
<p>{{ Fx_minversion_inline("3") }} Starting in Firefox 3.5 components can simply register for the profile-after-change notification in the <a href="/en/NsICategoryManager">category manager</a></p>
<table class="standard-table"> <tbody> <tr> <th>Topic</th> <th>Description</th> </tr> <tr> <td>xpcom-startup</td> <td>Called when xpcom is initialized. Many things are not available for use at this point. <p>{{ Note("You must register with the <a href='\"en/NsICategoryManager\"'>category manager</a> to receive this notification.") }}</p> </td> </tr> <tr> <td>app-startup</td> <td>General event for application startup. <p>{{ Note("You must register with the <a href='\"en/NsICategoryManager\"'>category manager</a> to receive this notification.") }}</p> </td> </tr> <tr> <td>profile-do-change</td> <td>This is fired after the profile has been selected. You will not be able to access user preferences, bookmarks, or anything that uses the profile folder until this event occurs. This occurs after any profile migration.</td> </tr> <tr> <td>profile-after-change</td> <td> <p>This is fired after all the observers for profile-do-change have been notified.</p> <p>{{ Fx_minversion_inline("3") }}You can register with the <a class="internal" href="/en/nsICategoryManager" title="En/NsICategoryManager">category manager</a> to receive this notification.</p> </td> </tr> <tr> <td>final-ui-startup</td> <td>Triggered just before the first window for the application is displayed.</td> </tr> <tr> <td>sessionstore-windows-restored</td> <td> <p>{{ Fx_minversion_inline("3") }} Sent by the session restore process to indicate that all initial browser windows have opened. Note that while the window are open and the chrome loaded the tabs in the windows may still be being restored after this notification.</p> <p>{{ Note("This notification is specific to the Firefox application") }}</p> </td> </tr> </tbody>
</table>
<h3 name="Application_shutdown">Application shutdown</h3>
<p>These are the topics that you can observe on shutdown, in order of appearance.</p>
<table class="standard-table"> <tbody> <tr> <th>Topic</th> <th>Description</th> </tr> <tr> <td>quit-application-requested</td> <td>Something has requested that the application be shutdown. You can cancel the shutdown from here.</td> </tr> <tr> <td>quit-application-granted</td> <td>All observers have agreed to the shutdown.</td> </tr> <tr> <td>quit-application</td> <td>The application is about to quit. This can be in response to a normal shutdown, or a restart. {{ Note("The data value for this notification is either 'shutdown' or 'restart'.") }}</td> </tr> <tr> <td>profile-change-net-teardown</td> <td>The network connection is going offline at this point. {{ Note("The data value for this notification is either 'shutdown-persist' or 'shutdown-cleanse'.") }}</td> </tr> <tr> <td>profile-change-teardown</td> <td>Part of the shutdown, profile data is still available at this point. {{ Note("The data value for this notification is either 'shutdown-persist' or 'shutdown-cleanse'.") }}</td> </tr> <tr> <td>profile-before-change</td> <td>Called just before the profile is lost. {{ Note("The data value for this notification is either 'shutdown-persist' or 'shutdown-cleanse'.") }}</td> </tr> <tr> <td>xpcom-shutdown</td> <td>This is the end. Many things will not be available here.</td> </tr> </tbody>
</table>
<h3>Windows</h3>
<p>These topics indicate points of interest during the lifetime of a window.</p>
<table class="standard-table"> <tbody> <tr> <th>Topic</th> <th>Description</th> </tr> <tr> <td>toplevel-window-ready</td> <td>Called just after a new top level window has been opened and is ready, but has not yet loaded a document.</td> </tr> <tr> <td>xul-window-registered</td> <td>Called just after a top level XUL window is registered with the window mediator service.</td> </tr> <tr> <td>xul-window-visible</td> <td>Called just after a XUL window is made visible.</td> </tr> <tr> <td>xul-window-destroyed</td> <td>Called just before a XUL window is destroyed.</td> </tr> <tr> <td>dom-window-destroyed</td> <td>{{ Fx_minversion_inline("3") }} Called just before a DOM window is destroyed.</td> </tr> </tbody>
</table>
<h3 name="IO_Notifications">IO Notifications</h3>
<p>These topics can be used to watch the IO service for useful information.</p>
<table class="standard-table"> <tbody> <tr> <th>Topic</th> <th>Description</th> </tr> <tr> <td>offline-requested</td> <td>Called to query whether the application can go offline. The attempt to go offline can be cancelled. <p>{{ Note("If your code chooses to cancel the attempt to go offline, it <b>must</b> notify the user.") }}</p> </td> </tr> <tr> <td>network:offline-about-to-go-offline</td> <td>Called just before all network IO is taken offline.</td> </tr> <tr> <td>network:offline-status-changed</td> <td>Called when the offline state has changed. {{ Note("The data value for this notification 'offline' or 'online' to indicate the new state.") }}</td> </tr> </tbody>
</table>
<h3 name="HTTP_requests">HTTP requests</h3>
<p>These are the topics that you can observe during a HTTP request (see <a href="/en/Setting_HTTP_request_headers" title="en/Setting_HTTP_request_headers">Setting HTTP request headers</a> and <a href="/en/Creating_Sandboxed_HTTP_Connections#HTTP_notifications" title="en/Creating_Sandboxed_HTTP_Connections#HTTP_notifications"> Creating Sandboxed HTTP Connections</a>). Both are passed an {{ Interface("nsIHttpChannel") }} as the subject parameter.</p>
<table class="standard-table"> <tbody> <tr> <th>Topic</th> <th>Description</th> </tr> <tr> <td>http-on-modify-request</td> <td>Called as a http request is made. The channel is available to allow you to modify headers and such.</td> </tr> <tr> <td>http-on-examine-response</td> <td>Called after a response has been received from the webserver. Headers are available on the channel.</td> </tr> </tbody>
</table>
<h3 name="Cookies">Cookies</h3>
<p>These topics indicate whenever a cookie has been changed (added, changed, cleared, or deleted) or its setting rejected by the browser. See {{ Interface("nsICookieService") }} for details.</p>
<table class="standard-table"> <tbody> <tr> <th>Topic</th> <th>Description</th> </tr> <tr> <td>cookie-changed</td> <td>Called upon a cookie change (added, changed, cleared, or deleted)</td> </tr> <tr> <td>cookie-rejected</td> <td>Called when the setting of a cookie was rejected by the browser (per the user's preferences)</td> </tr> </tbody>
</table>
<h3 name="Cookies">Extension Manager</h3>
<p>This topic indicates when the extension manager performs some action. Note that any action will be taken the next time the application starts. See {{ Interface("nsIExtensionManager") }} for details.</p>
<table class="standard-table"> <tbody> <tr> <th>Topic</th> <th>Data</th> <th>Description</th> </tr> <tr> <td>em-action-requested</td> <td>item-installed</td> <td>A new extension has been installed.</td> </tr> <tr> <td>em-action-requested</td> <td>item-upgraded</td> <td>A different version of an existing extension has been installed.</td> </tr> <tr> <td>em-action-requested</td> <td>item-uninstalled</td> <td>An addon has been marked to be uninstalled.</td> </tr> <tr> <td>em-action-requested</td> <td>item-enabled</td> <td>An addon has been enabled.</td> </tr> <tr> <td>em-action-requested</td> <td>item-disabled</td> <td>An addon has been disabled.</td> </tr> <tr> <td>em-action-requested</td> <td>item-cancel-action</td> <td>A previous action has been cancelled.</td> </tr> </tbody>
</table>
<h3>Idle Service</h3>
<p>This topic indicates when actions related to the Idle Service, provided by the {{ interface("nsIIdleService") }} interface.</p>
<table class="standard-table"> <tbody> <tr> <th>Topic</th> <th>Data</th> <th>Description</th> </tr> <tr> <td>idle</td> <td>The length of time the user has been idle, in seconds.</td> <td>Sent when the user becomes idle.</td> </tr> <tr> <td>idle-daily</td> <td>The length of time the user has been idle, in seconds.</td> <td>Sent once a day while the user is idle. {{ gecko_minversion_inline("1.9.2") }}</td> </tr> <tr> <td>back</td> <td>The length of time the user has been idle, in seconds.</td> <td>Sent when the user returns from being idle.</td> </tr> </tbody>
</table>
<h3>Login Manager</h3>
<p>This topic indicates when actions related to the Login Manager occur.</p>
<table class="standard-table"> <tbody> <tr> <th>Topic</th> <th>Data</th> <th>Description</th> </tr> <tr> <td>passwordmgr-found-form</td> <td>noAutofillForms</td> <td>A login is available for this form, but autofill of forms is disabled, so the form was not automatically filled out.  {{ fx_minversion_inline("3") }}</td> </tr> <tr> <td>passwordmgr-found-form</td> <td>autocompleteOff</td> <td>A login is available for this form, but autocomplete is disabled.{{ fx_minversion_inline("3") }}</td> </tr> </tbody>
</table>
<h3>Session Store</h3>
<p>This topic indicates when actions related to Session Store occur.</p>
<table class="standard-table"> <tbody> <tr> <th>Topic</th> <th>Data</th> <th>Description</th> </tr> <tr> <td>sessionstore-state-read</td> <td> </td> <td>Sent immediately after session store data is read and before it's used.  {{ fx_minversion_inline("3") }}</td> </tr> <tr> <td>sessionstore-state-write</td> <td> </td> <td>Sent immediately before the session store data is written to disk. {{ fx_minversion_inline("3") }}</td> </tr> </tbody>
</table>
<p>{{ languages( { "ja": "ja/Observer_Notifications" } ) }}</p>
Revert to this revision