1 | /* |
2 | SPDX-FileCopyrightText: 2000 David Faure <faure@kde.org> |
3 | |
4 | SPDX-License-Identifier: LGPL-2.0-or-later |
5 | */ |
6 | |
7 | #ifndef SLAVEBASE_H |
8 | #define SLAVEBASE_H |
9 | |
10 | #include "job_base.h" // for KIO::JobFlags |
11 | #include <kio/authinfo.h> |
12 | #include <kio/global.h> |
13 | #include <kio/udsentry.h> |
14 | |
15 | #include <QByteArray> |
16 | #include <QHostInfo> |
17 | #include <QSsl> |
18 | |
19 | #include <memory> |
20 | |
21 | class KConfigGroup; |
22 | class KRemoteEncoding; |
23 | class QUrl; |
24 | |
25 | namespace KIO |
26 | { |
27 | class Connection; |
28 | class SlaveBasePrivate; |
29 | |
30 | // TODO: Enable once file KIO worker is ported away and add endif, similar in the cpp file |
31 | // #if KIOCORE_ENABLE_DEPRECATED_SINCE(version where file:/ KIO worker was ported) |
32 | |
33 | /* |
34 | * @class KIO::SlaveBase slavebase.h <KIO/SlaveBase> |
35 | * |
36 | * There are two classes that specifies the protocol between application (job) |
37 | * and kioslave. SlaveInterface is the class to use on the application end, |
38 | * SlaveBase is the one to use on the slave end. |
39 | * |
40 | * Slave implementations should simply inherit SlaveBase |
41 | * |
42 | * A call to foo() results in a call to slotFoo() on the other end. |
43 | * |
44 | * Note that a kioslave doesn't have a Qt event loop. When idle, it's waiting for a command |
45 | * on the socket that connects it to the application. So don't expect a kioslave to react |
46 | * to D-Bus signals for instance. KIOSlaves are short-lived anyway, so any kind of watching |
47 | * or listening for notifications should be done elsewhere, for instance in a kded module |
48 | * (see kio_desktop's desktopnotifier.cpp for an example). |
49 | * |
50 | * If a kioslave needs a Qt event loop within the implementation of one method, e.g. to |
51 | * wait for an asynchronous operation to finish, that is possible, using QEventLoop. |
52 | * |
53 | * @deprecated Since 5.96, use WorkerBase. |
54 | */ |
55 | class SlaveBase |
56 | { |
57 | public: |
58 | KIOCORE_DEPRECATED_VERSION_BELATED(5, 101, 5, 96, "Use WorkerBase" ) |
59 | SlaveBase(const QByteArray &protocol, const QByteArray &pool_socket, const QByteArray &app_socket); |
60 | virtual ~SlaveBase(); |
61 | |
62 | /* |
63 | * \internal |
64 | * Terminate the slave by calling the destructor and then ::exit() |
65 | */ |
66 | void exit(); |
67 | |
68 | /* |
69 | * \internal |
70 | */ |
71 | void dispatchLoop(); |
72 | |
73 | /////////// |
74 | // Message Signals to send to the job |
75 | /////////// |
76 | |
77 | /* |
78 | * Sends data in the slave to the job (i.e.\ in get). |
79 | * |
80 | * To signal end of data, simply send an empty |
81 | * QByteArray(). |
82 | * |
83 | * \a data the data read by the slave |
84 | */ |
85 | void data(const QByteArray &data); |
86 | |
87 | /* |
88 | * Asks for data from the job. |
89 | * \sa readData |
90 | */ |
91 | void dataReq(); |
92 | |
93 | /* |
94 | * open succeeds |
95 | * \sa open() |
96 | */ |
97 | void opened(); |
98 | |
99 | /* |
100 | * Call to signal an error. |
101 | * This also finishes the job, so you must not call |
102 | * finished() after calling this. |
103 | * |
104 | * If the error code is KIO::ERR_SLAVE_DEFINED then the |
105 | * _text should contain the complete translated text of |
106 | * of the error message. |
107 | * |
108 | * For all other error codes, _text should match the corresponding |
109 | * error code. Usually, _text is a file or host name, or the error which |
110 | * was passed from the server.<br> |
111 | * For example, for KIO::ERR_DOES_NOT_EXIST, _text may only |
112 | * be the file or folder which does not exist, nothing else. Otherwise, |
113 | * this would break error strings generated by KIO::buildErrorString().<br> |
114 | * If you have to add more details than what the standard error codes |
115 | * provide, you'll need to use KIO::ERR_SLAVE_DEFINED. |
116 | * For a complete list of what _text should contain for each error code, |
117 | * look at the source of KIO::buildErrorString(). |
118 | * |
119 | * You can add rich text markup to the message, the places where the |
120 | * error message will be displayed are rich text aware. |
121 | * |
122 | * \sa KIO::Error |
123 | * \sa KIO::buildErrorString |
124 | * \a _errid the error code from KIO::Error |
125 | * \a _text the rich text error message |
126 | */ |
127 | void error(int _errid, const QString &_text); |
128 | |
129 | /* |
130 | * Call in openConnection, if you reimplement it, when you're done. |
131 | */ |
132 | void connected(); |
133 | |
134 | /* |
135 | * Call to signal successful completion of any command |
136 | * besides openConnection and closeConnection. Do not |
137 | * call this after calling error(). |
138 | */ |
139 | void finished(); |
140 | |
141 | /* |
142 | * Used to report the status of the slave. |
143 | * \a host the slave is currently connected to. (Should be |
144 | * empty if not connected) |
145 | * \a connected Whether an actual network connection exists. |
146 | **/ |
147 | void slaveStatus(const QString &host, bool connected); |
148 | |
149 | /* |
150 | * Call this from stat() to express details about an object, the |
151 | * UDSEntry customarily contains the atoms describing file name, size, |
152 | * MIME type, etc. |
153 | * \a _entry The UDSEntry containing all of the object attributes. |
154 | */ |
155 | void statEntry(const UDSEntry &_entry); |
156 | |
157 | /* |
158 | * Call this in listDir, each time you have a bunch of entries |
159 | * to report. |
160 | * \a _entry The UDSEntry containing all of the object attributes. |
161 | */ |
162 | void listEntries(const UDSEntryList &_entry); |
163 | |
164 | /* |
165 | * Call this at the beginning of put(), to give the size of the existing |
166 | * partial file, if there is one. The @p offset argument notifies the |
167 | * other job (the one that gets the data) about the offset to use. |
168 | * In this case, the boolean returns whether we can indeed resume or not |
169 | * (we can't if the protocol doing the get() doesn't support setting an offset) |
170 | */ |
171 | bool canResume(KIO::filesize_t offset); |
172 | |
173 | /* |
174 | * Call this at the beginning of get(), if the "range-start" metadata was set |
175 | * and returning byte ranges is implemented by this protocol. |
176 | */ |
177 | void canResume(); |
178 | |
179 | /////////// |
180 | // Info Signals to send to the job |
181 | /////////// |
182 | |
183 | /* |
184 | * Call this in get and copy, to give the total size |
185 | * of the file. |
186 | */ |
187 | void totalSize(KIO::filesize_t _bytes); |
188 | /* |
189 | * Call this during get and copy, once in a while, |
190 | * to give some info about the current state. |
191 | * Don't emit it in listDir, listEntries speaks for itself. |
192 | */ |
193 | void processedSize(KIO::filesize_t _bytes); |
194 | |
195 | void position(KIO::filesize_t _pos); |
196 | |
197 | void written(KIO::filesize_t _bytes); |
198 | |
199 | /* |
200 | * \since 5.66 |
201 | */ |
202 | void truncated(KIO::filesize_t _length); |
203 | |
204 | /* |
205 | * Only use this if you can't know in advance the size of the |
206 | * copied data. For example, if you're doing variable bitrate |
207 | * compression of the source. |
208 | * |
209 | * STUB ! Currently unimplemented. Here now for binary compatibility. |
210 | * |
211 | * Call this during get and copy, once in a while, |
212 | * to give some info about the current state. |
213 | * Don't emit it in listDir, listEntries speaks for itself. |
214 | */ |
215 | void processedPercent(float percent); // KF6 TODO REMOVE |
216 | |
217 | /* |
218 | * Call this in get and copy, to give the current transfer |
219 | * speed, but only if it can't be calculated out of the size you |
220 | * passed to processedSize (in most cases you don't want to call it) |
221 | */ |
222 | void speed(unsigned long _bytes_per_second); |
223 | |
224 | /* |
225 | * Call this to signal a redirection. |
226 | * The job will take care of going to that url. |
227 | */ |
228 | void redirection(const QUrl &_url); |
229 | |
230 | /* |
231 | * Call this in mimetype() and in get(), when you know the MIME type. |
232 | * See mimetype() about other ways to implement it. |
233 | */ |
234 | void mimeType(const QString &_type); |
235 | |
236 | /* |
237 | * Call to signal a warning, to be displayed in a dialog box. |
238 | */ |
239 | void warning(const QString &msg); |
240 | |
241 | /* |
242 | * Call to signal a message, to be displayed if the application wants to, |
243 | * for instance in a status bar. Usual examples are "connecting to host xyz", etc. |
244 | */ |
245 | void infoMessage(const QString &msg); |
246 | |
247 | /* |
248 | * Type of message box. Should be kept in sync with KMessageBox::DialogType. |
249 | */ |
250 | enum MessageBoxType { |
251 | QuestionTwoActions = 1, ///< \since 5.100 |
252 | WarningTwoActions = 2, ///< \since 5.100 |
253 | WarningContinueCancel = 3, |
254 | WarningTwoActionsCancel = 4, ///< \since 5.100 |
255 | Information = 5, |
256 | // In KMessageBox::DialogType; <unused> = 7, Error = 8, QuestionTwoActionsCancel = 9 |
257 | WarningContinueCancelDetailed = 10, |
258 | }; |
259 | |
260 | /* |
261 | * Button codes. Should be kept in sync with KMessageBox::ButtonCode |
262 | */ |
263 | enum ButtonCode { |
264 | Ok = 1, |
265 | Cancel = 2, |
266 | PrimaryAction = 3, ///< \since 5.100 |
267 | SecondaryAction = 4, ///< \since 5.100 |
268 | Continue = 5, |
269 | }; |
270 | |
271 | /* |
272 | * Call this to show a message box from the slave |
273 | * \a type type of message box: QuestionTwoActions, WarningTwoActions, WarningContinueCancel... |
274 | * \a text Message string. May contain newlines. |
275 | * \a title Message box title. |
276 | * \a primaryActionText the text for the first button. |
277 | * Ignored for @p type Information & SSLMessageBox. |
278 | * \a secondaryActionText the text for the second button. |
279 | * Ignored for @p type WarningContinueCancel, WarningContinueCancelDetailed, |
280 | * Information & SSLMessageBox. |
281 | * Returns a button code, as defined in ButtonCode, or 0 on communication error. |
282 | */ |
283 | int messageBox(MessageBoxType type, |
284 | const QString &text, |
285 | const QString &title = QString(), |
286 | const QString &primaryActionText = QString(), |
287 | const QString &secondaryActionText = QString()); |
288 | |
289 | int sslError(const QVariantMap &sslData); |
290 | |
291 | /* |
292 | * Call this to show a message box from the slave |
293 | * \a text Message string. May contain newlines. |
294 | * \a type type of message box: QuestionTwoActions, WarningTwoActions, WarningContinueCancel... |
295 | * \a title Message box title. |
296 | * \a primaryActionText the text for the first button. |
297 | * Ignored for @p type Information & SSLMessageBox. |
298 | * \a secondaryActionText the text for the second button. |
299 | * Ignored for @p type WarningContinueCancel, WarningContinueCancelDetailed, |
300 | * Information & SSLMessageBox. |
301 | * \a dontAskAgainName the name used to store result from 'Do not ask again' checkbox. |
302 | * Returns a button code, as defined in ButtonCode, or 0 on communication error. |
303 | */ |
304 | int messageBox(const QString &text, |
305 | MessageBoxType type, |
306 | const QString &title = QString(), |
307 | const QString &primaryActionText = QString(), |
308 | const QString &secondaryActionText = QString(), |
309 | const QString &dontAskAgainName = QString()); |
310 | |
311 | /* |
312 | * Sets meta-data to be send to the application before the first |
313 | * data() or finished() signal. |
314 | */ |
315 | void setMetaData(const QString &key, const QString &value); |
316 | |
317 | /* |
318 | * Queries for the existence of a certain config/meta-data entry |
319 | * send by the application to the slave. |
320 | */ |
321 | bool hasMetaData(const QString &key) const; |
322 | |
323 | /* |
324 | * Queries for config/meta-data send by the application to the slave. |
325 | */ |
326 | QString metaData(const QString &key) const; |
327 | |
328 | /* |
329 | * \internal for ForwardingSlaveBase |
330 | * Contains all metadata (but no config) sent by the application to the slave. |
331 | */ |
332 | MetaData allMetaData() const; |
333 | |
334 | /* |
335 | * Returns a map to query config/meta-data information from. |
336 | * |
337 | * The application provides the slave with all configuration information |
338 | * relevant for the current protocol and host. |
339 | * |
340 | * Use configValue() as shortcut. |
341 | * \since 5.64 |
342 | */ |
343 | QMap<QString, QVariant> mapConfig() const; |
344 | |
345 | /* |
346 | * Returns a bool from the config/meta-data information. |
347 | * \since 5.64 |
348 | */ |
349 | bool configValue(const QString &key, bool defaultValue) const; |
350 | |
351 | /* |
352 | * Returns an int from the config/meta-data information. |
353 | * \since 5.64 |
354 | */ |
355 | int configValue(const QString &key, int defaultValue) const; |
356 | |
357 | /* |
358 | * Returns a QString from the config/meta-data information. |
359 | * \since 5.64 |
360 | */ |
361 | QString configValue(const QString &key, const QString &defaultValue = QString()) const; |
362 | |
363 | /* |
364 | * Returns a configuration object to query config/meta-data information |
365 | * from. |
366 | * |
367 | * The application provides the slave with all configuration information |
368 | * relevant for the current protocol and host. |
369 | * |
370 | * @note Since 5.64 prefer to use mapConfig() or one of the configValue(...) overloads. |
371 | * @todo Find replacements for the other current usages of this method. |
372 | */ |
373 | KConfigGroup *config(); |
374 | // KF6: perhaps rename mapConfig() to config() when removing this |
375 | |
376 | /* |
377 | * Returns an object that can translate remote filenames into proper |
378 | * Unicode forms. This encoding can be set by the user. |
379 | */ |
380 | KRemoteEncoding *remoteEncoding(); |
381 | |
382 | /////////// |
383 | // Commands sent by the job, the slave has to |
384 | // override what it wants to implement |
385 | /////////// |
386 | |
387 | /* |
388 | * Set the host |
389 | * |
390 | * Called directly by createWorker, this is why there is no equivalent in |
391 | * SlaveInterface, unlike the other methods. |
392 | * |
393 | * This method is called whenever a change in host, port or user occurs. |
394 | */ |
395 | virtual void setHost(const QString &host, quint16 port, const QString &user, const QString &pass); |
396 | |
397 | /* |
398 | * Opens the connection (forced). |
399 | * |
400 | * When this function gets called the slave is operating in |
401 | * connection-oriented mode. |
402 | * When a connection gets lost while the slave operates in |
403 | * connection oriented mode, the slave should report |
404 | * ERR_CONNECTION_BROKEN instead of reconnecting. The user is |
405 | * expected to disconnect the slave in the error handler. |
406 | */ |
407 | virtual void openConnection(); |
408 | |
409 | /* |
410 | * Closes the connection (forced). |
411 | * |
412 | * Called when the application disconnects the slave to close |
413 | * any open network connections. |
414 | * |
415 | * When the slave was operating in connection-oriented mode, |
416 | * it should reset itself to connectionless (default) mode. |
417 | */ |
418 | virtual void closeConnection(); |
419 | |
420 | /* |
421 | * get, aka read. |
422 | * \a url the full url for this request. Host, port and user of the URL |
423 | * can be assumed to be the same as in the last setHost() call. |
424 | * |
425 | * The slave should first "emit" the MIME type by calling mimeType(), |
426 | * and then "emit" the data using the data() method. |
427 | * |
428 | * The reason why we need get() to emit the MIME type is: |
429 | * when pasting a URL in krunner, or konqueror's location bar, |
430 | * we have to find out what is the MIME type of that URL. |
431 | * Rather than doing it with a call to mimetype(), then the app or part |
432 | * would have to do a second request to the same server, this is done |
433 | * like this: get() is called, and when it emits the MIME type, the job |
434 | * is put on hold and the right app or part is launched. When that app |
435 | * or part calls get(), the slave is magically reused, and the download |
436 | * can now happen. All with a single call to get() in the slave. |
437 | * This mechanism is also described in KIO::get(). |
438 | */ |
439 | virtual void get(const QUrl &url); |
440 | |
441 | /* |
442 | * open. |
443 | * \a url the full url for this request. Host, port and user of the URL |
444 | * can be assumed to be the same as in the last setHost() call. |
445 | * \a mode see \ref QIODevice::OpenMode |
446 | */ |
447 | virtual void open(const QUrl &url, QIODevice::OpenMode mode); |
448 | |
449 | /* |
450 | * read. |
451 | * \a size the requested amount of data to read |
452 | * \sa KIO::FileJob::read() |
453 | */ |
454 | virtual void read(KIO::filesize_t size); |
455 | /* |
456 | * write. |
457 | * \a data the data to write |
458 | * \sa KIO::FileJob::write() |
459 | */ |
460 | virtual void write(const QByteArray &data); |
461 | /* |
462 | * seek. |
463 | * \a offset the requested amount of data to read |
464 | * \sa KIO::FileJob::read() |
465 | */ |
466 | virtual void seek(KIO::filesize_t offset); |
467 | /* |
468 | * close. |
469 | * \sa KIO::FileJob::close() |
470 | */ |
471 | virtual void close(); |
472 | |
473 | /* |
474 | * put, i.e.\ write data into a file. |
475 | * |
476 | * \a url where to write the file |
477 | * \a permissions may be -1. In this case no special permission mode is set. |
478 | * \a flags We support Overwrite here. Hopefully, we're going to |
479 | * support Resume in the future, too. |
480 | * If the file indeed already exists, the slave should NOT apply the |
481 | * permissions change to it. |
482 | * The support for resuming using .part files is done by calling canResume(). |
483 | * |
484 | * IMPORTANT: Use the "modified" metadata in order to set the modification time of the file. |
485 | * |
486 | * \sa canResume() |
487 | */ |
488 | virtual void put(const QUrl &url, int permissions, JobFlags flags); |
489 | |
490 | /* |
491 | * Finds all details for one file or directory. |
492 | * The information returned is the same as what listDir returns, |
493 | * but only for one file or directory. |
494 | * Call statEntry() after creating the appropriate UDSEntry for this |
495 | * url. |
496 | * |
497 | * You can use the "details" metadata to optimize this method to only |
498 | * do as much work as needed by the application. |
499 | * By default details is 2 (all details wanted, including modification time, size, etc.), |
500 | * details==1 is used when deleting: we don't need all the information if it takes |
501 | * too much time, no need to follow symlinks etc. |
502 | * details==0 is used for very simple probing: we'll only get the answer |
503 | * "it's a file or a directory (or a symlink), or it doesn't exist". |
504 | */ |
505 | virtual void stat(const QUrl &url); |
506 | |
507 | /* |
508 | * Finds MIME type for one file or directory. |
509 | * |
510 | * This method should either emit 'mimeType' or it |
511 | * should send a block of data big enough to be able |
512 | * to determine the MIME type. |
513 | * |
514 | * If the slave doesn't reimplement it, a get will |
515 | * be issued, i.e. the whole file will be downloaded before |
516 | * determining the MIME type on it - this is obviously not a |
517 | * good thing in most cases. |
518 | */ |
519 | virtual void mimetype(const QUrl &url); |
520 | |
521 | /* |
522 | * Lists the contents of @p url. |
523 | * The slave should emit ERR_CANNOT_ENTER_DIRECTORY if it doesn't exist, |
524 | * if we don't have enough permissions. |
525 | * You should not list files if the path in @p url is empty, but redirect |
526 | * to a non-empty path instead. |
527 | */ |
528 | virtual void listDir(const QUrl &url); |
529 | |
530 | /* |
531 | * Create a directory |
532 | * \a url path to the directory to create |
533 | * \a permissions the permissions to set after creating the directory |
534 | * (-1 if no permissions to be set) |
535 | * The slave emits ERR_CANNOT_MKDIR if failure. |
536 | */ |
537 | virtual void mkdir(const QUrl &url, int permissions); |
538 | |
539 | /* |
540 | * Rename @p oldname into @p newname. |
541 | * If the slave returns an error ERR_UNSUPPORTED_ACTION, the job will |
542 | * ask for copy + del instead. |
543 | * |
544 | * Important: the slave must implement the logic "if the destination already |
545 | * exists, error ERR_DIR_ALREADY_EXIST or ERR_FILE_ALREADY_EXIST". |
546 | * For performance reasons no stat is done in the destination before hand, |
547 | * the slave must do it. |
548 | * |
549 | * By default, rename() is only called when renaming (moving) from |
550 | * yourproto://host/path to yourproto://host/otherpath. |
551 | * |
552 | * If you set renameFromFile=true then rename() will also be called when |
553 | * moving a file from file:///path to yourproto://host/otherpath. |
554 | * Otherwise such a move would have to be done the slow way (copy+delete). |
555 | * See KProtocolManager::canRenameFromFile() for more details. |
556 | * |
557 | * If you set renameToFile=true then rename() will also be called when |
558 | * moving a file from yourproto: to file:. |
559 | * See KProtocolManager::canRenameToFile() for more details. |
560 | * |
561 | * \a src where to move the file from |
562 | * \a dest where to move the file to |
563 | * \a flags We support Overwrite here |
564 | */ |
565 | virtual void rename(const QUrl &src, const QUrl &dest, JobFlags flags); |
566 | |
567 | /* |
568 | * Creates a symbolic link named @p dest, pointing to @p target, which |
569 | * may be a relative or an absolute path. |
570 | * \a target The string that will become the "target" of the link (can be relative) |
571 | * \a dest The symlink to create. |
572 | * \a flags We support Overwrite here |
573 | */ |
574 | virtual void symlink(const QString &target, const QUrl &dest, JobFlags flags); |
575 | |
576 | /* |
577 | * Change permissions on @p url. |
578 | * |
579 | * The slave emits ERR_DOES_NOT_EXIST or ERR_CANNOT_CHMOD |
580 | */ |
581 | virtual void chmod(const QUrl &url, int permissions); |
582 | |
583 | /* |
584 | * Change ownership of @p url. |
585 | * |
586 | * The slave emits ERR_DOES_NOT_EXIST or ERR_CANNOT_CHOWN |
587 | */ |
588 | virtual void chown(const QUrl &url, const QString &owner, const QString &group); |
589 | |
590 | /* |
591 | * Sets the modification time for @p url. |
592 | * |
593 | * For instance this is what CopyJob uses to set mtime on dirs at the end of a copy. |
594 | * It could also be used to set the mtime on any file, in theory. |
595 | * The usual implementation on unix is to call utime(path, &myutimbuf). |
596 | * The slave emits ERR_DOES_NOT_EXIST or ERR_CANNOT_SETTIME |
597 | */ |
598 | virtual void setModificationTime(const QUrl &url, const QDateTime &mtime); |
599 | |
600 | /* |
601 | * Copy @p src into @p dest. |
602 | * |
603 | * By default, copy() is only called when copying a file from |
604 | * yourproto://host/path to yourproto://host/otherpath. |
605 | * |
606 | * If you set copyFromFile=true then copy() will also be called when |
607 | * moving a file from file:///path to yourproto://host/otherpath. |
608 | * Otherwise such a copy would have to be done the slow way (get+put). |
609 | * See also KProtocolManager::canCopyFromFile(). |
610 | * |
611 | * If you set copyToFile=true then copy() will also be called when |
612 | * moving a file from yourproto: to file:. |
613 | * See also KProtocolManager::canCopyToFile(). |
614 | * |
615 | * If the slave returns an error ERR_UNSUPPORTED_ACTION, the job will |
616 | * ask for get + put instead. |
617 | * |
618 | * If the slave returns an error ERR_FILE_ALREADY_EXIST, the job will |
619 | * ask for a different destination filename. |
620 | * |
621 | * \a src where to copy the file from (decoded) |
622 | * \a dest where to copy the file to (decoded) |
623 | * \a permissions may be -1. In this case no special permission mode is set, |
624 | * and the owner and group permissions are not preserved. |
625 | * \a flags We support Overwrite here |
626 | * |
627 | * Don't forget to set the modification time of @p dest to be the modification time of @p src. |
628 | */ |
629 | virtual void copy(const QUrl &src, const QUrl &dest, int permissions, JobFlags flags); |
630 | |
631 | /* |
632 | * Delete a file or directory. |
633 | * \a url file/directory to delete |
634 | * \a isfile if true, a file should be deleted. |
635 | * if false, a directory should be deleted. |
636 | * |
637 | * By default, del() on a directory should FAIL if the directory is not empty. |
638 | * However, if metadata("recurse") == "true", then the slave can do a recursive deletion. |
639 | * This behavior is only invoked if the slave specifies deleteRecursive=true in its protocol file. |
640 | */ |
641 | virtual void del(const QUrl &url, bool isfile); |
642 | |
643 | /* |
644 | * Change the destination of a symlink |
645 | * \a url the url of the symlink to modify |
646 | * \a target the new destination (target) of the symlink |
647 | */ |
648 | virtual void setLinkDest(const QUrl &url, const QString &target); |
649 | |
650 | /* |
651 | * Used for any command that is specific to this slave (protocol). |
652 | * |
653 | * Examples are : HTTP POST, mount and unmount (kio_file) |
654 | * |
655 | * \a data packed data; the meaning is completely dependent on the |
656 | * slave, but usually starts with an int for the command number. |
657 | * Document your slave's commands, at least in its header file. |
658 | */ |
659 | virtual void special(const QByteArray &data); |
660 | |
661 | /* |
662 | * Called to get the status of the slave. Slave should respond |
663 | * by calling slaveStatus(...) |
664 | */ |
665 | virtual void slave_status(); |
666 | |
667 | /* |
668 | * Called by the scheduler to tell the slave that the configuration |
669 | * changed (i.e.\ proxy settings). |
670 | */ |
671 | virtual void reparseConfiguration(); |
672 | |
673 | #if KIOCORE_BUILD_DEPRECATED_SINCE(6, 11) |
674 | /*! |
675 | * Returns timeout value for connecting to remote host. |
676 | * |
677 | * This is not used. |
678 | * |
679 | * \deprecated[6.11] |
680 | */ |
681 | int connectTimeout(); |
682 | #endif |
683 | |
684 | #if KIOCORE_BUILD_DEPRECATED_SINCE(6, 11) |
685 | /*! |
686 | * Returns timeout value for connecting to proxy in secs. |
687 | * |
688 | * This is not used. |
689 | * |
690 | * \deprecated[6.11] |
691 | */ |
692 | int proxyConnectTimeout(); |
693 | #endif |
694 | |
695 | #if KIOCORE_BUILD_DEPRECATED_SINCE(6, 11) |
696 | /*! |
697 | * Returns timeout value for read from first data from |
698 | * remote host in seconds. |
699 | * |
700 | * This is not used. |
701 | * |
702 | * \deprecated[6.11] |
703 | */ |
704 | int responseTimeout(); |
705 | #endif |
706 | |
707 | #if KIOCORE_BUILD_DEPRECATED_SINCE(6, 11) |
708 | /*! |
709 | * Returns timeout value for read from subsequent data from |
710 | * remote host in secs. |
711 | * |
712 | * This is not used. |
713 | * |
714 | * \deprecated[6.11] |
715 | */ |
716 | int readTimeout(); |
717 | #endif |
718 | |
719 | /* |
720 | * This function sets a timeout of @p timeout seconds and calls |
721 | * special(data) when the timeout occurs as if it was called by the |
722 | * application. |
723 | * |
724 | * A timeout can only occur when the slave is waiting for a command |
725 | * from the application. |
726 | * |
727 | * Specifying a negative timeout cancels a pending timeout. |
728 | * |
729 | * Only one timeout at a time is supported, setting a timeout |
730 | * cancels any pending timeout. |
731 | */ |
732 | void setTimeoutSpecialCommand(int timeout, const QByteArray &data = QByteArray()); |
733 | |
734 | ///////////////// |
735 | // Dispatching (internal) |
736 | //////////////// |
737 | |
738 | /* |
739 | * \internal |
740 | */ |
741 | virtual void dispatch(int command, const QByteArray &data); |
742 | |
743 | /* |
744 | * \internal |
745 | */ |
746 | virtual void dispatchOpenCommand(int command, const QByteArray &data); |
747 | |
748 | /* |
749 | * Read data sent by the job, after a dataReq |
750 | * |
751 | * \a buffer buffer where data is stored |
752 | * Returns 0 on end of data, |
753 | * > 0 bytes read |
754 | * < 0 error |
755 | **/ |
756 | int readData(QByteArray &buffer); |
757 | |
758 | /* |
759 | * It collects entries and emits them via listEntries |
760 | * when enough of them are there or a certain time |
761 | * frame exceeded (to make sure the app gets some |
762 | * items in time but not too many items one by one |
763 | * as this will cause a drastic performance penalty). |
764 | * \a entry The UDSEntry containing all of the object attributes. |
765 | * \since 5.0 |
766 | */ |
767 | void listEntry(const UDSEntry &entry); |
768 | |
769 | /* |
770 | * internal function to connect a slave to/ disconnect from |
771 | * either the slave pool or the application |
772 | */ |
773 | void connectSlave(const QString &path); |
774 | void disconnectSlave(); |
775 | |
776 | /* |
777 | * Prompt the user for Authorization info (login & password). |
778 | * |
779 | * Use this function to request authorization information from |
780 | * the end user. You can also pass an error message which explains |
781 | * why a previous authorization attempt failed. Here is a very |
782 | * simple example: |
783 | * |
784 | * \code |
785 | * KIO::AuthInfo authInfo; |
786 | * int errorCode = openPasswordDialogV2(authInfo); |
787 | * if (!errorCode) { |
788 | * qDebug() << QLatin1String("User: ") << authInfo.username; |
789 | * qDebug() << QLatin1String("Password: not displayed here!"); |
790 | * } else { |
791 | * error(errorCode, QString()); |
792 | * } |
793 | * \endcode |
794 | * |
795 | * You can also preset some values like the username, caption or |
796 | * comment as follows: |
797 | * |
798 | * \code |
799 | * KIO::AuthInfo authInfo; |
800 | * authInfo.caption = i18n("Acme Password Dialog"); |
801 | * authInfo.username = "Wile E. Coyote"; |
802 | * QString errorMsg = i18n("You entered an incorrect password."); |
803 | * int errorCode = openPasswordDialogV2(authInfo, errorMsg); |
804 | * [...] |
805 | * \endcode |
806 | * |
807 | * \note You should consider using checkCachedAuthentication() to |
808 | * see if the password is available in kpasswdserver before calling |
809 | * this function. |
810 | * |
811 | * \note A call to this function can fail and return @p false, |
812 | * if the password server could not be started for whatever reason. |
813 | * |
814 | * \note This function does not store the password information |
815 | * automatically (and has not since kdelibs 4.7). If you want to |
816 | * store the password information in a persistent storage like |
817 | * KWallet, then you MUST call @ref cacheAuthentication. |
818 | * |
819 | * \sa checkCachedAuthentication |
820 | * \a info See AuthInfo. |
821 | * \a errorMsg Error message to show |
822 | * Returns a KIO error code: NoError (0), KIO::USER_CANCELED, or other error codes. |
823 | */ |
824 | int openPasswordDialogV2(KIO::AuthInfo &info, const QString &errorMsg = QString()); |
825 | |
826 | /* |
827 | * Checks for cached authentication based on parameters |
828 | * given by @p info. |
829 | * |
830 | * Use this function to check if any cached password exists |
831 | * for the URL given by @p info. If @p AuthInfo::realmValue |
832 | * and/or @p AuthInfo::verifyPath flag is specified, then |
833 | * they will also be factored in determining the presence |
834 | * of a cached password. Note that @p Auth::url is a required |
835 | * parameter when attempting to check for cached authorization |
836 | * info. Here is a simple example: |
837 | * |
838 | * \code |
839 | * AuthInfo info; |
840 | * info.url = QUrl("https://www.foobar.org/foo/bar"); |
841 | * info.username = "somename"; |
842 | * info.verifyPath = true; |
843 | * if ( !checkCachedAuthentication( info ) ) |
844 | * { |
845 | * int errorCode = openPasswordDialogV2(info); |
846 | * .... |
847 | * } |
848 | * \endcode |
849 | * |
850 | * \a info See AuthInfo. |
851 | * Returns @p true if cached Authorization is found, false otherwise. |
852 | */ |
853 | bool checkCachedAuthentication(AuthInfo &info); |
854 | |
855 | /* |
856 | * Caches @p info in a persistent storage like KWallet. |
857 | * |
858 | * Note that calling openPasswordDialogV2 does not store passwords |
859 | * automatically for you (and has not since kdelibs 4.7). |
860 | * |
861 | * Here is a simple example of how to use cacheAuthentication: |
862 | * |
863 | * \code |
864 | * AuthInfo info; |
865 | * info.url = QUrl("https://www.foobar.org/foo/bar"); |
866 | * info.username = "somename"; |
867 | * info.verifyPath = true; |
868 | * if ( !checkCachedAuthentication( info ) ) { |
869 | * int errorCode = openPasswordDialogV2(info); |
870 | * if (!errorCode) { |
871 | * if (info.keepPassword) { // user asked password be save/remembered |
872 | * cacheAuthentication(info); |
873 | * } |
874 | * } |
875 | * } |
876 | * \endcode |
877 | * |
878 | * \a info See AuthInfo. |
879 | * Returns @p true if @p info was successfully cached. |
880 | */ |
881 | bool cacheAuthentication(const AuthInfo &info); |
882 | |
883 | /* |
884 | * Wait for an answer to our request, until we get @p expected1 or @p expected2 |
885 | * Returns the result from readData, as well as the cmd in *pCmd if set, and the data in @p data |
886 | */ |
887 | int waitForAnswer(int expected1, int expected2, QByteArray &data, int *pCmd = nullptr); |
888 | |
889 | /* |
890 | * Internal function to transmit meta data to the application. |
891 | * m_outgoingMetaData will be cleared; this means that if the slave is for |
892 | * example put on hold and picked up by a different KIO::Job later the new |
893 | * job will not see the metadata sent before. |
894 | * See kio/DESIGN.krun for an overview of the state |
895 | * progression of a job/slave. |
896 | * @warning calling this method may seriously interfere with the operation |
897 | * of KIO which relies on the presence of some metadata at some points in time. |
898 | * You should not use it if you are not familiar with KIO and not before |
899 | * the slave is connected to the last job before returning to idle state. |
900 | */ |
901 | void sendMetaData(); |
902 | |
903 | /* |
904 | * Internal function to transmit meta data to the application. |
905 | * Like sendMetaData() but m_outgoingMetaData will not be cleared. |
906 | * This method is mainly useful in code that runs before the slave is connected |
907 | * to its final job. |
908 | */ |
909 | void sendAndKeepMetaData(); |
910 | |
911 | /* If your ioslave was killed by a signal, wasKilled() returns true. |
912 | Check it regularly in lengthy functions (e.g. in get();) and return |
913 | as fast as possible from this function if wasKilled() returns true. |
914 | This will ensure that your slave destructor will be called correctly. |
915 | */ |
916 | bool wasKilled() const; |
917 | |
918 | /* Internally used. |
919 | * \internal |
920 | */ |
921 | void setKillFlag(); |
922 | |
923 | /* Internally used |
924 | * \internal |
925 | */ |
926 | void lookupHost(const QString &host); |
927 | |
928 | /* Internally used |
929 | * \internal |
930 | */ |
931 | int waitForHostInfo(QHostInfo &info); |
932 | |
933 | /* |
934 | * Checks with job if privilege operation is allowed. |
935 | * Returns privilege operation status. |
936 | * \sa PrivilegeOperationStatus |
937 | * \since 5.66 |
938 | */ |
939 | PrivilegeOperationStatus requestPrivilegeOperation(const QString &operationDetails); |
940 | |
941 | /* |
942 | * Adds @p action to the list of PolicyKit actions which the |
943 | * slave is authorized to perform. |
944 | * |
945 | * \a action the PolicyKit action |
946 | * \since 5.45 |
947 | */ |
948 | void addTemporaryAuthorization(const QString &action); |
949 | |
950 | protected: |
951 | /* |
952 | * Name of the protocol supported by this slave |
953 | */ |
954 | QByteArray mProtocol; |
955 | // Often used by TcpSlaveBase and unlikely to change |
956 | MetaData mOutgoingMetaData; |
957 | MetaData mIncomingMetaData; |
958 | |
959 | enum VirtualFunctionId { |
960 | AppConnectionMade = 0, |
961 | GetFileSystemFreeSpace = 1, // KF6 TODO: Turn into a virtual method |
962 | Truncate = 2, // KF6 TODO: Turn into a virtual method |
963 | }; |
964 | virtual void virtual_hook(int id, void *data); |
965 | |
966 | private: |
967 | // Convenience function converting mProtocol to QString as unsupportedActionErrorString(), which |
968 | // is used in many places in the code, takes a QString parameter |
969 | inline const QString protocolName() const |
970 | { |
971 | return QString::fromLatin1(ba: mProtocol); |
972 | } |
973 | |
974 | void setRunInThread(bool b); |
975 | |
976 | // This helps catching missing tr()/i18n() calls in error(). |
977 | void error(int _errid, const QByteArray &_text); |
978 | void send(int cmd, const QByteArray &arr = QByteArray()); |
979 | |
980 | std::unique_ptr<SlaveBasePrivate> const d; |
981 | friend class SlaveBasePrivate; |
982 | friend class WorkerThread; |
983 | friend class WorkerBasePrivate; |
984 | friend class WorkerSlaveBaseBridge; |
985 | }; |
986 | } |
987 | |
988 | #endif |
989 | |
990 | // HACK see comments in workerbase.h for same include/declaration guard |
991 | #ifndef KIO_UNSUPPORTEDACTIONERRORSTRING |
992 | #define KIO_UNSUPPORTEDACTIONERRORSTRING |
993 | |
994 | namespace KIO |
995 | { |
996 | |
997 | /* |
998 | * Returns an appropriate error message if the given command @p cmd |
999 | * is an unsupported action (ERR_UNSUPPORTED_ACTION). |
1000 | * \a protocol name of the protocol |
1001 | * \a cmd given command |
1002 | * \sa enum Command |
1003 | */ |
1004 | KIOCORE_EXPORT QString unsupportedActionErrorString(const QString &protocol, int cmd); |
1005 | } |
1006 | |
1007 | #endif |
1008 | |