1/*
2 * Copyright (C) 2003, 2004, 2005 Apple Computer, 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 Computer, 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 <Cocoa/Cocoa.h>
30
31#import <WebKit/WebDocument.h>
32
33@class NSMutableURLRequest;
34@class NSURLConnection;
35@class NSURLRequest;
36@class NSURLResponse;
37@class WebArchive;
38@class WebDataSourcePrivate;
39@class WebFrame;
40@class WebResource;
41
42/*!
43    @class WebDataSource
44    @discussion A WebDataSource represents the data associated with a web page.
45    A datasource has a WebDocumentRepresentation which holds an appropriate
46    representation of the data.  WebDataSources manage a hierarchy of WebFrames.
47    WebDataSources are typically related to a view by their containing WebFrame.
48*/
49@interface WebDataSource : NSObject
50{
51@private
52    WebDataSourcePrivate *_private;
53}
54
55/*!
56    @method initWithRequest:
57    @abstract The designated initializer for WebDataSource.
58    @param request The request to use in creating a datasource.
59    @result Returns an initialized WebDataSource.
60*/
61- (id)initWithRequest:(NSURLRequest *)request;
62
63/*!
64    @method data
65    @discussion The data will be incomplete until the datasource has completely loaded.
66    @result Returns the raw data associated with the datasource.  Returns nil
67    if the datasource hasn't loaded any data.
68*/
69- (NSData *)data;
70
71/*!
72    @method representation
73    @discussion A representation holds a type specific representation
74    of the datasource's data.  The representation class is determined by mapping
75    a MIME type to a class.  The representation is created once the MIME type
76    of the datasource content has been determined.
77    @result Returns the representation associated with this datasource.
78    Returns nil if the datasource hasn't created it's representation.
79*/
80- (id <WebDocumentRepresentation>)representation;
81
82/*!
83    @method webFrame
84    @result Return the frame that represents this data source.
85*/
86- (WebFrame *)webFrame;
87
88/*!
89    @method initialRequest
90    @result Returns a reference to the original request that created the
91    datasource.  This request will be unmodified by WebKit.
92*/
93- (NSURLRequest *)initialRequest;
94
95/*!
96    @method request
97    @result Returns the request that was used to create this datasource.
98*/
99- (NSMutableURLRequest *)request;
100
101/*!
102    @method response
103    @result returns the WebResourceResponse for the data source.
104*/
105- (NSURLResponse *)response;
106
107/*!
108    @method textEncodingName
109    @result Returns either the override encoding, as set on the WebView for this
110    dataSource or the encoding from the response.
111*/
112- (NSString *)textEncodingName;
113
114/*!
115    @method isLoading
116    @discussion Returns YES if there are any pending loads.
117*/
118- (BOOL)isLoading;
119
120/*!
121    @method pageTitle
122    @result Returns nil or the page title.
123*/
124- (NSString *)pageTitle;
125
126/*!
127    @method unreachableURL
128    @discussion This will be non-nil only for dataSources created by calls to the
129    WebFrame method loadAlternateHTMLString:baseURL:forUnreachableURL:.
130    @result returns the unreachableURL for which this dataSource is showing alternate content, or nil
131*/
132- (NSURL *)unreachableURL;
133
134/*!
135    @method webArchive
136    @result A WebArchive representing the data source, its subresources and child frames.
137    @description This method constructs a WebArchive using the original downloaded data.
138    In the case of HTML, if the current state of the document is preferred, webArchive should be
139    called on the DOM document instead.
140*/
141- (WebArchive *)webArchive;
142
143/*!
144    @method mainResource
145    @result A WebResource representing the data source.
146    @description This method constructs a WebResource using the original downloaded data.
147    This method can be used to construct a WebArchive in case the archive returned by
148    WebDataSource's webArchive isn't sufficient.
149*/
150- (WebResource *)mainResource;
151
152/*!
153    @method subresources
154    @abstract Returns all the subresources associated with the data source.
155    @description The returned array only contains subresources that have fully downloaded.
156*/
157- (NSArray *)subresources;
158
159/*!
160    method subresourceForURL:
161    @abstract Returns a subresource for a given URL.
162    @param URL The URL of the subresource.
163    @description Returns non-nil if the data source has fully downloaded a subresource with the given URL.
164*/
165- (WebResource *)subresourceForURL:(NSURL *)URL;
166
167/*!
168    @method addSubresource:
169    @abstract Adds a subresource to the data source.
170    @param subresource The subresource to be added.
171    @description addSubresource: adds a subresource to the data source's list of subresources.
172    Later, if something causes the data source to load the URL of the subresource, the data source
173    will load the data from the subresource instead of from the network. For example, if one wants to add
174    an image that is already downloaded to a web page, addSubresource: can be called so that the data source
175    uses the downloaded image rather than accessing the network. NOTE: If the data source already has a
176    subresource with the same URL, addSubresource: will replace it.
177*/
178- (void)addSubresource:(WebResource *)subresource;
179
180@end
181