1/* This file is part of the KDE project
2 *
3 * Copyright (C) 2002 David Faure <faure@kde.org>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License version 2, as published by the Free Software Foundation.
7 *
8 * This library is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 * Library General Public License for more details.
12 *
13 * You should have received a copy of the GNU Library General Public License
14 * along with this library; see the file COPYING.LIB. If not, write to
15 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 * Boston, MA 02110-1301, USA.
17 */
18
19#ifndef kparts_browserrun_h
20#define kparts_browserrun_h
21
22#include <krun.h>
23#include <kservice.h>
24#include <kparts/browserextension.h>
25
26namespace KParts {
27
28 /**
29 * This class extends KRun to provide additional functionality for browsers:
30 * - "save or open" dialog boxes
31 * - "save" functionality
32 * - support for HTTP POST (including saving the result to a temp file if
33 * opening a separate application)
34 * - warning before launching executables off the web
35 * - custom error handling (i.e. treating errors as HTML pages)
36 * - generation of SSL metadata depending on the previous URL shown by the part
37 * @author David Faure <faure@kde.org>
38 */
39 class KPARTS_EXPORT BrowserRun : public KRun
40 {
41 Q_OBJECT
42 public:
43 /**
44 * @param url the URL we're probing
45 * @param args URL args - includes reload, metaData, etc.
46 * @param browserArgs browser-related args - includes data for a HTTP POST, etc.
47 * @param part the part going to open this URL - can be 0 if not created yet
48 * @param window the mainwindow - passed to KIO::Job::setWindow()
49 * @param removeReferrer if true, the "referrer" metadata from @p args isn't passed on
50 * @param trustedSource if false, a warning will be shown before launching an executable.
51 Always pass false for @p trustedSource, except for local directory views.
52 * @param hideErrorDialog if true, no dialog will be shown in case of errors.
53 */
54 BrowserRun( const KUrl& url,
55 const KParts::OpenUrlArguments& args,
56 const KParts::BrowserArguments& browserArgs,
57 KParts::ReadOnlyPart *part,
58 QWidget *window,
59 bool removeReferrer, bool trustedSource, bool hideErrorDialog = false );
60
61 virtual ~BrowserRun();
62
63 KParts::OpenUrlArguments& arguments();
64 KParts::BrowserArguments& browserArguments();
65 KParts::ReadOnlyPart* part() const;
66 KUrl url() const;
67
68 bool hideErrorDialog() const;
69
70 /**
71 * @return Suggested disposition by the server (e.g. HTTP content-disposition)
72 */
73 QString contentDisposition() const;
74
75 /**
76 * @return Wheter the returned disposition suggests saving or opening inline
77 */
78 bool serverSuggestsSave() const;
79
80 enum AskSaveResult { Save, Open, Cancel };
81 /**
82 * Ask the user whether to save or open a url in another application.
83 * @param url the URL in question
84 * @param offer the application that will be used to open the URL
85 * @param mimeType the mimetype of the URL
86 * @param suggestedFileName optional file name suggested by the server
87 * @return Save, Open or Cancel.
88 * @deprecated use BrowserOpenOrSaveQuestion
89 * @code
90 * BrowserOpenOrSaveQuestion dlg(parent, url, mimeType, suggestedFileName);
91 * const BrowserOpenOrSaveQuestion::Result res = dlg.askOpenOrSave();
92 * @endcode
93 */
94#ifndef KDE_NO_DEPRECATED
95 static KDE_DEPRECATED AskSaveResult askSave( const KUrl & url, KService::Ptr offer, const QString& mimeType, const QString & suggestedFileName = QString() );
96#endif
97
98 enum AskEmbedOrSaveFlags { InlineDisposition = 0, AttachmentDisposition = 1 };
99 /**
100 * Similar to askSave but for the case where the current application is
101 * able to embed the url itself (instead of passing it to another app).
102 * @param url the URL in question
103 * @param mimeType the mimetype of the URL
104 * @param suggestedFileName optional filename suggested by the server
105 * @param flags set to AttachmentDisposition if suggested by the server
106 * @return Save, Open or Cancel.
107 * @deprecated use BrowserOpenOrSaveQuestion
108 * @code
109 * BrowserOpenOrSaveQuestion dlg(parent, url, mimeType, suggestedFileName);
110 * const BrowserOpenOrSaveQuestion::Result res = dlg.askEmbedOrSave(flags);
111 * // Important: returns Embed now, not Open!
112 * @endcode
113 */
114#ifndef KDE_NO_DEPRECATED
115 static KDE_DEPRECATED AskSaveResult askEmbedOrSave( const KUrl & url, const QString& mimeType, const QString & suggestedFileName = QString(), int flags = 0 );
116#endif
117
118 // virtual so that KHTML can implement differently (HTML cache)
119 virtual void save( const KUrl & url, const QString & suggestedFileName );
120
121 // static so that it can be called from other classes
122 static void simpleSave( const KUrl & url, const QString & suggestedFileName,
123 QWidget* window =0 ); // KDE5: remove
124 /**
125 * If kget integration is enabled, passes the url to kget.
126 * Otherwise, asks the user for a destination url, and calls saveUrlUsingKIO.
127 * @since 4.4
128 */
129 static void saveUrl(const KUrl & url, const QString & suggestedFileName,
130 QWidget* window, const KParts::OpenUrlArguments& args);
131
132 /**
133 * Starts the KIO file copy job to download @p srcUrl into @p destUrl.
134 * @since 4.4
135 */
136 static void saveUrlUsingKIO(const KUrl & srcUrl, const KUrl& destUrl,
137 QWidget* window, const QMap<QString, QString> &metaData);
138
139 static bool allowExecution( const QString &mimeType, const KUrl &url );
140
141 static bool isTextExecutable( const QString &mimeType );
142
143 /**
144 * KDE webbrowsing kparts support error urls to display errors in-line in the browser component.
145 * This helper method creates the error URL from its parameters.
146 * @param error the KIO error code (or KIO::ERR_SLAVE_DEFINED if not from KIO)
147 * @param errorText the text of the error message
148 * @param initialUrl the URL that we were trying to open (as a string, so that this can
149 * support invalid URLs as well)
150 * @since 4.6
151 */
152 static KUrl makeErrorUrl(int error, const QString& errorText, const QString& initialUrl);
153
154 protected:
155 /**
156 * Reimplemented from KRun
157 */
158 virtual void scanFile();
159 /**
160 * Reimplemented from KRun
161 */
162 virtual void init();
163 /**
164 * Called when an error happens.
165 * NOTE: @p job could be 0L, if you passed hideErrorDialog=true.
166 * The default implementation shows a message box, but only when job != 0 ....
167 * It is strongly recommended to reimplement this method if
168 * you passed hideErrorDialog=true.
169 */
170 virtual void handleError( KJob * job );
171
172 /**
173 * NotHandled means that foundMimeType should call KRun::foundMimeType,
174 * i.e. launch an external app.
175 */
176 enum NonEmbeddableResult { Handled, NotHandled, Delayed };
177
178 /**
179 * Helper for foundMimeType: call this if the mimetype couldn't be embedded
180 */
181 NonEmbeddableResult handleNonEmbeddable( const QString& mimeType ); // TODO KDE5: remove, and add =0 to the other overload
182
183 /**
184 * Helper for foundMimeType: call this if the mimetype couldn't be embedded
185 * @param mimeType the mimetype found for the URL
186 * @param pSelectedService Output variable: pointer to a KService::Ptr, which will be set
187 * to the service selected in the BrowserOpenOrSaveQuestion dialog, if any.
188 *
189 * How to handle this properly: if pSelectedService is non-zero, then the dialog will show
190 * additional "open with" buttons. In your code, you should write:
191 * @code
192 if (selectedService) {
193 KRun::setPreferredService(selectedService->desktopEntryName()); // not necessary since 4.9.3
194 KRun::foundMimeType(mimeType);
195 } else { // the user requested an open-with dialog
196 KRun::displayOpenWithDialog(url(), m_window, false, suggestedFileName());
197 setFinished(true);
198 }
199 * @endcode
200 *
201 * @since 4.5
202 */
203 NonEmbeddableResult handleNonEmbeddable(const QString& mimeType, KService::Ptr* pSelectedService);
204
205 protected Q_SLOTS:
206 void slotBrowserScanFinished(KJob *job);
207 void slotBrowserMimetype(KIO::Job *job, const QString &type);
208 void slotCopyToTempFileResult(KJob *job);
209 virtual void slotStatResult( KJob *job );
210
211 private:
212 void redirectToError( int error, const QString& errorText );
213 class BrowserRunPrivate;
214 BrowserRunPrivate* const d;
215
216 };
217}
218#endif
219