Home | History | Annotate | Download | only in Interfaces 
      1 /*
      2  * Copyright (C) 2006, 2007, 2008 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  * 1. Redistributions of source code must retain the above copyright
      8  *    notice, this list of conditions and the following disclaimer.
      9  * 2. Redistributions in binary form must reproduce the above copyright
     10  *    notice, this list of conditions and the following disclaimer in the
     11  *    documentation and/or other materials provided with the distribution.
     12  *
     13  * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY
     14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
     15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
     16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE COMPUTER, INC. OR
     17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
     18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
     20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
     21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
     22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     24  */
     25 
     26 #ifndef DO_NO_IMPORTS
     27 import "oaidl.idl";
     28 import "ocidl.idl";
     29 import "DOMHTML.idl";
     30 import "IWebArchive.idl";
     31 import "IWebFrameView.idl";
     32 import "IWebView.idl";
     33 import "IWebURLRequest.idl";
     34 import "DOMCore.idl";
     35 #endif
     36 
     37 cpp_quote("// this is done to get midl to treat the JavaScriptCore API types as pointer types")
     38 cpp_quote("#if 0")
     39 typedef void* JSGlobalContextRef;
     40 cpp_quote("#else")
     41 cpp_quote("typedef struct OpaqueJSContext* JSGlobalContextRef;")
     42 cpp_quote("#endif")
     43 
     44 interface IDOMDocument;
     45 interface IDOMElement;
     46 interface IDOMHTMLElement;
     47 interface IWebURLRequest;
     48 interface IWebArchive;
     49 interface IWebDataSource;
     50 interface IWebFramePrivate;
     51 interface IWebFrameView;
     52 interface IWebView;
     53 
     54 /*!
     55     @class WebFrame
     56     @discussion Every web page is represented by at least one WebFrame.  A WebFrame
     57     has a WebFrameView and a WebDataSource.
     58     @interface WebFrame : NSObject
     59 */
     60 [
     61     object,
     62     oleautomation,
     63     uuid(B4B22EF7-DD43-4d01-A992-99C4A8B1F845),
     64     pointer_default(unique)
     65 ]
     66 interface IWebFrame : IUnknown
     67 {
     68     /*!
     69         @method name
     70         @result The frame name.
     71         - (NSString *)name;
     72     */
     73     HRESULT name([out, retval] BSTR* frameName);
     74 
     75     /*!
     76         @method webView
     77         @result Returns the WebView for the document that includes this frame.
     78         - (WebView *)webView;
     79     */
     80     HRESULT webView([out, retval] IWebView** view);
     81 
     82     /*!
     83         @method frameView
     84         @result The WebFrameView for this frame.
     85         - (WebFrameView *)frameView;
     86     */
     87     HRESULT frameView([out, retval] IWebFrameView** view);
     88 
     89     /*!
     90         @method DOMDocument
     91         @abstract Returns the DOM document of the frame.
     92         @description Returns nil if the frame does not contain a DOM document such as a standalone image.
     93         - (DOMDocument *)DOMDocument;
     94     */
     95     HRESULT DOMDocument([out, retval] IDOMDocument** document);
     96 
     97     /*!
     98         @method frameElement
     99         @abstract Returns the frame element of the frame.
    100         @description The class of the result is either DOMHTMLFrameElement, DOMHTMLIFrameElement or DOMHTMLObjectElement.
    101         Returns nil if the frame is the main frame since there is no frame element for the frame in this case.
    102         - (DOMHTMLElement *)frameElement;
    103     */
    104     HRESULT frameElement([out, retval] IDOMHTMLElement** frameElement);
    105 
    106     /*!
    107         @method loadRequest:
    108         @param request The web request to load.
    109         - (void)loadRequest:(NSURLRequest *)request;
    110     */
    111     HRESULT loadRequest([in] IWebURLRequest* request);
    112 
    113     /*!
    114         @method loadData:MIMEType:textEncodingName:baseURL:
    115         @param data The data to use for the main page of the document.
    116         @param MIMEType The MIME type of the data.
    117         @param encodingName The encoding of the data.
    118         @param URL The base URL to apply to relative URLs within the document.
    119         - (void)loadData:(NSData *)data MIMEType:(NSString *)MIMEType textEncodingName:(NSString *)encodingName baseURL:(NSURL *)URL;
    120     */
    121     HRESULT loadData([in] IStream* data, [in] BSTR mimeType, [in] BSTR textEncodingName, [in] BSTR url);
    122 
    123     /*!
    124         @method loadHTMLString:baseURL:
    125         @param string The string to use for the main page of the document.
    126         @param URL The base URL to apply to relative URLs within the document.
    127         - (void)loadHTMLString:(NSString *)string baseURL:(NSURL *)URL;
    128     */
    129     HRESULT loadHTMLString([in] BSTR string, [in] BSTR baseURL);
    130 
    131     /*!
    132         @method loadAlternateHTMLString:baseURL:forUnreachableURL:
    133         @abstract Loads a page to display as a substitute for a URL that could not be reached.
    134         @discussion This allows clients to display page-loading errors in the webview itself.
    135         This is typically called while processing the WebFrameLoadDelegate method
    136         -webView:didFailProvisionalLoadWithError:forFrame: or one of the the WebPolicyDelegate methods
    137         -webView:decidePolicyForMIMEType:request:frame:decisionListener: or
    138         -webView:unableToImplementPolicyWithError:frame:. If it is called from within one of those
    139         three delegate methods then the back/forward list will be maintained appropriately.
    140         @param string The string to use for the main page of the document.
    141         @param baseURL The baseURL to apply to relative URLs within the document.
    142         @param unreachableURL The URL for which this page will serve as alternate content.
    143         - (void)loadAlternateHTMLString:(NSString *)string baseURL:(NSURL *)baseURL forUnreachableURL:(NSURL *)unreachableURL;
    144     */
    145     HRESULT loadAlternateHTMLString([in] BSTR str, [in] BSTR baseURL, [in] BSTR unreachableURL);
    146 
    147     /*!
    148         @method loadArchive:
    149         @abstract Causes WebFrame to load a WebArchive.
    150         @param archive The archive to be loaded.
    151         - (void)loadArchive:(WebArchive *)archive;
    152     */
    153     HRESULT loadArchive([in] IWebArchive* archive);
    154 
    155     /*!
    156         @method dataSource
    157         @discussion Returns the committed data source.  Will return nil if the
    158         provisional data source hasn't yet been loaded.
    159         @result The datasource for this frame.
    160         - (WebDataSource *)dataSource;
    161     */
    162     HRESULT dataSource([out, retval] IWebDataSource** source);
    163 
    164     /*!
    165         @method provisionalDataSource
    166         @discussion Will return the provisional data source.  The provisional data source will
    167         be nil if no data source has been set on the frame, or the data source
    168         has successfully transitioned to the committed data source.
    169         @result The provisional datasource of this frame.
    170         - (WebDataSource *)provisionalDataSource;
    171     */
    172     HRESULT provisionalDataSource([out, retval] IWebDataSource** source);
    173 
    174     /*!
    175         @method stopLoading
    176         @discussion Stop any pending loads on the frame's data source,
    177         and its children.
    178         - (void)stopLoading;
    179     */
    180     HRESULT stopLoading();
    181 
    182     /*!
    183         @method reload
    184         - (void)reload;
    185     */
    186     HRESULT reload();
    187 
    188     /*!
    189         @method findFrameNamed:
    190         @discussion This method returns a frame with the given name. findFrameNamed returns self
    191         for _self and _current, the parent frame for _parent and the main frame for _top.
    192         findFrameNamed returns self for _parent and _top if the receiver is the mainFrame.
    193         findFrameNamed first searches from the current frame to all descending frames then the
    194         rest of the frames in the WebView. If still not found, findFrameNamed searches the
    195         frames of the other WebViews.
    196         @param name The name of the frame to find.
    197         @result The frame matching the provided name. nil if the frame is not found.
    198         - (WebFrame *)findFrameNamed:(NSString *)name;
    199     */
    200     HRESULT findFrameNamed([in] BSTR name, [out, retval] IWebFrame** frame);
    201 
    202     /*!
    203         @method parentFrame
    204         @result The frame containing this frame, or nil if this is a top level frame.
    205         - (WebFrame *)parentFrame;
    206     */
    207     HRESULT parentFrame([out, retval] IWebFrame** frame);
    208 
    209     /*!
    210         @method childFrames
    211         @discussion The frames in the array are associated with a frame set or iframe.
    212         @result Returns an array of WebFrame.
    213         - (NSArray *)childFrames;
    214     */
    215     HRESULT childFrames([out, retval] IEnumVARIANT** enumFrames);
    216 
    217 
    218   /* This is a DOMElement on mac, but maybe should be a DOMHTMLFrameElement? */
    219     HRESULT currentForm([out, retval] IDOMElement** frameElement);
    220 
    221     /*!
    222         @method setAllowsScrolling:
    223         @abstract Sets whether the WebFrameView allows its document to be scrolled
    224         @param flag YES to allow the document to be scrolled, NO to disallow scrolling
    225         - (void)setAllowsScrolling:(BOOL)flag;
    226     */
    227    HRESULT setAllowsScrolling([in] BOOL flag);
    228 
    229     /*!
    230         @method allowsScrolling
    231         @abstract Returns whether the WebFrameView allows its document to be scrolled
    232         @result YES if the document is allowed to scroll, otherwise NO
    233         - (BOOL)allowsScrolling;
    234     */
    235    HRESULT allowsScrolling([out, retval] BOOL* flag);
    236 
    237     /*!
    238         @method globalContext
    239         @result The frame's global JavaScript execution context.  Use this method to
    240         bridge between the WebKit and JavaScriptCore APIs.
    241     */
    242    [local] JSGlobalContextRef globalContext();
    243 
    244    /*!
    245         @method setIsDisconnected
    246         @abstract Set whether a frame is disconnected
    247         @param flag YES to mark the frame as disconnected, NO keeps it a regular frame
    248    */
    249    HRESULT setIsDisconnected([in] BOOL flag);
    250 
    251       /*!
    252         @method setExcludeFromTextSearch
    253         @abstract Set whether a frame should be excluded from text search
    254         @param flag YES to mark the frame as not searchable
    255    */
    256    HRESULT setExcludeFromTextSearch([in] BOOL flag);
    257 
    258    /*!
    259        @method reloadFromOrigin
    260        @discussion Performs HTTP/1.1 end-to-end reload.
    261    */
    262    HRESULT reloadFromOrigin();
    263 }
    264