Mac Developer Library

Developer

WebKit Framework Reference WebPolicyDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

WebPolicyDelegate

The WebPolicyDelegate informal protocol works with the WebPolicyDecisionListener protocol to modify the policy decisions that the WebView class makes when handling URLs or the data objects they represent. The methods in this protocol are typically invoked in the following order.

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

  2. 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.

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

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

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import WebKit

Objective-C

@import WebKit;

Availability


Available in OS X v10.2 with Safari 1.0 and later.
Available in OS X v10.2.7 and later.
  • Decides whether to display content with a given MIME type.

    Declaration

    Swift

    func webView(_ webView: WebView!, decidePolicyForMIMEType type: String!, request request: NSURLRequest!, frame frame: WebFrame!, decisionListener listener: WebPolicyDecisionListener!)

    Objective-C

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

    Parameters

    webView

    The associated web view.

    type

    The MIME type of the content.

    request

    The request to load the content.

    frame

    The frame for displaying the content.

    listener

    The object that receives the policy decision.

    Discussion

    This method is invoked during the process of loading content for request after the webView:didStartProvisionalLoadForFrame: method in the WebFrameLoadDelegate informal protocol is called by the WebView object. The web view implements a policy decision by sending one of the WebPolicyDecisionListener protocol messages to listener.

    If you do not implement this method, the default behavior is used. The listener is told to ignore the MIME type unless webView specifies it can handle the type in its canShowMIMEType: method.

    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.

    Import Statement

    Objective-C

    @import WebKit;

    Swift

    import WebKit

    Availability

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

    Available in OS X v10.2.7 and later.

  • Routes a navigation action internally or to an external viewer.

    Declaration

    Swift

    func webView(_ webView: WebView!, decidePolicyForNavigationAction actionInformation: [NSObject : AnyObject]!, request request: NSURLRequest!, frame frame: WebFrame!, decisionListener listener: WebPolicyDecisionListener!)

    Objective-C

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

    Parameters

    webView

    The WebView object for which this object is the policy delegate.

    actionInformation

    A description of the action that triggered the navigation request. The possible key-value pairs in this dictionary are defined in Action Dictionary Keys.

    request

    The request for which the navigation is made.

    frame

    The WebFrame object in which the action occurred.

    listener

    The WebPolicyDecisionListener object that receives the policy decision.

    Discussion

    This method is invoked when a navigation decision needs to be made. The web view implements a policy decision by sending one of the WebPolicyDecisionListener protocol messages to listener. This method is invoked whenever a server redirect is encountered, and before loading starts.

    If you do not implement this method, the default behavior is used. The listener handles the navigation internally if the request is for an error page or if the canHandleRequest: method of the NSURLConnection class returns YEStrue when passed request. Otherwise, the listener ignores the navigation, and it is handled externally.

    Import Statement

    Objective-C

    @import WebKit;

    Swift

    import WebKit

    Availability

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

    Available in OS X v10.2.7 and later.

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

    Declaration

    Swift

    func webView(_ webView: WebView!, decidePolicyForNewWindowAction actionInformation: [NSObject : AnyObject]!, request request: NSURLRequest!, newFrameName frameName: String!, decisionListener listener: WebPolicyDecisionListener!)

    Objective-C

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

    Parameters

    webView

    The WebView object for which this object is the policy delegate.

    actionInformation

    A description of the action that triggered the navigation request. The possible key-value pairs in this dictionary are defined in Making content decisions.

    request

    The request for which the new window action is performed.

    frameName

    The name of the new frame that contains the content returned from the request.

    listener

    The WebPolicyDecisionListener object that receives the policy decision.

    Discussion

    This method is invoked when a targeted navigation decision needs to be made. A targeted navigation typically opens a new window to display content. 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.

    Import Statement

    Objective-C

    @import WebKit;

    Swift

    import WebKit

    Availability

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

    Available in OS X v10.2.7 and later.

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

    Declaration

    Swift

    func webView(_ webView: WebView!, unableToImplementPolicyWithError error: NSError!, frame frame: WebFrame!)

    Objective-C

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

    Parameters

    webView

    The WebView object for which this object is the policy delegate.

    error

    The error that occurred.

    frame

    The frame in which the error occurred.

    Discussion

    Delegates might implement this method to display or log an error message. If you do not implement this method, no action is taken.

    Import Statement

    Objective-C

    @import WebKit;

    Swift

    import WebKit

    Availability

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

    Available in OS X v10.2.7 and later.

  • Keys that might appear in a dictionary passed as the actionInformation parameter to the webView:decidePolicyForNavigationAction:request:frame:decisionListener: and webView:decidePolicyForNewWindowAction:request:newFrameName:decisionListener: methods.

    Declaration

    Swift

    var WebActionNavigationTypeKey: NSString! var WebActionElementKey: NSString! var WebActionButtonKey: NSString! var WebActionModifierFlagsKey: NSString! var WebActionOriginalURLKey: NSString!

    Objective-C

    extern NSString *WebActionNavigationTypeKey; extern NSString *WebActionElementKey; extern NSString *WebActionButtonKey; extern NSString *WebActionModifierFlagsKey; extern NSString *WebActionOriginalURLKey;

    Constants

    • WebActionNavigationTypeKey

      WebActionNavigationTypeKey

      The navigation type of the action. Can be any of the values defined in WebNavigationType below.

      Available in OS X v10.2 and later.

    • WebActionElementKey

      WebActionElementKey

      A dictionary containing element information. See WebView Class Reference for a description of the key-value pairs in this dictionary.

      Available in OS X v10.2 and later.

    • WebActionButtonKey

      WebActionButtonKey

      An NSNumber object where 0 indicates the left button, 1 indicates the middle button, and 2 indicates the right button.

      Available in OS X v10.2 and later.

    • WebActionModifierFlagsKey

      WebActionModifierFlagsKey

      An unsigned number that indicates the modifier flag.

      Available in OS X v10.2 and later.

    • WebActionOriginalURLKey

      WebActionOriginalURLKey

      The URL that initiated the action.

      Available in OS X v10.2 and later.

  • Possible values for the WebActionNavigationTypeKey key that appears in an action dictionary.

    Declaration

    Swift

    enum WebNavigationType : Int { case LinkClicked case FormSubmitted case BackForward case Reload case FormResubmitted case Other }

    Objective-C

    typedef enum { WebNavigationTypeLinkClicked, WebNavigationTypeFormSubmitted, WebNavigationTypeBackForward, WebNavigationTypeReload, WebNavigationTypeFormResubmitted, WebNavigationTypeOther } WebNavigationType;

    Constants

    • LinkClicked

      WebNavigationTypeLinkClicked

      A link (an href) was clicked.

      Available in OS X v10.2 and later.

    • FormSubmitted

      WebNavigationTypeFormSubmitted

      A form was submitted.

      Available in OS X v10.2 and later.

    • BackForward

      WebNavigationTypeBackForward

      The user clicked back or forward button.

      Available in OS X v10.2 and later.

    • Reload

      WebNavigationTypeReload

      The user hit the reload button.

      Available in OS X v10.2 and later.

    • FormResubmitted

      WebNavigationTypeFormResubmitted

      A form was resubmitted (through a back, forward or reload action).

      Available in OS X v10.2 and later.

    • Other

      WebNavigationTypeOther

      Navigation is taking place for some other reason.

      Available in OS X v10.2 and later.

    Import Statement

    Objective-C

    @import WebKit;

    Swift

    import WebKit

    Availability

    Available in OS X v10.2 and later.