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