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#import <JavaScriptCore/JSBase.h> 31 32@class DOMDocument; 33@class DOMHTMLElement; 34@class JSContext; 35@class NSURLRequest; 36@class WebArchive; 37@class WebDataSource; 38@class WebFramePrivate; 39@class WebFrameView; 40@class WebScriptObject; 41@class WebView; 42 43/*! 44 @class WebFrame 45 @discussion Every web page is represented by at least one WebFrame. A WebFrame 46 has a WebFrameView and a WebDataSource. 47*/ 48@interface WebFrame : NSObject 49{ 50@private 51 WebFramePrivate *_private; 52} 53 54/*! 55 @method initWithName:webFrameView:webView: 56 @abstract The designated initializer of WebFrame. 57 @discussion WebFrames are normally created for you by the WebView. You should 58 not need to invoke this method directly. 59 @param name The name of the frame. 60 @param view The WebFrameView for the frame. 61 @param webView The WebView that manages the frame. 62 @result Returns an initialized WebFrame. 63*/ 64- (instancetype)initWithName:(NSString *)name webFrameView:(WebFrameView *)view webView:(WebView *)webView; 65 66/*! 67 @property name 68 @abstract The frame name. 69*/ 70@property (nonatomic, readonly, copy) NSString *name; 71 72/*! 73 @property webView 74 @abstract The WebView for the document that includes this frame. 75*/ 76@property (nonatomic, readonly, strong) WebView *webView; 77 78/*! 79 @property frameView 80 @abstract The WebFrameView for this frame. 81*/ 82@property (nonatomic, readonly, strong) WebFrameView *frameView; 83 84/*! 85 @property DOMDocument 86 @abstract The DOM document of the frame. 87 @description Returns nil if the frame does not contain a DOM document such as a standalone image. 88*/ 89@property (nonatomic, readonly, strong) DOMDocument *DOMDocument; 90 91/*! 92 @property frameElement 93 @abstract The frame element of the frame. 94 @description The class of the result is either DOMHTMLFrameElement, DOMHTMLIFrameElement or DOMHTMLObjectElement. 95 Returns nil if the frame is the main frame since there is no frame element for the frame in this case. 96*/ 97@property (nonatomic, readonly, strong) DOMHTMLElement *frameElement; 98 99/*! 100 @method loadRequest: 101 @param request The web request to load. 102*/ 103- (void)loadRequest:(NSURLRequest *)request; 104 105/*! 106 @method loadData:MIMEType:textEncodingName:baseURL: 107 @param data The data to use for the main page of the document. 108 @param MIMEType The MIME type of the data. 109 @param encodingName The encoding of the data. 110 @param URL The base URL to apply to relative URLs within the document. 111*/ 112- (void)loadData:(NSData *)data MIMEType:(NSString *)MIMEType textEncodingName:(NSString *)encodingName baseURL:(NSURL *)URL; 113 114/*! 115 @method loadHTMLString:baseURL: 116 @param string The string to use for the main page of the document. 117 @param URL The base URL to apply to relative URLs within the document. 118*/ 119- (void)loadHTMLString:(NSString *)string baseURL:(NSURL *)URL; 120 121/*! 122 @method loadAlternateHTMLString:baseURL:forUnreachableURL: 123 @abstract Loads a page to display as a substitute for a URL that could not be reached. 124 @discussion This allows clients to display page-loading errors in the webview itself. 125 This is typically called while processing the WebFrameLoadDelegate method 126 -webView:didFailProvisionalLoadWithError:forFrame: or one of the the WebPolicyDelegate methods 127 -webView:decidePolicyForMIMEType:request:frame:decisionListener: or 128 -webView:unableToImplementPolicyWithError:frame:. If it is called from within one of those 129 three delegate methods then the back/forward list will be maintained appropriately. 130 @param string The string to use for the main page of the document. 131 @param baseURL The baseURL to apply to relative URLs within the document. 132 @param unreachableURL The URL for which this page will serve as alternate content. 133*/ 134- (void)loadAlternateHTMLString:(NSString *)string baseURL:(NSURL *)baseURL forUnreachableURL:(NSURL *)unreachableURL; 135 136/*! 137 @method loadArchive: 138 @abstract Causes WebFrame to load a WebArchive. 139 @param archive The archive to be loaded. 140*/ 141- (void)loadArchive:(WebArchive *)archive; 142 143/*! 144 @property dataSource 145 @abstract The datasource for this frame. 146 @discussion Returns the committed data source. Will return nil if the 147 provisional data source hasn't yet been loaded. 148*/ 149@property (nonatomic, readonly, strong) WebDataSource *dataSource; 150 151/*! 152 @property provisionalDataSource 153 @abstract The provisional datasource of this frame. 154 @discussion Will return the provisional data source. The provisional data source will 155 be nil if no data source has been set on the frame, or the data source 156 has successfully transitioned to the committed data source. 157*/ 158@property (nonatomic, readonly, strong) WebDataSource *provisionalDataSource; 159 160/*! 161 @method stopLoading 162 @discussion Stop any pending loads on the frame's data source, 163 and its children. 164*/ 165- (void)stopLoading; 166 167/*! 168 @method reload 169 @discussion Performs HTTP/1.1 end-to-end revalidation using cache-validating conditionals if possible. 170*/ 171- (void)reload; 172 173/*! 174 @method reloadFromOrigin 175 @discussion Performs HTTP/1.1 end-to-end reload. 176*/ 177- (void)reloadFromOrigin; 178 179/*! 180 @method findFrameNamed: 181 @discussion This method returns a frame with the given name. findFrameNamed returns self 182 for _self and _current, the parent frame for _parent and the main frame for _top. 183 findFrameNamed returns self for _parent and _top if the receiver is the mainFrame. 184 findFrameNamed first searches from the current frame to all descending frames then the 185 rest of the frames in the WebView. If still not found, findFrameNamed searches the 186 frames of the other WebViews. 187 @param name The name of the frame to find. 188 @result The frame matching the provided name. nil if the frame is not found. 189*/ 190- (WebFrame *)findFrameNamed:(NSString *)name; 191 192/*! 193 @property parentFrame 194 @abstract The frame containing this frame, or nil if this is a top level frame. 195*/ 196@property (nonatomic, readonly, strong) WebFrame *parentFrame; 197 198/*! 199 @property childFrames 200 @abstract An array of WebFrame. 201 @discussion The frames in the array are associated with a frame set or iframe. 202*/ 203@property (nonatomic, readonly, copy) NSArray *childFrames; 204 205/*! 206 @property windowObject 207 @abstract The WebScriptObject representing the frame's JavaScript window object. 208*/ 209@property (nonatomic, readonly, strong) WebScriptObject *windowObject; 210 211/*! 212 @property globalContext 213 @abstract The frame's global JavaScript execution context. 214 @discussion Use this method to bridge between the WebKit and JavaScriptCore APIs. 215*/ 216@property (nonatomic, readonly) JSGlobalContextRef globalContext; 217 218#if JSC_OBJC_API_ENABLED 219/*! 220 @property javaScriptContext 221 @abstract The frame's global JavaScript execution context. 222 @discussion Use this method to bridge between the WebKit and Objective-C JavaScriptCore API. 223*/ 224@property (nonatomic, readonly, strong) JSContext *javaScriptContext; 225#endif // JSC_OBJC_API_ENABLED 226 227@end 228