1/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2/* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6#include "nsIProxiedProtocolHandler.idl"
7
8[scriptable, uuid(c48126d9-2ddd-485b-a51a-378e917e75f8)]
9interface nsIHttpProtocolHandler : nsIProxiedProtocolHandler
10{
11    /**
12     * Get the HTTP advertised user agent string.
13     */
14    [must_use] readonly attribute ACString userAgent;
15
16    /**
17     * Get the application name.
18	 *
19     * @return The name of this application (eg. "Mozilla").
20     */
21    [must_use] readonly attribute ACString appName;
22
23    /**
24     * Get the application version string.
25     *
26     * @return The complete version (major and minor) string. (eg. "5.0")
27     */
28    [must_use] readonly attribute ACString appVersion;
29
30    /**
31     * Get the current platform.
32     *
33     * @return The platform this application is running on
34     *		   (eg. "Windows", "Macintosh", "X11")
35     */
36    [must_use] readonly attribute ACString platform;
37
38    /**
39     * Get the current oscpu.
40     *
41     * @return The oscpu this application is running on
42     */
43    [must_use] readonly attribute ACString oscpu;
44
45    /**
46     * Get the application comment misc portion.
47     */
48    [must_use] readonly attribute ACString misc;
49
50};
51
52%{C++
53// ----------- Categories -----------
54/**
55 * At initialization time, the HTTP handler will initialize each service
56 * registered under this category:
57 */
58#define NS_HTTP_STARTUP_CATEGORY "http-startup-category"
59
60// ----------- Observer topics -----------
61/**
62 * nsIObserver notification corresponding to startup category.  Services
63 * registered under the startup category will receive this observer topic at
64 * startup if they implement nsIObserver.  The "subject" of the notification
65 * is the nsIHttpProtocolHandler instance.
66 */
67#define NS_HTTP_STARTUP_TOPIC "http-startup"
68
69/**
70 * This observer topic is notified when an HTTP channel is opened.
71 * It is similar to http-on-modify-request, except that
72 * 1) The notification is guaranteed to occur before on-modify-request, during
73 *    the AsyncOpen call itself.
74 * 2) It only occurs for the initial open of a channel, not for internal
75 *    asyncOpens that happen during redirects, etc.
76 * 3) Some information (most notably nsIProxiedChannel.proxyInfo) may not be set
77 *    on the channel object yet.
78 *
79 * The "subject" of the notification is the nsIHttpChannel instance.
80 *
81 * Generally the 'http-on-modify-request' notification is preferred unless the
82 * synchronous, during-asyncOpen behavior that this notification provides is
83 * required.
84 */
85#define NS_HTTP_ON_OPENING_REQUEST_TOPIC "http-on-opening-request"
86
87/**
88 * Before an HTTP request is sent to the server, this observer topic is
89 * notified.  The observer of this topic can then choose to set any additional
90 * headers for this request before the request is actually sent to the server.
91 * The "subject" of the notification is the nsIHttpChannel instance.
92 */
93#define NS_HTTP_ON_MODIFY_REQUEST_TOPIC "http-on-modify-request"
94
95/**
96 * Before an HTTP connection to the server is created, this observer topic is
97 * notified.  This observer happens after HSTS upgrades, etc. are set, providing
98 * access to the full set of request headers. The observer of this topic can
99 * choose to set any additional headers for this request before the request is
100 * actually sent to the server. The "subject" of the notification is the
101 * nsIHttpChannel instance.
102 */
103#define NS_HTTP_ON_BEFORE_CONNECT_TOPIC "http-on-before-connect"
104
105/**
106 * After an HTTP server response is received, this observer topic is notified.
107 * The observer of this topic can interrogate the response.  The "subject" of
108 * the notification is the nsIHttpChannel instance.
109 */
110#define NS_HTTP_ON_EXAMINE_RESPONSE_TOPIC "http-on-examine-response"
111
112/**
113 * The observer of this topic is notified after the received HTTP response
114 * is merged with data from the browser cache.  This means that, among other
115 * things, the Content-Type header will be set correctly.
116 */
117#define NS_HTTP_ON_EXAMINE_MERGED_RESPONSE_TOPIC "http-on-examine-merged-response"
118
119/**
120 * The observer of this topic is notified before data is read from the cache.
121 * The notification is sent if and only if there is no network communication
122 * at all.
123 */
124#define NS_HTTP_ON_EXAMINE_CACHED_RESPONSE_TOPIC "http-on-examine-cached-response"
125
126/**
127 * Before an HTTP request corresponding to a channel with the LOAD_DOCUMENT_URI
128 * flag is sent to the server, this observer topic is notified. The observer of
129 * this topic can then choose to modify the user agent for this request before
130 * the request is actually sent to the server. Additionally, the modified user
131 * agent will be propagated to sub-resource requests from the same load group.
132 */
133#define NS_HTTP_ON_USERAGENT_REQUEST_TOPIC "http-on-useragent-request"
134
135/**
136 * This topic is notified for every http channel right after it called
137 * OnStopRequest on its listener, regardless whether it was finished
138 * successfully, failed or has been canceled.
139 */
140#define NS_HTTP_ON_STOP_REQUEST_TOPIC "http-on-stop-request"
141
142%}
143