---

WebPolicyDelegate Protocol Reference

(informal protocol)

Overview

WebView policy delegates implement this informal protocol to modify the policy decisions that are made when handling URLs or the data they represent. Delegates make policy decisions by sending appropriate messages to the listener argument that conforms to the WebPolicyDecisionListener protocol. The methods in this protocol are typically invoked in the following order.

The webView:decidePolicyForNewWindowAction:request:newFrameName:decisionListener: method is invoked once for every load.

The webView:decidePolicyForNavigationAction:request:frame:decisionListener: method may be invoked zero or more times after a load started. This method is invoked every time a server redirect is encountered unless blocked by an earlier policy decision.

The webView:decidePolicyForMIMEType:request:frame:decisionListener: method is invoked once the MIME type of the content is known unless blocked by an earlier policy decision.

The webView:unableToImplementPolicyWithError:frame: method is invoked when an error occurs implementing a policy decision.

Tasks

Making Content Decisions

• – webView:decidePolicyForMIMEType:request:frame:decisionListener:

Making Navigation Decisions

• – webView:decidePolicyForNavigationAction:request:frame:decisionListener:

Making New Window Decisions

• – webView:decidePolicyForNewWindowAction:request:newFrameName:decisionListener:

Handling Errors

• – webView:unableToImplementPolicyWithError:frame:

Instance Methods

webView:decidePolicyForMIMEType:request:frame:decisionListener:

Decides whether to display content with a given MIME type.

- (void)webView:(WebView *)sender decidePolicyForMIMEType:(NSString *)type request:(NSURLRequest *)request frame:(WebFrame *)frame decisionListener:(id < WebPolicyDecisionListener >)listener

Discussion

This method is invoked when a decision needs to be made on handling MIME content, specified by type, for request in frame. The receiver implements a policy decision by sending one of the WebPolicyDecisionListener protocol messages to listener. This method is invoked during the process of loading content for request, after webView:didStartProvisionalLoadForFrame: is sent to the WebView.

If you do not implement this method, the default behavior is as follows. If request is not a directory and sending canShowMIMEType: to sender returns YES, then use is sent to listener. Otherwise, ignore is sent to listener.

In some rare cases, multiple responses may be received for a single resource. This happens in the case of multipart/x-mixed-replace, also known as a “server push.” In this case, this method will be invoked multiple times.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebPolicyDelegate.h

webView:decidePolicyForNavigationAction:request:frame:decisionListener:

Routes a navigation action internally or to an external viewer.

- (void)webView:(WebView *)sender decidePolicyForNavigationAction:(NSDictionary *)actionInformation request:(NSURLRequest *)request frame:(WebFrame *)frame decisionListener:(id < WebPolicyDecisionListener >)listener

Discussion

This method is invoked when a navigation decision needs to be made for request in frame. The actionInformation argument describes the action that triggered this navigation request. The possible key-value pairs in this dictionary are defined in “Constants.” The receiver implements a policy decision by sending one of the WebPolicyDecisionListener protocol messages to listener. This method is invoked when ever a server redirect is encountered, and before loading starts.

If you do not implement this method, the default behavior is as follows. If the Web Kit can handle the action, then use is sent to listener, otherwise, ignore is sent to listener and openURL: is sent to the shared NSWorkspace to open the URL in an external application. The Web Kit can handle the action if sending canHandleRequest: to the NSURLConnection object returns YES, or the request is for an error page.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebPolicyDelegate.h

webView:decidePolicyForNewWindowAction:request:newFrameName:decisionListener:

Decides whether to allow a targeted navigation event, such as opening a link in a new window.

- (void)webView:(WebView *)sender decidePolicyForNewWindowAction:(NSDictionary *)actionInformation request:(NSURLRequest *)request newFrameName:(NSString *)frameName decisionListener:(id < WebPolicyDecisionListener >)listener

Discussion

This method is invoked when a targeted navigation decision needs to be made for request in frame. A targeted navigation typically opens a new window to display that content. The actionInformation argument describes the action that triggered this navigation request. The possible key-value pairs in this dictionary are defined in “Constants.” The receiver implements a policy decision by sending one of the WebPolicyDecisionListener protocol messages to listener. This method allows delegates to modify the behavior of targeted links which normally open a new window. Delegates might do something else, such as download or present the content in a special way. If this method sends use to listener then the new window will be opened, and webView:decidePolicyForNavigationAction:request:frame:decisionListener: will be invoked with a WebNavigationTypeOther as the value for the WebActionNavigationTypeKey key in the action dictionary.

The default behavior sends use to listener,

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebPolicyDelegate.h

webView:unableToImplementPolicyWithError:frame:

Handles or drops events that were rejected by a policy maker.

- (void)webView:(WebView *)sender unableToImplementPolicyWithError:(NSError *)error frame:(WebFrame *)frame

Discussion

This method is invoked when a policy decision failed in frame. The error argument describes the error that occurred. Delegates might implement this method to display or log an error message. If you do not implement this method, no action is taken.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebPolicyDelegate.h

Constants

These are the possible keys that might appear in an action dictionary passed as an argument to the webView:decidePolicyForNavigationAction:request:frame:decisionListener: and webView:decidePolicyForNewWindowAction:request:newFrameName:decisionListener: methods.

These are the possible values for the WebActionNavigationTypeKey that appears in an action dictionary.

---