|
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 Computer, 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 <Cocoa/Cocoa.h> |
|
30 |
|
31 @class NSError; |
|
32 @class NSURLResponse; |
|
33 @class NSURLRequest; |
|
34 @class WebView; |
|
35 @class WebFrame; |
|
36 @class WebPolicyPrivate; |
|
37 |
|
38 /*! |
|
39 @enum WebNavigationType |
|
40 @abstract The type of action that triggered a possible navigation. |
|
41 @constant WebNavigationTypeLinkClicked A link with an href was clicked. |
|
42 @constant WebNavigationTypeFormSubmitted A form was submitted. |
|
43 @constant WebNavigationTypeBackForward The user chose back or forward. |
|
44 @constant WebNavigationTypeReload The User hit the reload button. |
|
45 @constant WebNavigationTypeFormResubmitted A form was resubmitted (by virtue of doing back, forward or reload). |
|
46 @constant WebNavigationTypeOther Navigation is taking place for some other reason. |
|
47 */ |
|
48 |
|
49 typedef enum { |
|
50 WebNavigationTypeLinkClicked, |
|
51 WebNavigationTypeFormSubmitted, |
|
52 WebNavigationTypeBackForward, |
|
53 WebNavigationTypeReload, |
|
54 WebNavigationTypeFormResubmitted, |
|
55 WebNavigationTypeOther |
|
56 } WebNavigationType; |
|
57 |
|
58 extern NSString *WebActionNavigationTypeKey; // NSNumber (WebNavigationType) |
|
59 extern NSString *WebActionElementKey; // NSDictionary of element info |
|
60 extern NSString *WebActionButtonKey; // NSNumber (0 for left button, 1 for middle button, 2 for right button) |
|
61 extern NSString *WebActionModifierFlagsKey; // NSNumber (unsigned) |
|
62 extern NSString *WebActionOriginalURLKey; // NSURL |
|
63 |
|
64 /*! |
|
65 @protocol WebPolicyDecisionListener |
|
66 @discussion This protocol is used to call back with the results of a |
|
67 policy decision. This provides the ability to make these decisions |
|
68 asyncrhonously, which means the decision can be made by prompting |
|
69 with a sheet, for example. |
|
70 */ |
|
71 |
|
72 @protocol WebPolicyDecisionListener <NSObject> |
|
73 |
|
74 /*! |
|
75 @method use |
|
76 @abstract Use the resource |
|
77 @discussion If there remain more policy decisions to be made, then |
|
78 the next policy delegate method gets to decide. This will be |
|
79 either the next navigation policy delegate if there is a redirect, |
|
80 or the content policy delegate. If there are no more policy |
|
81 decisions to be made, the resource will be displayed inline if |
|
82 possible. If there is no view available to display the resource |
|
83 inline, then unableToImplementPolicyWithError:frame: will be |
|
84 called with an appropriate error. |
|
85 |
|
86 <p>If a new window is going to be created for this navigation as a |
|
87 result of frame targetting, then it will be created once you call |
|
88 this method. |
|
89 */ |
|
90 - (void)use; |
|
91 /*! |
|
92 @method download |
|
93 @abstract Download the resource instead of displaying it. |
|
94 @discussion This method is more than just a convenience because it |
|
95 allows an in-progress navigation to be converted to a download |
|
96 based on content type, without having to stop and restart the |
|
97 load. |
|
98 */ |
|
99 - (void)download; |
|
100 |
|
101 /*! |
|
102 @method ignore |
|
103 @abstract Do nothing (but the client may choose to handle the request itself) |
|
104 @discussion A policy of ignore prevents WebKit from doing anything |
|
105 further with the load, however, the client is still free to handle |
|
106 the request in some other way, such as opening a new window, |
|
107 opening a new window behind the current one, opening the URL in an |
|
108 external app, revealing the location in Finder if a file URL, etc. |
|
109 */ |
|
110 - (void)ignore; |
|
111 |
|
112 @end |
|
113 |
|
114 |
|
115 /*! |
|
116 @category WebPolicyDelegate |
|
117 @discussion While loading a URL, WebKit asks the WebPolicyDelegate for |
|
118 policies that determine the action of what to do with the URL or the data that |
|
119 the URL represents. Typically, the policy handler methods are called in this order: |
|
120 |
|
121 decidePolicyForNewWindowAction:request:newFrameName:decisionListener: (at most once)<BR> |
|
122 decidePolicyForNavigationAction:request:frame:decisionListener: (zero or more times)<BR> |
|
123 decidePolicyForMIMEType:request:frame: (zero or more times)<BR> |
|
124 |
|
125 New window policy is always checked. Navigation policy is checked |
|
126 for the initial load and every redirect unless blocked by an |
|
127 earlier policy. Content policy is checked once the content type is |
|
128 known, unless an earlier policy prevented it. |
|
129 |
|
130 In rare cases, content policy might be checked more than |
|
131 once. This occurs when loading a "multipart/x-mixed-replace" |
|
132 document, also known as "server push". In this case, multiple |
|
133 documents come in one navigation, with each replacing the last. In |
|
134 this case, conent policy will be checked for each one. |
|
135 */ |
|
136 @interface NSObject (WebPolicyDelegate) |
|
137 |
|
138 /*! |
|
139 @method webView:decidePolicyForNavigationAction:request:frame:decisionListener: |
|
140 @abstract This method is called to decide what to do with a proposed navigation. |
|
141 @param actionInformation Dictionary that describes the action that triggered this navigation. |
|
142 @param request The request for the proposed navigation |
|
143 @param frame The WebFrame in which the navigation is happening |
|
144 @param listener The object to call when the decision is made |
|
145 @discussion This method will be called before loading starts, and |
|
146 on every redirect. |
|
147 */ |
|
148 - (void)webView:(WebView *)webView decidePolicyForNavigationAction:(NSDictionary *)actionInformation |
|
149 request:(NSURLRequest *)request |
|
150 frame:(WebFrame *)frame |
|
151 decisionListener:(id<WebPolicyDecisionListener>)listener; |
|
152 |
|
153 /*! |
|
154 @method webView:decidePolicyForNewWindowAction:request:newFrameName:decisionListener: |
|
155 @discussion This method is called to decide what to do with an targetted nagivation that would open a new window. |
|
156 @param actionInformation Dictionary that describes the action that triggered this navigation. |
|
157 @param request The request for the proposed navigation |
|
158 @param frame The frame in which the navigation is taking place |
|
159 @param listener The object to call when the decision is made |
|
160 @discussion This method is provided so that modified clicks on a targetted link which |
|
161 opens a new frame can prevent the new window from being opened if they decide to |
|
162 do something else, like download or present the new frame in a specialized way. |
|
163 |
|
164 <p>If this method picks a policy of Use, the new window will be |
|
165 opened, and decidePolicyForNavigationAction:request:frame:decisionListner: |
|
166 will be called with a WebNavigationType of WebNavigationTypeOther |
|
167 in its action. This is to avoid possible confusion about the modifiers. |
|
168 */ |
|
169 - (void)webView:(WebView *)webView decidePolicyForNewWindowAction:(NSDictionary *)actionInformation |
|
170 request:(NSURLRequest *)request |
|
171 newFrameName:(NSString *)frameName |
|
172 decisionListener:(id<WebPolicyDecisionListener>)listener; |
|
173 |
|
174 /*! |
|
175 @method webView:decidePolicyForMIMEType:request:frame: |
|
176 @discussion Returns the policy for content which has been partially loaded. |
|
177 Sent after webView:didStartProvisionalLoadForFrame: is sent on the WebFrameLoadDelegate. |
|
178 @param type MIME type for the resource. |
|
179 @param request A NSURLRequest for the partially loaded content. |
|
180 @param frame The frame which is loading the URL. |
|
181 @param listener The object to call when the decision is made |
|
182 */ |
|
183 - (void)webView:(WebView *)webView decidePolicyForMIMEType:(NSString *)type |
|
184 request:(NSURLRequest *)request |
|
185 frame:(WebFrame *)frame |
|
186 decisionListener:(id<WebPolicyDecisionListener>)listener; |
|
187 |
|
188 /*! |
|
189 @method webView:unableToImplementPolicy:error:forURL:inFrame: |
|
190 @discussion Called when a WebPolicy could not be implemented. It is up to the client to display appropriate feedback. |
|
191 @param policy The policy that could not be implemented. |
|
192 @param error The error that caused the policy to not be implemented. |
|
193 @param URL The URL of the resource for which a particular action was requested but failed. |
|
194 @param frame The frame in which the policy could not be implemented. |
|
195 */ |
|
196 - (void)webView:(WebView *)webView unableToImplementPolicyWithError:(NSError *)error frame:(WebFrame *)frame; |
|
197 |
|
198 @end |