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