TDE core libraries
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

job.h 22KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532
  1. // -*- c++ -*-
  2. /* This file is part of the KDE libraries
  3. Copyright (C) 2000 Stephan Kulow <coolo@kde.org>
  4. David Faure <faure@kde.org>
  5. This library is free software; you can redistribute it and/or
  6. modify it under the terms of the GNU Library General Public
  7. License as published by the Free Software Foundation; either
  8. version 2 of the License, or (at your option) any later version.
  9. This library is distributed in the hope that it will be useful,
  10. but WITHOUT ANY WARRANTY; without even the implied warranty of
  11. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  12. Library General Public License for more details.
  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. #ifndef __tdeio_job_h__
  19. #define __tdeio_job_h__
  20. #include <tdeio/jobclasses.h>
  21. namespace TDEIO {
  22. /**
  23. * Creates a single directory.
  24. *
  25. *
  26. *
  27. *
  28. * @param url The URL of the directory to create.
  29. * @param permissions The permissions to set after creating the
  30. * directory (unix-style), -1 for default permissions.
  31. * @return A pointer to the job handling the operation.
  32. */
  33. TDEIO_EXPORT SimpleJob * mkdir( const KURL& url, int permissions = -1 );
  34. /**
  35. * Removes a single directory.
  36. *
  37. * The directory is assumed to be empty.
  38. *
  39. *
  40. *
  41. * @param url The URL of the directory to remove.
  42. * @return A pointer to the job handling the operation.
  43. */
  44. TDEIO_EXPORT SimpleJob * rmdir( const KURL& url );
  45. /**
  46. * Changes permissions on a file or directory.
  47. * See the other chmod below for changing many files
  48. * or directories.
  49. *
  50. * @param url The URL of file or directory.
  51. * @param permissions The permissions to set.
  52. * @return the job handling the operation.
  53. */
  54. TDEIO_EXPORT SimpleJob * chmod( const KURL& url, int permissions );
  55. /**
  56. * Rename a file or directory.
  57. * Warning: this operation fails if a direct renaming is not
  58. * possible (like with files or dirs on separate partitions)
  59. * Use move or file_move in this case.
  60. *
  61. * @param src The original URL
  62. * @param dest The final URL
  63. * @param overwrite whether to automatically overwrite if the dest exists
  64. * @return the job handling the operation.
  65. */
  66. TDEIO_EXPORT SimpleJob * rename( const KURL& src, const KURL & dest, bool overwrite );
  67. /**
  68. * Create or move a symlink.
  69. * This is the lowlevel operation, similar to file_copy and file_move.
  70. * It doesn't do any check (other than those the slave does)
  71. * and it doesn't show rename and skip dialogs - use TDEIO::link for that.
  72. * @param target The string that will become the "target" of the link (can be relative)
  73. * @param dest The symlink to create.
  74. * @param overwrite whether to automatically overwrite if the dest exists
  75. * @param showProgressInfo true to show progress information
  76. * @return the job handling the operation.
  77. */
  78. TDEIO_EXPORT SimpleJob * symlink( const TQString & target, const KURL& dest, bool overwrite, bool showProgressInfo = true );
  79. /**
  80. * Execute any command that is specific to one slave (protocol).
  81. *
  82. * Examples are : HTTP POST, mount and unmount (tdeio_file)
  83. *
  84. * @param url The URL isn't passed to the slave, but is used to know
  85. * which slave to send it to :-)
  86. * @param data Packed data. The meaning is completely dependent on the
  87. * slave, but usually starts with an int for the command number.
  88. * @param showProgressInfo true to show progress information
  89. * @return the job handling the operation.
  90. */
  91. TDEIO_EXPORT SimpleJob * special( const KURL& url, const TQByteArray & data, bool showProgressInfo = true );
  92. /**
  93. * Mount filesystem.
  94. *
  95. * Special job for @p tdeio_file.
  96. *
  97. * @param ro Mount read-only if @p true.
  98. * @param fstype File system type (e.g. "ext2", can be 0L).
  99. * @param dev Device (e.g. /dev/sda0).
  100. * @param point Mount point, can be @p null.
  101. * @param showProgressInfo true to show progress information
  102. * @return the job handling the operation.
  103. */
  104. TDEIO_EXPORT SimpleJob *mount( bool ro, const char *fstype, const TQString& dev, const TQString& point, bool showProgressInfo = true );
  105. /**
  106. * Unmount filesystem.
  107. *
  108. * Special job for @p tdeio_file.
  109. *
  110. * @param point Point to unmount.
  111. * @param showProgressInfo true to show progress information
  112. * @return the job handling the operation.
  113. */
  114. TDEIO_EXPORT SimpleJob *unmount( const TQString & point, bool showProgressInfo = true );
  115. /**
  116. * Retrieve local URL if available
  117. *
  118. * @param remoteURL the remote URL to get the local URL for
  119. * @return the job handling the operation.
  120. */
  121. TDEIO_EXPORT LocalURLJob *localURL( const KURL& remoteUrl );
  122. /**
  123. * HTTP cache update
  124. *
  125. * @param url Url to update, protocol must be "http".
  126. * @param no_cache If true, cache entry for @p url is deleted.
  127. * @param expireDate Local machine time indicating when the entry is
  128. * supposed to expire.
  129. * @return the job handling the operation.
  130. */
  131. TDEIO_EXPORT SimpleJob *http_update_cache( const KURL& url, bool no_cache, time_t expireDate);
  132. /**
  133. * Find all details for one file or directory.
  134. *
  135. * @param url the URL of the file
  136. * @param showProgressInfo true to show progress information
  137. * @return the job handling the operation.
  138. */
  139. TDEIO_EXPORT StatJob * stat( const KURL& url, bool showProgressInfo = true );
  140. /**
  141. * Find all details for one file or directory.
  142. * This version of the call includes two additional booleans, @p sideIsSource and @p details.
  143. *
  144. * @param url the URL of the file
  145. * @param sideIsSource is true when stating a source file (we will do a get on it if
  146. * the stat works) and false when stating a destination file (target of a copy).
  147. * The reason for this parameter is that in some cases the tdeioslave might not
  148. * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP
  149. * has issues with case-sensitivity on some systems).
  150. * When the slave can't reliably determine the existence of a file, it will:
  151. * @li be optimistic if sideIsSource=true, i.e. it will assume the file exists,
  152. * and if it doesn't this will appear when actually trying to download it
  153. * @li be pessimistic if sideIsSource=false, i.e. it will assume the file
  154. * doesn't exist, to prevent showing "about to overwrite" errors to the user.
  155. * If you simply want to check for existence without downloading/uploading afterwards,
  156. * then you should use sideIsSource=false.
  157. *
  158. * @param details selects the level of details we want.
  159. * By default this is 2 (all details wanted, including modification time, size, etc.),
  160. * setDetails(1) is used when deleting: we don't need all the information if it takes
  161. * too much time, no need to follow symlinks etc.
  162. * setDetails(0) is used for very simple probing: we'll only get the answer
  163. * "it's a file or a directory, or it doesn't exist". This is used by KRun.
  164. * @param showProgressInfo true to show progress information
  165. * @return the job handling the operation.
  166. */
  167. TDEIO_EXPORT StatJob * stat( const KURL& url, bool sideIsSource, short int details, bool showProgressInfo = true );
  168. /**
  169. * Get (a.k.a. read).
  170. *
  171. * The slave emits the data through data().
  172. * @param url the URL of the file
  173. * @param reload true to reload the file, false if it can be taken from the cache
  174. * @param showProgressInfo true to show progress information
  175. * @return the job handling the operation.
  176. */
  177. TDEIO_EXPORT TransferJob *get( const KURL& url, bool reload=false, bool showProgressInfo = true );
  178. /**
  179. * Put (a.k.a. write)
  180. *
  181. * @param url Where to write data.
  182. * @param permissions May be -1. In this case no special permission mode is set.
  183. * @param overwrite If true, any existing file will be overwritten.
  184. * @param resume true to resume an operation. Warning, setting this to true means
  185. * that the data will be appended to @p dest if @p dest exists.
  186. * @param showProgressInfo true to show progress information
  187. * @return the job handling the operation.
  188. * @see multi_get()
  189. */
  190. TDEIO_EXPORT TransferJob *put( const KURL& url, int permissions,
  191. bool overwrite, bool resume, bool showProgressInfo = true );
  192. /**
  193. * HTTP POST (for form data).
  194. *
  195. * Example:
  196. * \code
  197. * job = TDEIO::http_post( url, postData, false );
  198. * job->addMetaData("content-type", contentType );
  199. * job->addMetaData("referrer", referrerURL);
  200. * \endcode
  201. *
  202. * @p postData is the data that you want to send and
  203. * @p contentType is the complete HTTP header line that
  204. * specifies the content's MIME type, for example
  205. * "Content-Type: text/xml".
  206. *
  207. * You MUST specify content-type!
  208. *
  209. * Often @p contentType is
  210. * "Content-Type: application/x-www-form-urlencoded" and
  211. * the @p postData is then an ASCII string (without null-termination!)
  212. * with characters like space, linefeed and percent escaped like %20,
  213. * %0A and %25.
  214. *
  215. * @param url Where to write the data.
  216. * @param postData Encoded data to post.
  217. * @param showProgressInfo true to display
  218. * @return the job handling the operation.
  219. */
  220. TDEIO_EXPORT TransferJob *http_post( const KURL& url, const TQByteArray &postData,
  221. bool showProgressInfo = true );
  222. /**
  223. * Get (a.k.a. read), into a single TQByteArray.
  224. * @see StoredTransferJob
  225. *
  226. * @param url the URL of the file
  227. * @param reload true to reload the file, false if it can be taken from the cache
  228. * @param showProgressInfo true to show progress information
  229. * @return the job handling the operation.
  230. * @since 3.3
  231. */
  232. TDEIO_EXPORT StoredTransferJob *storedGet( const KURL& url, bool reload=false, bool showProgressInfo = true );
  233. /**
  234. * Put (a.k.a. write) data from a single TQByteArray.
  235. * @see StoredTransferJob
  236. *
  237. * @param arr The data to write
  238. * @param url Where to write data.
  239. * @param permissions May be -1. In this case no special permission mode is set.
  240. * @param overwrite If true, any existing file will be overwritten.
  241. * @param resume true to resume an operation. Warning, setting this to true means
  242. * that the data will be appended to @p dest if @p dest exists.
  243. * @param showProgressInfo true to show progress information
  244. * @return the job handling the operation.
  245. * @since 3.3
  246. */
  247. TDEIO_EXPORT StoredTransferJob *storedPut( const TQByteArray& arr, const KURL& url, int permissions,
  248. bool overwrite, bool resume, bool showProgressInfo = true );
  249. /**
  250. * Creates a new multiple get job.
  251. *
  252. * @param id the id of the get operation
  253. * @param url the URL of the file
  254. * @param metaData the MetaData associated with the file
  255. *
  256. * @return the job handling the operation.
  257. * @see get()
  258. */
  259. TDEIO_EXPORT MultiGetJob *multi_get( long id, const KURL &url, const MetaData &metaData);
  260. /**
  261. * Find mimetype for one file or directory.
  262. *
  263. * @param url the URL of the file
  264. * @param showProgressInfo true to show progress information
  265. * @return the job handling the operation.
  266. */
  267. TDEIO_EXPORT MimetypeJob * mimetype( const KURL& url,
  268. bool showProgressInfo = true );
  269. /**
  270. * Copy a single file.
  271. *
  272. * Uses either SlaveBase::copy() if the slave supports that
  273. * or get() and put() otherwise.
  274. * @param src Where to get the file.
  275. * @param dest Where to put the file.
  276. * @param permissions May be -1. In this case no special permission mode is set.
  277. * @param overwrite If true, any existing file will be overwritten.
  278. * @param resume true to resume an operation. Warning, setting this to true means
  279. * that @p src will be appended to @p dest if @p dest exists.
  280. * You probably don't want that, so leave it to false :)
  281. *
  282. * @param showProgressInfo true to show progress information
  283. * @return the job handling the operation.
  284. */
  285. TDEIO_EXPORT FileCopyJob *file_copy( const KURL& src, const KURL& dest, int permissions=-1,
  286. bool overwrite=false, bool resume=false,
  287. bool showProgressInfo = true);
  288. /**
  289. * Move a single file.
  290. *
  291. * Use either SlaveBase::rename() if the slave supports that,
  292. * or copy() and del() otherwise, or eventually get() & put() & del()
  293. * @param src Where to get the file.
  294. * @param dest Where to put the file.
  295. * @param permissions May be -1. In this case no special permission mode is set.
  296. * @param overwrite If @p true, any existing file will be overwritten.
  297. * @param resume true to resume an operation. Warning, setting this to true means
  298. * that @p src will be appended to @p dest if @p dest exists.
  299. * You probably don't want that, so leave it to false :)
  300. * @param showProgressInfo true to show progress information
  301. * @return the job handling the operation.
  302. */
  303. TDEIO_EXPORT FileCopyJob *file_move( const KURL& src, const KURL& dest, int permissions=-1,
  304. bool overwrite=false, bool resume=false,
  305. bool showProgressInfo = true);
  306. /**
  307. * Delete a single file.
  308. *
  309. * @param src File to delete.
  310. * @param showProgressInfo true to show progress information
  311. * @return the job handling the operation.
  312. */
  313. TDEIO_EXPORT SimpleJob *file_delete( const KURL& src, bool showProgressInfo = true);
  314. /**
  315. * List the contents of @p url, which is assumed to be a directory.
  316. *
  317. * "." and ".." are returned, filter them out if you don't want them.
  318. *
  319. *
  320. * @param url the url of the directory
  321. * @param showProgressInfo true to show progress information
  322. * @param includeHidden true for all files, false to cull out UNIX hidden
  323. * files/dirs (whose names start with dot)
  324. * @return the job handling the operation.
  325. */
  326. TDEIO_EXPORT ListJob *listDir( const KURL& url, bool showProgressInfo = true,
  327. bool includeHidden = true );
  328. /**
  329. * The same as the previous method, but recurses subdirectories.
  330. * Directory links are not followed.
  331. *
  332. * "." and ".." are returned but only for the toplevel directory.
  333. * Filter them out if you don't want them.
  334. *
  335. * @param url the url of the directory
  336. * @param showProgressInfo true to show progress information
  337. * @param includeHidden true for all files, false to cull out UNIX hidden
  338. * files/dirs (whose names start with dot)
  339. * @return the job handling the operation.
  340. */
  341. TDEIO_EXPORT ListJob *listRecursive( const KURL& url, bool showProgressInfo = true,
  342. bool includeHidden = true );
  343. /**
  344. * Copy a file or directory @p src into the destination @p dest,
  345. * which can be a file (including the final filename) or a directory
  346. * (into which @p src will be copied).
  347. *
  348. * This emulates the cp command completely.
  349. *
  350. * @param src the file or directory to copy
  351. * @param dest the destination
  352. * @param showProgressInfo true to show progress information
  353. * @return the job handling the operation
  354. * @see copyAs()
  355. */
  356. TDEIO_EXPORT CopyJob *copy( const KURL& src, const KURL& dest, bool showProgressInfo = true );
  357. /**
  358. * Copy a file or directory @p src into the destination @p dest,
  359. * which is the destination name in any case, even for a directory.
  360. *
  361. * As opposed to copy(), this doesn't emulate cp, but is the only
  362. * way to copy a directory, giving it a new name and getting an error
  363. * box if a directory already exists with the same name.
  364. *
  365. * @param src the file or directory to copy
  366. * @param dest the destination
  367. * @param showProgressInfo true to show progress information
  368. * @return the job handling the operation
  369. */
  370. TDEIO_EXPORT CopyJob *copyAs( const KURL& src, const KURL& dest, bool showProgressInfo = true );
  371. /**
  372. * Copy a list of file/dirs @p src into a destination directory @p dest.
  373. *
  374. * @param src the list of files and/or directories
  375. * @param dest the destination
  376. * @param showProgressInfo true to show progress information
  377. * @return the job handling the operation
  378. */
  379. TDEIO_EXPORT CopyJob *copy( const KURL::List& src, const KURL& dest, bool showProgressInfo = true );
  380. /**
  381. * Moves a file or directory @p src to the given destination @p dest.
  382. *
  383. * @param src the file or directory to copy
  384. * @param dest the destination
  385. * @param showProgressInfo true to show progress information
  386. * @return the job handling the operation
  387. * @see copy()
  388. * @see moveAs()
  389. */
  390. TDEIO_EXPORT CopyJob *move( const KURL& src, const KURL& dest, bool showProgressInfo = true );
  391. /**
  392. * Moves a file or directory @p src to the given destination @p dest. Unlike move()
  393. * this operation will fail when the directory already exists.
  394. *
  395. * @param src the file or directory to copy
  396. * @param dest the destination
  397. * @param showProgressInfo true to show progress information
  398. * @return the job handling the operation
  399. * @see copyAs()
  400. */
  401. TDEIO_EXPORT CopyJob *moveAs( const KURL& src, const KURL& dest, bool showProgressInfo = true );
  402. /**
  403. * Moves a list of files or directories @p src to the given destination @p dest.
  404. *
  405. * @param src the list of files or directories to copy
  406. * @param dest the destination
  407. * @param showProgressInfo true to show progress information
  408. * @return the job handling the operation
  409. * @see copy()
  410. */
  411. TDEIO_EXPORT CopyJob *move( const KURL::List& src, const KURL& dest, bool showProgressInfo = true );
  412. /**
  413. * Create a link.
  414. * If the protocols and hosts are the same, a Unix symlink will be created.
  415. * Otherwise, a .desktop file of Type Link and pointing to the src URL will be created.
  416. *
  417. * @param src The existing file or directory, 'target' of the link.
  418. * @param destDir Destination directory where the link will be created.
  419. * @param showProgressInfo true to show progress information
  420. * @return the job handling the operation
  421. */
  422. TDEIO_EXPORT CopyJob *link( const KURL& src, const KURL& destDir, bool showProgressInfo = true );
  423. /**
  424. * Create several links
  425. * If the protocols and hosts are the same, a Unix symlink will be created.
  426. * Otherwise, a .desktop file of Type Link and pointing to the src URL will be created.
  427. *
  428. * @param src The existing files or directories, 'targets' of the link.
  429. * @param destDir Destination directory where the links will be created.
  430. * @param showProgressInfo true to show progress information
  431. * @return the job handling the operation
  432. * @see link()
  433. */
  434. TDEIO_EXPORT CopyJob *link( const KURL::List& src, const KURL& destDir, bool showProgressInfo = true );
  435. /**
  436. * Create a link. Unlike link() this operation will fail when the directory already
  437. * exists.
  438. * If the protocols and hosts are the same, a Unix symlink will be created.
  439. * Otherwise, a .desktop file of Type Link and pointing to the src URL will be created.
  440. *
  441. * @param src The existing file or directory, 'target' of the link.
  442. * @param dest Destination directory where the link will be created.
  443. * @param showProgressInfo true to show progress information
  444. * @return the job handling the operation
  445. * @see link ()
  446. * @see copyAs()
  447. */
  448. TDEIO_EXPORT CopyJob *linkAs( const KURL& src, const KURL& dest, bool showProgressInfo = true );
  449. /**
  450. * Trash a file or directory.
  451. * This is currently only supported for local files and directories.
  452. * Use "KURL src; src.setPath( path );" to create a URL from a path.
  453. *
  454. * @param src file to delete
  455. * @param showProgressInfo true to show progress information
  456. * @return the job handling the operation
  457. * @since 3.4
  458. */
  459. TDEIO_EXPORT CopyJob *trash( const KURL& src, bool showProgressInfo = true );
  460. /**
  461. * Trash a list of files or directories.
  462. * This is currently only supported for local files and directories.
  463. *
  464. * @param src the files to delete
  465. * @param showProgressInfo true to show progress information
  466. * @return the job handling the operation
  467. * @since 3.4
  468. */
  469. TDEIO_EXPORT CopyJob *trash( const KURL::List& src, bool showProgressInfo = true );
  470. /**
  471. * Delete a file or directory.
  472. *
  473. * @param src file to delete
  474. * @param shred obsolete (TODO remove in KDE4)
  475. * @param showProgressInfo true to show progress information
  476. * @return the job handling the operation
  477. */
  478. TDEIO_EXPORT DeleteJob *del( const KURL& src, bool shred = false, bool showProgressInfo = true );
  479. /**
  480. * Deletes a list of files or directories.
  481. *
  482. * @param src the files to delete
  483. * @param shred obsolete (TODO remove in KDE4)
  484. * @param showProgressInfo true to show progress information
  485. * @return the job handling the operation
  486. */
  487. TDEIO_EXPORT DeleteJob *del( const KURL::List& src, bool shred = false, bool showProgressInfo = true );
  488. }
  489. #endif