1/*
2 * Copyright (C) 2006, 2007, 2008 Apple Inc.  All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 * 1. Redistributions of source code must retain the above copyright
8 *    notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 *    notice, this list of conditions and the following disclaimer in the
11 *    documentation and/or other materials provided with the distribution.
12 *
13 * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY
14 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE COMPUTER, INC. OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
18 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
19 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
20 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
21 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
23 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24 */
25
26#ifndef DO_NO_IMPORTS
27import "oaidl.idl";
28import "ocidl.idl";
29import "IWebView.idl";
30import "IWebURLRequest.idl";
31#endif
32
33interface IWebError;
34interface IWebURLResponse;
35interface IWebURLRequest;
36interface IWebView;
37interface IWebFrame;
38interface IWebPolicyPrivate;
39
40/*!
41    @enum WebNavigationType
42    @abstract The type of action that triggered a possible navigation.
43    @constant WebNavigationTypeLinkClicked A link with an href was clicked.
44    @constant WebNavigationTypeFormSubmitted A form was submitted.
45    @constant WebNavigationTypeBackForward The user chose back or forward.
46    @constant WebNavigationTypeReload The User hit the reload button.
47    @constant WebNavigationTypeFormResubmitted A form was resubmitted (by virtue of doing back, forward or reload).
48    @constant WebNavigationTypeOther Navigation is taking place for some other reason.
49*/
50
51typedef enum WebNavigationType {
52    WebNavigationTypeLinkClicked,
53    WebNavigationTypeFormSubmitted,
54    WebNavigationTypeBackForward,
55    WebNavigationTypeReload,
56    WebNavigationTypeFormResubmitted,
57    WebNavigationTypeOther
58} WebNavigationType;
59
60cpp_quote("#define WebActionButtonKey TEXT(\"WebActionButtonKey\")")
61cpp_quote("#define WebActionElementKey TEXT(\"WebActionElementKey\")")
62cpp_quote("#define WebActionFormKey TEXT(\"WebActionFormKey\")")
63cpp_quote("#define WebActionModifierFlagsKey TEXT(\"WebActionModifierFlagsKey\")")
64cpp_quote("#define WebActionNavigationTypeKey TEXT(\"WebActionNavigationTypeKey\")")
65cpp_quote("#define WebActionOriginalURLKey TEXT(\"WebActionOriginalURLKey\")")
66
67/*!
68    @protocol WebPolicyDecisionListener
69    @discussion This protocol is used to call back with the results of a
70    policy decision. This provides the ability to make these decisions
71    asyncrhonously, which means the decision can be made by prompting
72    with a sheet, for example.
73    @protocol WebPolicyDecisionListener <NSObject>
74*/
75[
76    object,
77    oleautomation,
78    uuid(DFCDE523-FD96-4f95-958B-151540FE122A),
79    pointer_default(unique)
80]
81interface IWebPolicyDecisionListener : IUnknown
82{
83    /*!
84        @method use
85        @abstract Use the resource
86        @discussion If there remain more policy decisions to be made, then
87        the next policy delegate method gets to decide. This will be
88        either the next navigation policy delegate if there is a redirect,
89        or the content policy delegate. If there are no more policy
90        decisions to be made, the resource will be displayed inline if
91        possible. If there is no view available to display the resource
92        inline, then unableToImplementPolicyWithError:frame: will be
93        called with an appropriate error.
94
95        <p>If a new window is going to be created for this navigation as a
96        result of frame targetting, then it will be created once you call
97        this method.
98        - (void)use;
99    */
100    HRESULT use();
101
102    /*!
103        @method download
104        @abstract Download the resource instead of displaying it.
105        @discussion This method is more than just a convenience because it
106        allows an in-progress navigation to be converted to a download
107        based on content type, without having to stop and restart the
108        load.
109        - (void)download;
110    */
111    HRESULT download();
112
113    /*!
114        @method ignore
115        @abstract Do nothing (but the client may choose to handle the request itself)
116        @discussion A policy of ignore prevents WebKit from doing anything
117        further with the load, however, the client is still free to handle
118        the request in some other way, such as opening a new window,
119        opening a new window behind the current one, opening the URL in an
120        external app, revealing the location in Finder if a file URL, etc.
121        - (void)ignore;
122    */
123    HRESULT ignore();
124}
125
126/*!
127    @category WebPolicyDelegate
128    @discussion While loading a URL, WebKit asks the WebPolicyDelegate for
129    policies that determine the action of what to do with the URL or the data that
130    the URL represents. Typically, the policy handler methods are called in this order:
131
132    decidePolicyForNewWindowAction:request:newFrameName:decisionListener: (at most once)<BR>
133    decidePolicyForNavigationAction:request:frame:decisionListener: (zero or more times)<BR>
134    decidePolicyForMIMEType:request:frame: (zero or more times)<BR>
135
136    New window policy is always checked. Navigation policy is checked
137    for the initial load and every redirect unless blocked by an
138    earlier policy. Content policy is checked once the content type is
139    known, unless an earlier policy prevented it.
140
141    In rare cases, content policy might be checked more than
142    once. This occurs when loading a "multipart/x-mixed-replace"
143    document, also known as "server push". In this case, multiple
144    documents come in one navigation, with each replacing the last. In
145    this case, conent policy will be checked for each one.
146    @interface NSObject (WebPolicyDelegate)
147*/
148[
149    object,
150    oleautomation,
151    uuid(9B0BAE6C-A496-4000-9E22-2E89F0747401),
152    pointer_default(unique)
153]
154interface IWebPolicyDelegate : IUnknown
155{
156    /*!
157       @method webView:decidePolicyForNavigationAction:request:frame:decisionListener:
158       @abstract This method is called to decide what to do with a proposed navigation.
159       @param actionInformation Dictionary that describes the action that triggered this navigation.
160       @param request The request for the proposed navigation
161       @param frame The WebFrame in which the navigation is happening
162       @param listener The object to call when the decision is made
163       @discussion This method will be called before loading starts, and
164       on every redirect.
165        - (void)webView:(WebView *)webView decidePolicyForNavigationAction:(NSDictionary *)actionInformation
166                                                                   request:(NSURLRequest *)request
167                                                                     frame:(WebFrame *)frame
168                                                          decisionListener:(id<WebPolicyDecisionListener>)listener;
169    */
170    HRESULT decidePolicyForNavigationAction([in] IWebView* webView, [in] IPropertyBag* actionInformation, [in] IWebURLRequest* request, [in] IWebFrame* frame, [in] IWebPolicyDecisionListener* listener);
171
172    /*!
173        @method webView:decidePolicyForNewWindowAction:request:newFrameName:decisionListener:
174        @discussion This method is called to decide what to do with an targetted nagivation that would open a new window.
175        @param actionInformation Dictionary that describes the action that triggered this navigation.
176        @param request The request for the proposed navigation
177        @param frame The frame in which the navigation is taking place
178        @param listener The object to call when the decision is made
179        @discussion This method is provided so that modified clicks on a targetted link which
180        opens a new frame can prevent the new window from being opened if they decide to
181        do something else, like download or present the new frame in a specialized way.
182
183        <p>If this method picks a policy of Use, the new window will be
184        opened, and decidePolicyForNavigationAction:request:frame:decisionListner:
185        will be called with a WebNavigationType of WebNavigationTypeOther
186        in its action. This is to avoid possible confusion about the modifiers.
187        - (void)webView:(WebView *)webView decidePolicyForNewWindowAction:(NSDictionary *)actionInformation
188                                                                  request:(NSURLRequest *)request
189                                                             newFrameName:(NSString *)frameName
190                                                         decisionListener:(id<WebPolicyDecisionListener>)listener;
191    */
192    HRESULT decidePolicyForNewWindowAction([in] IWebView* webView, [in] IPropertyBag* actionInformation, [in] IWebURLRequest* request, [in] BSTR frameName, [in] IWebPolicyDecisionListener* listener);
193
194    /*!
195        @method webView:decidePolicyForMIMEType:request:frame:
196        @discussion Returns the policy for content which has been partially loaded.
197        Sent after webView:didStartProvisionalLoadForFrame: is sent on the WebFrameLoadDelegate.
198        @param type MIME type for the resource.
199        @param request A NSURLRequest for the partially loaded content.
200        @param frame The frame which is loading the URL.
201        @param listener The object to call when the decision is made
202        - (void)webView:(WebView *)webView decidePolicyForMIMEType:(NSString *)type
203                                                           request:(NSURLRequest *)request
204                                                             frame:(WebFrame *)frame
205                                                  decisionListener:(id<IWebPolicyDecisionListener>)listener;
206    */
207    HRESULT decidePolicyForMIMEType([in] IWebView* webView, [in] BSTR type, [in] IWebURLRequest* request, [in] IWebFrame* frame, [in] IWebPolicyDecisionListener* listener);
208
209    /*!
210        @method webView:unableToImplementPolicy:error:forURL:inFrame:
211        @discussion Called when a WebPolicy could not be implemented. It is up to the client to display appropriate feedback.
212        @param policy The policy that could not be implemented.
213        @param error The error that caused the policy to not be implemented.
214        @param URL The URL of the resource for which a particular action was requested but failed.
215        @param frame The frame in which the policy could not be implemented.
216        - (void)webView:(WebView *)webView unableToImplementPolicyWithError:(NSError *)error frame:(WebFrame *)frame;
217    */
218    HRESULT unableToImplementPolicyWithError([in] IWebView* webView, [in] IWebError* error, [in] IWebFrame* frame);
219}
220