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
27import "oaidl.idl";
28import "ocidl.idl";
29import "IWebMutableURLRequest.idl";
30import "IWebURLResponse.idl";
31import "IWebResource.idl";
32import "IWebArchive.idl";
33import "IWebDocument.idl";
34import "IWebFrame.idl";
35#endif
36
37interface IWebMutableURLRequest;
38interface IWebURLConnection;
39interface IWebURLRequest;
40interface IWebURLResponse;
41interface IWebArchive;
42interface IWebDataSourcePrivate;
43interface IWebError;
44interface IWebFrame;
45interface IWebResource;
46
47interface IWebDocumentRepresentation;
48
49/*!
50    @class WebDataSource
51    @discussion A WebDataSource represents the data associated with a web page.
52    A datasource has a WebDocumentRepresentation which holds an appropriate
53    representation of the data.  WebDataSources manage a hierarchy of WebFrames.
54    WebDataSources are typically related to a view by their containing WebFrame.
55*/
56[
57    object,
58    oleautomation,
59    uuid(5221A975-AE09-4a7b-A4DF-E3B1B5F38A21),
60    pointer_default(unique)
61]
62interface IWebDataSource : IUnknown
63{
64    /*!
65        @method initWithRequest:
66        @abstract The designated initializer for WebDataSource.
67        @param request The request to use in creating a datasource.
68        @result Returns an initialized WebDataSource.
69        - (id)initWithRequest:(NSURLRequest *)request;
70    */
71    HRESULT initWithRequest([in] IWebURLRequest* request);
72
73    /*!
74        @method data
75        @discussion The data will be incomplete until the datasource has completely loaded.
76        @result Returns the raw data associated with the datasource.  Returns nil
77        if the datasource hasn't loaded any data.
78        - (NSData *)data;
79    */
80    HRESULT data([out, retval] IStream** stream);
81
82    /*!
83        @method representation
84        @discussion A representation holds a type specific representation
85        of the datasource's data.  The representation class is determined by mapping
86        a MIME type to a class.  The representation is created once the MIME type
87        of the datasource content has been determined.
88        @result Returns the representation associated with this datasource.
89        Returns nil if the datasource hasn't created it's representation.
90        - (id <WebDocumentRepresentation>)representation;
91    */
92    HRESULT representation([out, retval] IWebDocumentRepresentation** rep);
93
94    /*!
95        @method webFrame
96        @result Return the frame that represents this data source.
97        - (WebFrame *)webFrame;
98    */
99    HRESULT webFrame([out, retval] IWebFrame** frame);
100
101    /*!
102        @method initialRequest
103        @result Returns a reference to the original request that created the
104        datasource.  This request will be unmodified by WebKit.
105        - (NSURLRequest *)initialRequest;
106    */
107    HRESULT initialRequest([out, retval] IWebURLRequest** request);
108
109    /*!
110        @method request
111        @result Returns the request that was used to create this datasource.
112        - (NSMutableURLRequest *)request;
113    */
114    HRESULT request([out, retval] IWebMutableURLRequest** request);
115
116    /*!
117        @method response
118        @result returns the WebResourceResponse for the data source.
119        - (NSURLResponse *)response;
120    */
121    HRESULT response([out, retval] IWebURLResponse** response);
122
123    /*!
124        @method textEncodingName
125        @result Returns either the override encoding, as set on the WebView for this
126        dataSource or the encoding from the response.
127        - (NSString *)textEncodingName;
128    */
129    HRESULT textEncodingName([out, retval] BSTR* name);
130
131    /*!
132        @method isLoading
133        @discussion Returns YES if there are any pending loads.
134        - (BOOL)isLoading;
135    */
136    HRESULT isLoading([out, retval] BOOL* loading);
137
138    /*!
139        @method pageTitle
140        @result Returns nil or the page title.
141        - (NSString *)pageTitle;
142    */
143    HRESULT pageTitle([out, retval] BSTR* title);
144
145    /*!
146        @method unreachableURL
147        @discussion This will be non-nil only for dataSources created by calls to the
148        WebFrame method loadAlternateHTMLString:baseURL:forUnreachableURL:.
149        @result returns the unreachableURL for which this dataSource is showing alternate content, or nil
150        - (NSURL *)unreachableURL;
151    */
152    HRESULT unreachableURL([out, retval] BSTR* url);
153
154    /*!
155        @method webArchive
156        @result A WebArchive representing the data source, its subresources and child frames.
157        @description This method constructs a WebArchive using the original downloaded data.
158        In the case of HTML, if the current state of the document is preferred, webArchive should be
159        called on the DOM document instead.
160        - (WebArchive *)webArchive;
161    */
162    HRESULT webArchive([out, retval] IWebArchive** archive);
163
164    /*!
165        @method mainResource
166        @result A WebResource representing the data source.
167        @description This method constructs a WebResource using the original downloaded data.
168        This method can be used to construct a WebArchive in case the archive returned by
169        WebDataSource's webArchive isn't sufficient.
170        - (WebResource *)mainResource;
171    */
172    HRESULT mainResource([out, retval] IWebResource** resource);
173
174    /*!
175        @method subresources
176        @abstract Returns all the subresources associated with the data source.
177        @description The returned array only contains subresources that have fully downloaded.
178        - (NSArray *)subresources;
179    */
180    HRESULT subresources([out, retval] IEnumVARIANT** enumResources);
181
182    /*!
183        method subresourceForURL:
184        @abstract Returns a subresource for a given URL.
185        @param URL The URL of the subresource.
186        @description Returns non-nil if the data source has fully downloaded a subresource with the given URL.
187        - (WebResource *)subresourceForURL:(NSURL *)URL;
188    */
189    HRESULT subresourceForURL([in] BSTR url, [out, retval] IWebResource** resource);
190
191    /*!
192        @method addSubresource:
193        @abstract Adds a subresource to the data source.
194        @param subresource The subresource to be added.
195        @description addSubresource: adds a subresource to the data source's list of subresources.
196        Later, if something causes the data source to load the URL of the subresource, the data source
197        will load the data from the subresource instead of from the network. For example, if one wants to add
198        an image that is already downloaded to a web page, addSubresource: can be called so that the data source
199        uses the downloaded image rather than accessing the network. NOTE: If the data source already has a
200        subresource with the same URL, addSubresource: will replace it.
201        - (void)addSubresource:(WebResource *)subresource;
202    */
203    HRESULT addSubresource([in] IWebResource* subresource);
204}
205
206[
207    object,
208    oleautomation,
209    uuid(4B80B7D4-98D7-4a80-AF46-2AF84B2F2E8F),
210    pointer_default(unique)
211]
212interface IWebDataSourcePrivate : IUnknown
213{
214    HRESULT overrideEncoding([out, retval] BSTR* encoding);
215    HRESULT setOverrideEncoding([in] BSTR encoding);
216    HRESULT mainDocumentError([out, retval] IWebError** error);
217    HRESULT setDeferMainResourceDataLoad([in] BOOL flag);
218}
219