1 /* This file is part of the KDE libraries 2 * Copyright (C) 1999 Torben Weis <weis@kde.org> 3 * Copyright (C) 2005-2006 David Faure <faure@kde.org> 4 * 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 * 10 * This library is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * Library General Public License for more details. 14 * 15 * You should have received a copy of the GNU Library General Public License 16 * along with this library; see the file COPYING.LIB. If not, write to 17 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 18 * Boston, MA 02110-1301, USA. 19 */ 20 21 #ifndef kurl_h 22 #define kurl_h 23 24 #include <kdelibs4support_export.h> 25 26 #ifdef KDELIBS4SUPPORT_NO_DEPRECATED_NOISE 27 #warning "This file is deprecated." 28 #endif 29 30 #include <QVariant> 31 #include <QUrl> 32 #include <QMap> 33 34 class QStringList; 35 class QMimeData; 36 37 class KUrlPrivate; 38 39 /** 40 * \class KUrl kurl.h <KUrl> 41 * 42 * Represents and parses a URL. 43 * 44 * A prototypical URL looks like: 45 * \code 46 * protocol://user:password\@hostname:port/path/to/file.ext#reference 47 * \endcode 48 * 49 * KUrl handles escaping of URLs. This means that the specification 50 * of a full URL will differ from the corresponding string that would specify a 51 * local file or directory in file-operations like fopen. This is because an URL 52 * doesn't allow certain characters and escapes them. (e.g. '#'->"%23", space->"%20") 53 * (In a URL the hash-character '#' is used to specify a "reference", i.e. the position 54 * within a document). 55 * 56 * The constructor KUrl(const QString&) expects a string properly escaped, 57 * or at least non-ambiguous. 58 * If you have the absolute path you should use KUrl::fromPath(const QString&). 59 * \code 60 * KUrl kurl = KUrl::fromPath("/bar/#foo#"); 61 * QString url = kurl.url(); // -> "file:///bar/%23foo%23" 62 * \endcode 63 * 64 * If you have the URL of a local file or directory and need the absolute path, 65 * you would use toLocalFile(). 66 * \code 67 * KUrl url( "file:///bar/%23foo%23" ); 68 * ... 69 * if ( url.isLocalFile() ) 70 * QString path = url.toLocalFile(); // -> "/bar/#foo#" 71 * \endcode 72 * 73 * This must also be considered when you have separated directory and file 74 * strings and need to put them together. 75 * While you can simply concatenate normal path strings, you must take care if 76 * the directory-part is already an escaped URL. 77 * (This might be needed if the user specifies a relative path, and your 78 * program supplies the rest from elsewhere.) 79 * 80 * Wrong: 81 * \code 82 * QString dirUrl = "file:///bar/"; 83 * QString fileName = "#foo#"; 84 * QString invalidURL = dirUrl + fileName; // -> "file:///bar/#foo#" won't behave like you would expect. 85 * \endcode 86 * Instead you should use addPath(): 87 * Right: 88 * \code 89 * KUrl url( "file:///bar/" ); 90 * QString fileName = "#foo#"; 91 * url.addPath( fileName ); 92 * QString validURL = url.url(); // -> "file:///bar/%23foo%23" 93 * \endcode 94 * 95 * Also consider that some URLs contain the password, but this shouldn't be 96 * visible. Your program should use prettyUrl() every time it displays a 97 * URL, whether in the GUI or in debug output or... 98 * 99 * \code 100 * KUrl url( "ftp://name:password@ftp.faraway.org/bar/%23foo%23"); 101 * QString visibleURL = url.prettyUrl(); // -> "ftp://name@ftp.faraway.org/bar/%23foo%23" 102 * \endcode 103 * Note that prettyUrl() doesn't change the character escapes (like "%23"). 104 * Otherwise the URL would be invalid and the user wouldn't be able to use it in another 105 * context. 106 * 107 * @deprecated since 5.0; use QUrl directly 108 */ 109 class KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE KUrl : public QUrl // krazy:exclude=dpointer,qclasses (krazy can't deal with embedded classes) 110 { 111 public: 112 typedef QMap<QString, QString> MetaDataMap; 113 enum MimeDataFlags { DefaultMimeDataFlags = 0, NoTextExport = 1 }; 114 115 /** 116 * Options to be used in adjustPath 117 */ 118 enum AdjustPathOption { 119 /** 120 * strips a trailing '/', except when the path is already just "/". 121 */ 122 RemoveTrailingSlash, 123 124 /** 125 * Do not change the path. 126 */ 127 LeaveTrailingSlash, 128 129 /** 130 * adds a trailing '/' if there is none yet 131 */ 132 AddTrailingSlash 133 }; 134 135 /** 136 * \class List kurl.h <KUrl> 137 * 138 * KUrl::List is a QList that contains KUrls with a few 139 * convenience methods. 140 * @see KUrl 141 * @see QList 142 */ 143 class KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE List : public QList<KUrl> //krazy:exclude=dpointer (just some convenience methods) 144 { 145 public: 146 /** 147 * Creates an empty List. 148 */ List()149 List() { } 150 /** 151 * Creates a list that contains the given URL as only 152 * item. 153 * @param url the url to add. 154 */ 155 List(const KUrl &url); 156 /** 157 * Creates a list that contains the URLs from the given 158 * list of strings. 159 * @param list the list containing the URLs as strings 160 */ 161 List(const QStringList &list); 162 /** 163 * Creates a list that contains the URLs from the given QList<KUrl>. 164 * @param list the list containing the URLs 165 */ 166 List(const QList<KUrl> &list); 167 /** 168 * Creates a list that contains the URLs from the given QList<KUrl>. 169 * @param list the list containing the URLs 170 * @since 4.7 171 */ 172 List(const QList<QUrl> &list); 173 /** 174 * Converts the URLs of this list to a list of strings. 175 * @return the list of strings 176 */ 177 QStringList toStringList() const; 178 179 /** 180 * Converts the URLs of this list to a list of strings. 181 * 182 * @param trailing use to add or remove a trailing slash to/from the path. 183 * 184 * @return the list of strings 185 * 186 * @since 4.6 187 */ 188 QStringList toStringList(KUrl::AdjustPathOption trailing) const; 189 190 /** 191 * Converts this KUrl::List to a QVariant, this allows to use KUrl::List 192 * in QVariant() constructor 193 */ 194 operator QVariant() const; 195 196 /** 197 * Converts this KUrl::List into a list of QUrl instances. 198 * @since 4.7 199 */ 200 operator QList<QUrl>() const; 201 202 /** 203 * Adds URLs data into the given QMimeData. 204 * 205 * By default, populateMimeData also exports the URLs as plain text, for e.g. dropping 206 * onto a text editor. 207 * But in some cases this might not be wanted, e.g. if adding other mime data 208 * which provides better plain text data. 209 * 210 * WARNING: do not call this method multiple times on the same mimedata object, 211 * you can add urls only once. But you can add other things, e.g. images, XML... 212 * 213 * @param mimeData the QMimeData instance used to drag or copy this URL 214 * @param metaData KIO metadata shipped in the mime data, which is used for instance to 215 * set a correct HTTP referrer (some websites require it for downloading e.g. an image) 216 * @param flags set NoTextExport to prevent setting plain/text data into @p mimeData 217 * 218 * @deprecated since 5.0, use QMimeData::setUrls, followed by KUrlMimeData::setMetaData if you have metadata. 219 */ 220 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED 221 KDELIBS4SUPPORT_DEPRECATED void populateMimeData(QMimeData *mimeData, 222 const KUrl::MetaDataMap &metaData = MetaDataMap(), 223 MimeDataFlags flags = DefaultMimeDataFlags) const; 224 #endif 225 226 /** 227 * Adds URLs into the given QMimeData. 228 * 229 * This should add both the KDE-style URLs (eg: desktop:/foo) and 230 * the "most local" version of the URLs (eg: 231 * file:///home/jbloggs/Desktop/foo) to the mimedata. 232 * 233 * This method should be called on the KDE-style URLs. 234 * 235 * @code 236 * QMimeData* mimeData = new QMimeData(); 237 * 238 * KUrl::List kdeUrls; 239 * kdeUrls << "desktop:/foo"; 240 * kdeUrls << "desktop:/bar"; 241 * 242 * KUrl::List normalUrls; 243 * normalUrls << "file:///home/jbloggs/Desktop/foo"; 244 * normalUrls << "file:///home/jbloggs/Desktop/bar"; 245 * 246 * kdeUrls.populateMimeData(normalUrls, mimeData); 247 * @endcode 248 * 249 * @param mostLocalUrls the "most local" urls 250 * @param mimeData the mime data object to populate 251 * @param metaData KIO metadata shipped in the mime data, which is 252 * used for instance to set a correct HTTP referrer 253 * (some websites require it for downloading e.g. an 254 * image) 255 * @param flags set NoTextExport to prevent setting plain/text 256 * data into @p mimeData. 257 * @since 4.2 258 * @deprecated since 5.0, use KUrlMimeData::setUrls, followed by KUrlMimeData::setMetaData if you have metadata. 259 */ 260 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED 261 KDELIBS4SUPPORT_DEPRECATED void populateMimeData(const KUrl::List &mostLocalUrls, 262 QMimeData *mimeData, 263 const KUrl::MetaDataMap &metaData = MetaDataMap(), 264 MimeDataFlags flags = DefaultMimeDataFlags) const; 265 #endif 266 267 /** 268 * Return true if @p mimeData contains URI data 269 * @deprecated since 5.0, use QMimeData::hasUrls 270 */ 271 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED 272 KDELIBS4SUPPORT_DEPRECATED static bool canDecode(const QMimeData *mimeData); 273 #endif 274 275 /** 276 * Return the list of mimeTypes that can be decoded by fromMimeData 277 * @deprecated since 5.0, use KUrlMimeData::mimeDataTypes 278 */ 279 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED 280 KDELIBS4SUPPORT_DEPRECATED static QStringList mimeDataTypes(); 281 #endif 282 283 /** 284 * Flags to be used in fromMimeData. 285 * @since 4.2.3 286 * @deprecated since 5.0, use KUrlMimeData 287 */ 288 enum DecodeOptions { 289 /** 290 * When the mimedata contains both KDE-style URLs (eg: desktop:/foo) and 291 * the "most local" version of the URLs (eg: file:///home/dfaure/Desktop/foo), 292 * decode it as local urls. Useful in paste/drop operations that end up calling KIO, 293 * so that urls from other users work as well. 294 */ 295 PreferLocalUrls, 296 /** 297 * When the mimedata contains both KDE-style URLs (eg: desktop:/foo) and 298 * the "most local" version of the URLs (eg: file:///home/dfaure/Desktop/foo), 299 * decode it as the KDE-style URL. Useful in DnD code e.g. when moving icons, 300 * and the kde-style url is used as identifier for the icons. 301 */ 302 PreferKdeUrls 303 }; 304 305 /** 306 * Extract a list of KUrls from the contents of @p mimeData. 307 * Decoding will fail if @p mimeData does not contain any URLs, or if at 308 * least one extracted URL is not valid. 309 * @param mimeData the mime data to extract from; cannot be 0 310 * @param decodeOptions options for decoding 311 * @param metaData optional pointer to a map holding the metadata 312 * @return the list of urls 313 * @since 4.2.3 314 * @deprecated since 5.0, use KUrlMimeData::urlsFromMimeData 315 */ 316 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED 317 KDELIBS4SUPPORT_DEPRECATED static KUrl::List fromMimeData(const QMimeData *mimeData, 318 DecodeOptions decodeOptions = PreferKdeUrls, 319 KUrl::MetaDataMap *metaData = nullptr); 320 #endif 321 }; 322 /** 323 * Constructs an empty URL. 324 */ 325 KUrl(); 326 327 /** 328 * Destructs the KUrl object. 329 */ 330 ~KUrl(); 331 332 /** 333 * Usual constructor, to construct from a string. 334 * @param urlOrPath An encoded URL or a path. 335 * 336 * @deprecated since 5.0, use QUrl(str) if it's a URL, QUrl::fromLocalFile(str) if it's a local path, 337 * and QUrl::fromUserInput() if it could be either. 338 */ 339 KUrl(const QString &urlOrPath); 340 /** 341 * Constructor taking a char * @p urlOrPath, which is an _encoded_ representation 342 * of the URL, exactly like the usual constructor. This is useful when 343 * the URL, in its encoded form, is strictly ascii. 344 * @param urlOrPath An encoded URL, or a path. 345 * 346 * @deprecated since 5.0, use QUrl(str) if it's a URL, QUrl::fromLocalFile(str) if it's a local path, 347 * and QUrl::fromUserInput() if it could be either. 348 */ 349 KDELIBS4SUPPORT_DEPRECATED explicit KUrl(const char *urlOrPath); 350 /** 351 * Constructor taking a QByteArray @p urlOrPath, which is an _encoded_ representation 352 * of the URL, exactly like the usual constructor. This is useful when 353 * the URL, in its encoded form, is strictly ascii. 354 * @param urlOrPath An encoded URL, or a path. 355 * 356 * @deprecated since 5.0, use QUrl(str) if it's a URL, QUrl::fromLocalFile(str) if it's a local path, 357 * and QUrl::fromUserInput() if it could be either. 358 */ 359 KDELIBS4SUPPORT_DEPRECATED explicit KUrl(const QByteArray &urlOrPath); 360 361 /** 362 * Copy constructor. 363 * @param u the KUrl to copy 364 */ 365 KUrl(const KUrl &u); 366 /** 367 * Converts from a QUrl. 368 * @param u the QUrl 369 */ 370 KUrl(const QUrl &u); //krazy:exclude=qclasses 371 /** 372 * Constructor allowing relative URLs. 373 * 374 * @param _baseurl The base url. 375 * @param _rel_url A relative or absolute URL. 376 * If this is an absolute URL then @p _baseurl will be ignored. 377 * If this is a relative URL it will be combined with @p _baseurl. 378 * Note that _rel_url should be encoded too, in any case. 379 * So do NOT pass a path here (use setPath or addPath instead). 380 * 381 * @deprecated since 5.0, use QUrl(_baseurl).resolved(QUrl(_rel_url)) 382 */ 383 KUrl(const KUrl &_baseurl, const QString &_rel_url); 384 385 /** 386 * Returns the protocol for the URL (i.e., file, http, etc.), lowercased. 387 * @deprecated since 5.0, use QUrl::scheme() instead 388 */ 389 QString protocol() const; 390 391 /** 392 * @deprecated since 5.0, use QUrl::setScheme() instead 393 */ 394 void setProtocol(const QString &proto); 395 396 /** 397 * @deprecated since 5.0, use QUrl::userName() instead 398 */ 399 QString user() const; 400 401 /** 402 * @deprecated since 5.0, use QUrl::setUserName() instead 403 */ 404 void setUser(const QString &user); 405 406 /** 407 * @deprecated since 5.0, use QUrl::userName() and QString::isEmpty() instead 408 */ 409 bool hasUser() const; 410 411 /** 412 * @deprecated since 5.0, use QUrl::password() instead 413 **/ 414 QString pass() const; 415 416 /** 417 * @deprecated since 5.0, use QUrl::setPassword() instead 418 **/ 419 void setPass(const QString &pass); 420 421 /** 422 * @deprecated since 5.0, use QUrl::password() and QString::isEmpty() instead 423 **/ 424 bool hasPass() const; 425 426 /** 427 * @deprecated since 5.0, use QUrl::host() and QString::isEmpty() instead 428 **/ 429 bool hasHost() const; 430 431 /** 432 * @param trailing use to add or remove a trailing slash to/from the path. see adjustPath 433 434 * @return The current decoded path. This does not include the query. Can 435 * be QString() if no path is set. 436 * 437 * @deprecated since 5.0, use OUrl::toLocalFile() for local file urls and 438 * QUrl::path() for all other cases. You may use QUrl::isLocalFile() to decide 439 * which method to choose. If RemoveTrailingSlash was used, use 440 * url.adjusted(QUrl::StripTrailingSlash).path(). 441 */ 442 QString path(AdjustPathOption trailing = LeaveTrailingSlash) const; 443 444 /** 445 * @param trailing use to add or remove a trailing slash to/from the local path. see adjustPath 446 * 447 * @return The current local path. Can 448 * be QString() if no path is set. 449 * 450 * @deprecated since 5.0, use QUrl::toLocalFile() instead; if 451 * RemoveTrailingSlash was used, use 452 * url.adjusted(QUrl::StripTrailingSlash).toLocalFile() 453 */ 454 QString toLocalFile(AdjustPathOption trailing = LeaveTrailingSlash) const; 455 456 /** 457 * KUrl's setPath on an empty url implies the "file" protocol. 458 * @deprecated since 5.0, use QUrl::fromLocalFile instead, for the case of local paths. 459 * Do not port to QUrl u; u.setPath(...); since that would lead to a URL without a scheme! 460 */ 461 KDELIBS4SUPPORT_DEPRECATED void setPath(const QString &path); 462 463 /** 464 * @deprecated since 5.0, use QUrl::path() and QString::isEmpty() 465 **/ 466 bool hasPath() const; 467 468 /** 469 * Options to be used in cleanPath 470 */ 471 enum CleanPathOption { 472 /** 473 * if set, occurrences of consecutive directory separators 474 * (e.g. /foo//bar) are cleaned up as well. (set by default) 475 */ 476 SimplifyDirSeparators = 0x00, 477 478 /** 479 * The opposite of SimplifyDirSeparators. 480 */ 481 KeepDirSeparators = 0x01 482 }; 483 484 Q_DECLARE_FLAGS(CleanPathOptions, CleanPathOption) 485 486 /** 487 * Resolves "." and ".." components in path. 488 * Some servers seem not to like the removal of extra '/' 489 * even though it is against the specification in RFC 2396. 490 * 491 * @param options use KeepDirSeparators if you don't want to remove consecutive 492 * occurrences of directory separator 493 * @deprecated since 5.0, use url.setPath(QDir::cleanPath(url.path())) in file-management code. 494 * No replacement available yet for the old HTTP issue mentionned above. 495 */ 496 void cleanPath(const CleanPathOption &options = SimplifyDirSeparators); 497 498 /** 499 * Add or remove a trailing slash to/from the path. 500 * 501 * If the URL has no path, then no '/' is added 502 * anyway. And on the other side: If the path is "/", then this 503 * character won't be stripped. Reason: "ftp://weis\@host" means something 504 * completely different than "ftp://weis\@host/". So adding or stripping 505 * the '/' would really alter the URL, while "ftp://host/path" and 506 * "ftp://host/path/" mean the same directory. 507 * 508 * @param trailing RemoveTrailingSlash strips any trailing '/' and 509 * AddTrailingSlash adds a trailing '/' if there is none yet 510 * @deprecated For RemoveTrailingSlash, use url = url.adjusted(QUrl::StripTrailingSlash) (remember 511 * to add the assignment!). For AppendTrailingSlash, use: 512 * if (!url.path().endsWith('/')) url.setPath(url.path() + '/'). 513 */ 514 void adjustPath(AdjustPathOption trailing); 515 516 /** 517 * This is useful for HTTP. It looks first for '?' and decodes then. 518 * The encoded path is the concatenation of the current path and the query. 519 * @param _txt the new path and query. 520 * 521 * @deprecated since 5.0, use QUrl::setPath() and 522 * QUrl::fromPercentEncoding() to set the encoded path; use QUrl::setQuery() 523 * with an appropriate QUrl::ParsingMode value to set the query. 524 */ 525 void setEncodedPathAndQuery(const QString &_txt); 526 527 /** 528 * Option to be used in encodedPathAndQuery 529 **/ 530 enum EncodedPathAndQueryOption { 531 /** 532 * Permit empty path (default) 533 */ 534 PermitEmptyPath = 0x00, 535 /** 536 * If set to true then an empty path is substituted by "/" 537 * (this is the opposite of PermitEmptyPath) 538 */ 539 AvoidEmptyPath = 0x01 540 }; 541 Q_DECLARE_FLAGS(EncodedPathAndQueryOptions, EncodedPathAndQueryOption) 542 543 /** 544 * Returns the encoded path and the query. 545 * 546 * @param trailing add or remove a trailing '/', see adjustPath 547 * @param options a set of flags from EncodedPathAndQueryOption 548 * @return The concatenation of the encoded path , '?' and the encoded query. 549 * 550 * @deprecated since 5.0, use QUrl::path() and QUrl::query(); 551 * QUrl::adjusted() can be used to remove a trailing slash if necessary. 552 */ 553 QString encodedPathAndQuery(AdjustPathOption trailing = LeaveTrailingSlash, const EncodedPathAndQueryOptions &options = PermitEmptyPath) const; 554 555 /** 556 * @param query This is considered to be encoded. This has a good reason: 557 * The query may contain the 0 character. 558 * 559 * The query should start with a '?'. If it doesn't '?' is prepended. 560 * 561 * @deprecated since 5.0, use QUrl::setQuery(QString), but note that it 562 * doesn't start with '?' (it uses null vs empty, instead). 563 */ 564 void setQuery(const QString &query); 565 566 /** 567 * Returns the query of the URL. 568 * The query may contain the 0 character. 569 * If a query is present it always starts with a '?'. 570 * A single '?' means an empty query. 571 * An empty string means no query. 572 * @return The encoded query, or QString() if there is none. 573 * 574 * @deprecated since 5.0, use QByteArray QUrl::query(), but note that it 575 * doesn't start with '?' (QUrl::hasQuery() can be used to distinguish 576 * between no query and an empty query). 577 */ 578 QString query() const; 579 580 /** 581 * Returns the @em encoded reference (or "fragment") of the URL (everything after '#'). 582 * @return the encoded reference, or QString("") if the reference part is empty, 583 * or QString() if the URL has no reference. 584 * @deprecated since 5.0, use QUrl::fragment(QUrl::FullyEncoded) 585 */ 586 QString ref() const; 587 588 /** 589 * Sets the reference/fragment part (everything after '#'). 590 * If you have an encoded fragment already (as a QByteArray), you can call setFragment directly. 591 * @param fragment the @em encoded reference (or QString() to remove it). 592 * @deprecated since 5.0, use QUrl::setFragment() 593 */ 594 void setRef(const QString &fragment); 595 596 /** 597 * Checks whether the URL has a reference/fragment part. 598 * @return true if the URL has a reference part. In a URL like 599 * http://www.kde.org/kdebase.tar#tar:/README it would 600 * return true, too. 601 * @deprecated since 5.0, use QUrl::hasFragment() 602 */ 603 bool hasRef() const; 604 605 /** 606 * Returns the @em unencoded reference (or "fragment") of the URL (everything after '#'). 607 * @return the unencoded reference, or QString("") if the reference part is empty, 608 * or QString() if the URL has no reference. 609 * @see split 610 * @see hasSubUrl 611 * @see encodedHtmlRef 612 * @deprecated since 5.0, use QUrl::fragment(QUrl::FullyDecoded) 613 */ 614 QString htmlRef() const; 615 616 /** 617 * Returns the @em encoded reference (or "fragment") of the URL (everything after '#'). 618 * @return the encoded reference, or QString("") if the reference part is empty, 619 * or QString() if the URL has no reference. 620 * @see ref 621 * @deprecated since 5.0, use QUrl::fragment(QUrl::FullyEncoded) 622 */ 623 QString encodedHtmlRef() const; 624 625 /** 626 * Sets the HTML-style reference. 627 * 628 * @param ref The new reference. This is considered to be @em not encoded in 629 * contrast to setRef(). Use QString() to remove it. 630 * @see htmlRef() 631 * @deprecated since 5.0, use QUrl::setFragment(ref, QUrl::DecodedMode) 632 */ 633 void setHTMLRef(const QString &ref); 634 635 /** 636 * Checks whether there is a HTML reference. 637 * @return true if the URL has an HTML-style reference. 638 * @see htmlRef() 639 * @deprecated since 5.0, use QUrl::hasFragment() 640 */ 641 bool hasHTMLRef() const; 642 643 /** 644 * Checks whether the file is local. 645 * @return true if the file is a plain local file (i.e. uses the file protocol 646 * and no hostname, or the local hostname). 647 * When isLocalFile returns true, you can use toLocalFile to read the file contents. 648 * Otherwise you need to use KIO (e.g. KIO::get). 649 */ 650 bool isLocalFile() const; 651 652 /** 653 * Adds encoding information to url by adding a "charset" parameter. If there 654 * is already a charset parameter, it will be replaced. 655 * @param encoding the encoding to add or QString() to remove the 656 * encoding. 657 */ 658 void setFileEncoding(const QString &encoding); 659 660 /** 661 * Returns encoding information from url, the content of the "charset" 662 * parameter. 663 * @return An encoding suitable for QTextCodec::codecForName() 664 * or QString() if not encoding was specified. 665 */ 666 QString fileEncoding() const; 667 668 /** 669 * Checks whether the URL has any sub URLs. See split() 670 * for examples for sub URLs. 671 * @return true if the file has at least one sub URL. 672 * @see split 673 */ 674 bool hasSubUrl() const; 675 676 /** 677 * Adds to the current path. 678 * Assumes that the current path is a directory. @p txt is appended to the 679 * current path. The function adds '/' if needed while concatenating. 680 * This means it does not matter whether the current path has a trailing 681 * '/' or not. If there is none, it becomes appended. If @p txt 682 * has a leading '/' then this one is stripped. 683 * 684 * @param txt The text to add. It is considered to be decoded. 685 * @deprecated since 5.0, use u.setPath(u.path() + '/' + txt). 686 * If the path might already have a trailing slash, use u = u.adjusted(QUrl::StripTrailingSlash) first. 687 */ 688 void addPath(const QString &txt); 689 690 /** 691 * Options for queryItems. Currently, only one option is 692 * defined: 693 * 694 * @param CaseInsensitiveKeys normalize query keys to lowercase. 695 **/ 696 enum QueryItemsOption { CaseInsensitiveKeys = 1 }; 697 Q_DECLARE_FLAGS(QueryItemsOptions, QueryItemsOption) 698 699 /** 700 * Returns the list of query items as a map mapping keys to values. 701 * 702 * This does the same as QUrl::queryItems(), except that it 703 * decodes "+" into " " in the value, supports CaseInsensitiveKeys, 704 * and returns a different data type. 705 * 706 * @param options any of QueryItemsOption <em>or</em>ed together. 707 * 708 * @return the map of query items or the empty map if the url has no 709 * query items. 710 * @deprecated since 5.0, use QUrlQuery(url).queryItems() 711 */ 712 QMap< QString, QString > queryItems(const QueryItemsOptions &options = {}) const; 713 714 /** 715 * Returns the value of a certain query item. 716 * 717 * This does the same as QUrl::queryItemValue(), except that it 718 * decodes "+" into " " in the value. 719 * 720 * @param item Item whose value we want 721 * 722 * @return the value of the given query item name or QString() if the 723 * specified item does not exist. 724 * @deprecated since 5.0, use QUrlQuery(url).queryItemValue(item) 725 */ 726 QString queryItem(const QString &item) const; 727 728 /** 729 * Add an additional query item. 730 * To replace an existing query item, the item should first be 731 * removed with removeQueryItem() 732 * 733 * @param _item Name of item to add 734 * @param _value Value of item to add 735 * @deprecated since 5.0, use QUrlQuery(url), then addQueryItem(), then QUrl::setQuery() 736 */ 737 void addQueryItem(const QString &_item, const QString &_value); 738 739 /** 740 * Sets the filename of the path. 741 * In comparison to addPath() this function does not assume that the current 742 * path is a directory. This is only assumed if the current path ends with '/'. 743 * 744 * Any reference is reset. 745 * 746 * @param _txt The filename to be set. It is considered to be decoded. If the 747 * current path ends with '/' then @p _txt int just appended, otherwise 748 * all text behind the last '/' in the current path is erased and 749 * @p _txt is appended then. It does not matter whether @p _txt starts 750 * with '/' or not. 751 * @deprecated since 5.0, use u = u.adjusted(QUrl::RemoveFilename); followed by 752 * u.setPath(u.path() + txt); 753 */ 754 void setFileName(const QString &_txt); 755 756 /** 757 * option to be used in fileName and directory 758 */ 759 enum DirectoryOption { 760 /** 761 * This tells whether a trailing '/' should be ignored. 762 * 763 * If the flag is not set, for both <tt>file:///hallo/torben/</tt> and <tt>file:///hallo/torben</tt> 764 * the fileName is "torben" and the path is "hallo" 765 * 766 * If the flag is set, then everything behind the last '/'is considered to be the filename. 767 * So "hallo/torben" will be the path and the filename will be empty. 768 */ 769 ObeyTrailingSlash = 0x02, 770 /** 771 * tells whether the returned result should end with '/' or not. 772 * If the flag is set, '/' is added to the end of the path 773 * 774 * If the path is empty or just "/" then this flag has no effect. 775 * 776 * This option should only be used in directory(), it has no effect in fileName() 777 */ 778 AppendTrailingSlash = 0x04, 779 /** 780 * Opposite of ObeyTrailingSlash (default) 781 * fileName("file:/foo/") and fileName("file:/foo") is "foo" in both cases. 782 */ 783 IgnoreTrailingSlash = 0x01 784 785 }; 786 Q_DECLARE_FLAGS(DirectoryOptions, DirectoryOption) 787 788 /** 789 * Returns the filename of the path. 790 * @param options a set of DirectoryOption flags. (StripTrailingSlashFromResult has no effect) 791 * @return The filename of the current path. The returned string is decoded. Null 792 * if there is no file (and thus no path). 793 * @deprecated since 5.0, use url.fileName(), which behaves like ObeyTrailingSlash though. 794 * To get rid of the trailing slash if there could be one, use adjusted(QUrl::StripTrailingSlash) first. 795 */ 796 QString fileName(const DirectoryOptions &options = IgnoreTrailingSlash) const; 797 798 /** 799 * Returns the directory of the path. 800 * @param options a set of DirectoryOption flags 801 * @return The directory part of the current path. Everything between the last and the second last '/' 802 * is returned. For example <tt>file:///hallo/torben/</tt> would return "/hallo/torben/" while 803 * <tt>file:///hallo/torben</tt> would return "hallo/". The returned string is decoded. 804 * QString() is returned when there is no path. 805 * @deprecated since 5.0, use url.adjusted(QUrl::RemoveFilename).path(), which behaves like ObeyTrailingSlash though. 806 * To get rid of the trailing slash if there could be one, use adjusted(QUrl::StripTrailingSlash) first. 807 * Do not combine the two calls! You want to remove the trailing slash first, and then remove the filename. 808 */ 809 QString directory(const DirectoryOptions &options = IgnoreTrailingSlash) const; 810 811 /** 812 * Set the directory to @p dir, leaving the filename empty. 813 */ 814 void setDirectory(const QString &dir); 815 816 /** 817 * Changes the directory by descending into the given directory. 818 * It is assumed the current URL represents a directory. 819 * If @p dir starts with a "/" the 820 * current URL will be "protocol://host/dir" otherwise @p _dir will 821 * be appended to the path. @p _dir can be ".." 822 * This function won't strip protocols. That means that when you are in 823 * file:///dir/dir2/my.tgz#tar:/ and you do cd("..") you will 824 * still be in file:///dir/dir2/my.tgz#tar:/ 825 * 826 * @param _dir the directory to change to 827 * @return true if successful 828 */ 829 bool cd(const QString &_dir); 830 831 /** 832 * Returns the URL as string, with all escape sequences intact, 833 * encoded in a given charset. 834 * This is used in particular for encoding URLs in UTF-8 before using them 835 * in a drag and drop operation. 836 * Please note that the string returned by url() will include 837 * the password of the URL. If you want to show the URL to the 838 * user, use prettyUrl(). 839 * 840 * @param trailing use to add or remove a trailing slash to/from the path. See adjustPath 841 * @return The complete URL, with all escape sequences intact, encoded 842 * in a given charset. 843 * @see prettyUrl() 844 * 845 * @deprecated since 5.0, use QUrl::toString() instead. 846 * In case of RemoveTrailingSlash, call adjusted(QUrl::StripTrailingSlash) first. 847 * AddTrailingSlash is not available directly, test if path ends with '/', and if not setPath(path() + '/'). 848 */ 849 QString url(AdjustPathOption trailing = LeaveTrailingSlash) const; 850 851 /** 852 * Returns the URL as string in human-friendly format. 853 * Example: 854 * \code 855 * http://localhost:8080/test.cgi?test=hello world&name=fred 856 * \endcode 857 * @param trailing use to add or remove a trailing slash to/from the path. see adjustPath. 858 * 859 * @return A human readable URL, with no non-necessary encodings/escaped 860 * characters. Password will not be shown. 861 * @see url() 862 * 863 * @deprecated since 5.0, use QUrl::toDisplayString() instead. 864 */ 865 QString prettyUrl(AdjustPathOption trailing = LeaveTrailingSlash) const; 866 867 /** 868 * Return the URL as a string, which will be either the URL (as prettyUrl 869 * would return) or, when the URL is a local file without query or ref, 870 * the path. 871 * Use this method, to display URLs to the user. 872 * You can give the result of pathOrUrl back to the KUrl constructor, it accepts 873 * both paths and urls. 874 * 875 * @return the new KUrl 876 * @param trailing use to add or remove a trailing slash to/from the path. see adjustPath. 877 * @since 4.2 878 * @deprecated since 5.0, use QUrl::toDisplayString(QUrl::PreferLocalFile | ...) instead. 879 */ 880 QString pathOrUrl(AdjustPathOption trailing = LeaveTrailingSlash) const; 881 882 /** 883 * Returns the URL as a string, using the standard conventions for mime data 884 * (drag-n-drop or copy-n-paste). 885 * Internally used by KUrl::List::fromMimeData, which is probably what you want to use instead. 886 * @deprecated since 5.0, use QMimeData::setUrls directly, or KUrlMimeData::setUrls 887 */ 888 QString toMimeDataString() const; 889 890 /** 891 * This function is useful to implement the "Up" button in a file manager for example. 892 * cd() never strips a sub-protocol. That means that if you are in 893 * file:///home/x.tgz#gzip:/#tar:/ and hit the up button you expect to see 894 * file:///home. The algorithm tries to go up on the right-most URL. If that is not 895 * possible it strips the right most URL. It continues stripping URLs. 896 * @return a URL that is a level higher 897 * @deprecated since 5.0, use KIO::upUrl() instead, from kio/global.h 898 */ 899 KUrl upUrl() const; 900 901 KUrl &operator=(const KUrl &_u); 902 903 // Define those, since the constructors are explicit 904 KUrl &operator=(const char *_url) 905 { 906 *this = KUrl(_url); 907 return *this; 908 } 909 KUrl &operator=(const QByteArray &_url) 910 { 911 *this = KUrl(_url); 912 return *this; 913 } 914 KUrl &operator=(const QString &_url) 915 { 916 *this = KUrl(_url); 917 return *this; 918 } 919 920 bool operator==(const KUrl &_u) const; 921 bool operator==(const QString &_u) const; 922 bool operator!=(const KUrl &_u) const 923 { 924 return !(*this == _u); 925 } 926 bool operator!=(const QString &_u) const 927 { 928 return !(*this == _u); 929 } 930 931 /** 932 * Converts this KUrl to a QVariant, this allows to use KUrl 933 * in QVariant() constructor 934 */ 935 operator QVariant() const; 936 937 /** 938 * The same as equals(), just with a less obvious name. 939 * Compares this url with @p u. 940 * @param u the URL to compare this one with. 941 * @param ignore_trailing set to true to ignore trailing '/' characters. 942 * @return True if both urls are the same. If at least one of the urls is invalid, 943 * false is returned. 944 * @see operator==. This function should be used if you want to 945 * ignore trailing '/' characters. 946 * @deprecated since 4.0, use equals() instead. 947 */ 948 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED 949 KDELIBS4SUPPORT_DEPRECATED bool cmp(const KUrl &u, bool ignore_trailing = false) const; 950 #endif 951 952 /** 953 * Flags to be used in URL comparison functions like equals, or urlcmp 954 */ 955 enum EqualsOption { 956 /** 957 * ignore trailing '/' characters. The paths "dir" and "dir/" are treated the same. 958 * Note however, that by default, the paths "" and "/" are not the same 959 * (For instance ftp://user@host redirects to ftp://user@host/home/user (on a linux server), 960 * while ftp://user@host/ is the root dir). 961 * This is also why path(RemoveTrailingSlash) for "/" returns "/" and not "". 962 * 963 * When dealing with web pages however, you should also set AllowEmptyPath so that 964 * no path and "/" are considered equal. 965 */ 966 CompareWithoutTrailingSlash = 0x01, 967 /** 968 * disables comparison of HTML-style references. 969 */ 970 CompareWithoutFragment = 0x02, 971 /** 972 * Treat a URL with no path as equal to a URL with a path of "/", 973 * when CompareWithoutTrailingSlash is set. 974 * Example: 975 * KUrl::urlcmp("http://www.kde.org", "http://www.kde.org/", KUrl::CompareWithoutTrailingSlash | KUrl::AllowEmptyPath) 976 * returns true. 977 * This option is ignored if CompareWithoutTrailingSlash isn't set. 978 * @since 4.5 979 */ 980 AllowEmptyPath = 0x04 981 }; 982 Q_DECLARE_FLAGS(EqualsOptions, EqualsOption) 983 984 /** 985 * Compares this url with @p u. 986 * @param u the URL to compare this one with. 987 * @param options a set of EqualsOption flags 988 * @return True if both urls are the same. If at least one of the urls is invalid, 989 * false is returned. 990 * @see operator==. This function should be used if you want to 991 * set additional options, like ignoring trailing '/' characters. 992 * @deprecated since 5.0, use matches(u, formattingOptions) 993 * equals(u, KUrl::CompareWithoutTrailingSlash) becomes matches(u, QUrl::StripTrailingSlash) 994 * equals(u, KUrl::CompareWithoutFragment) becomes matches(u, QUrl::RemoveFragment) 995 * equals(u, KUrl::CompareWithoutTrailingSlash|KUrl::AllowEmptyPath) needs manual handling 996 * (it was mostly unused). 997 */ 998 bool equals(const KUrl &u, const EqualsOptions &options = {}) const; 999 1000 /** 1001 * Checks whether the given URL is parent of this URL. 1002 * For instance, ftp://host/dir/ is a parent of ftp://host/dir/subdir/subsubdir/. 1003 * @return true if this url is a parent of @p u (or the same URL as @p u) 1004 * @deprecated since 5.0. url.isParentOf(child) is now 1005 * url.isParentOf(child) || url.matches(child, QUrl::StripTrailingSlash); 1006 */ 1007 bool isParentOf(const KUrl &child) const; 1008 1009 /** 1010 * Splits nested URLs like file:///home/weis/kde.tgz#gzip:/#tar:/kdebase 1011 * A URL like http://www.kde.org#tar:/kde/README.hml#ref1 will be split in 1012 * http://www.kde.org and tar:/kde/README.html#ref1. 1013 * That means in turn that "#ref1" is an HTML-style reference and not a new sub URL. 1014 * Since HTML-style references mark 1015 * a certain position in a document this reference is appended to every URL. 1016 * The idea behind this is that browsers, for example, only look at the first URL while 1017 * the rest is not of interest to them. 1018 * 1019 * 1020 * @param _url The URL that has to be split. 1021 * @return An empty list on error or the list of split URLs. 1022 * @see hasSubUrl 1023 */ 1024 static List split(const QString &_url); 1025 1026 /** 1027 * Splits nested URLs like file:///home/weis/kde.tgz#gzip:/#tar:/kdebase 1028 * A URL like http://www.kde.org#tar:/kde/README.hml#ref1 will be split in 1029 * http://www.kde.org and tar:/kde/README.html#ref1. 1030 * That means in turn that "#ref1" is an HTML-style reference and not a new sub URL. 1031 * Since HTML-style references mark 1032 * a certain position in a document this reference is appended to every URL. 1033 * The idea behind this is that browsers, for example, only look at the first URL while 1034 * the rest is not of interest to them. 1035 * 1036 * @return An empty list on error or the list of split URLs. 1037 * 1038 * @param _url The URL that has to be split. 1039 * @see hasSubUrl 1040 */ 1041 static List split(const KUrl &_url); 1042 1043 /** 1044 * Reverses split(). Only the first URL may have a reference. This reference 1045 * is considered to be HTML-like and is appended at the end of the resulting 1046 * joined URL. 1047 * @param _list the list to join 1048 * @return the joined URL 1049 */ 1050 static KUrl join(const List &_list); 1051 1052 /** 1053 * Creates a KUrl object from a QString representing an absolute local path. 1054 * KUrl url( somePath ) is almost the same, but this method is more explicit, 1055 * avoids the path-or-url detection in the KUrl constructor, and parses 1056 * "abc:def" as a filename, not as URL. 1057 * 1058 * @param text the local path 1059 * @return the new KUrl 1060 * 1061 * @deprecated since 5.0, use QUrl::fromLocalFile 1062 */ 1063 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED fromPath(const QString & text)1064 static KDELIBS4SUPPORT_DEPRECATED KUrl fromPath(const QString &text) 1065 { 1066 return fromLocalFile(text); 1067 } 1068 #endif 1069 1070 /** 1071 * @deprecated since 4.0, use QUrl() instead 1072 */ 1073 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED 1074 static KDELIBS4SUPPORT_DEPRECATED KUrl fromPathOrUrl(const QString &text); 1075 #endif 1076 1077 /** 1078 * Adds URL data into the given QMimeData. 1079 * 1080 * By default, populateMimeData also exports the URL as plain text, for e.g. dropping 1081 * onto a text editor. 1082 * But in some cases this might not be wanted, e.g. if adding other mime data 1083 * which provides better plain text data. 1084 * 1085 * WARNING: do not call this method multiple times, use KUrl::List::populateMimeData instead. 1086 * 1087 * @param mimeData the QMimeData instance used to drag or copy this URL 1088 * @param metaData KIO metadata shipped in the mime data, which is used for instance to 1089 * set a correct HTTP referrer (some websites require it for downloading e.g. an image) 1090 * @param flags set NoTextExport to prevent setting plain/text data into @p mimeData 1091 * 1092 * @deprecated since 5.0, use QMimeData::setUrls(QList<QUrl>() << url), 1093 * followed by KUrlMimeData::setMetaData if you have metadata. 1094 */ 1095 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED 1096 KDELIBS4SUPPORT_DEPRECATED void populateMimeData(QMimeData *mimeData, 1097 const MetaDataMap &metaData = MetaDataMap(), 1098 MimeDataFlags flags = DefaultMimeDataFlags) const; 1099 #endif 1100 1101 /** 1102 * Convenience function. 1103 * 1104 * Returns whether '_url' is likely to be a "relative" URL instead of 1105 * an "absolute" URL. 1106 * 1107 * This is mostly meant for KUrl(url, relativeUrl). 1108 * 1109 * If you are looking for the notion of "relative path" (foo) vs "absolute path" (/foo), 1110 * use QUrl::isRelative() instead. 1111 * Indeed, isRelativeUrl() returns true for the string "/foo" since it doesn't contain a protocol, 1112 * while KUrl("/foo").isRelative() is false since the KUrl constructor turns it into file:///foo. 1113 * The two methods basically test the same thing, but this one takes a string (which is faster) 1114 * while the class method requires a QUrl/KUrl which gives a more expected result, given 1115 * the "magic" in the KUrl constructor. 1116 * 1117 * @param _url URL to examine 1118 * @return true when the URL is likely to be "relative", false otherwise. 1119 * @deprecated since 5.0, use QUrl(_url)::isRelative instead 1120 */ 1121 static bool isRelativeUrl(const QString &_url); 1122 1123 /** 1124 * Convenience function 1125 * 1126 * Returns a "relative URL" based on @p base_url that points to @p url. 1127 * 1128 * If no "relative URL" can be created, e.g. because the protocol 1129 * and/or hostname differ between @p base_url and @p url an absolute 1130 * URL is returned. 1131 * Note that if @p base_url represents a directory, it should contain 1132 * a trailing slash. 1133 * @param base_url the URL to derive from 1134 * @param url new URL 1135 * @see adjustPath() 1136 * @deprecated since 5.0, check that the URLs have the same scheme+host+port+user+pass, 1137 * then make the path relative with QDir(base_url.path()).relativeFilePath(url.path()) 1138 */ 1139 static QString relativeUrl(const KUrl &base_url, const KUrl &url); 1140 1141 /** 1142 * Convenience function 1143 * 1144 * Returns a relative path based on @p base_dir that points to @p path. 1145 * @param base_dir the base directory to derive from 1146 * @param path the new target directory 1147 * @param isParent A pointer to a boolean which, if provided, will be set to reflect 1148 * whether @p path has @p base_dir is a parent dir. 1149 * @deprecated since 5.0, use QDir(base_dir).relativeFilePath(path). isParent can be 1150 * replaced with a call to startsWith("..") on the result value. 1151 */ 1152 static QString relativePath(const QString &base_dir, const QString &path, bool *isParent = nullptr); 1153 1154 private: 1155 void _setQuery(const QString &query); 1156 void _setEncodedUrl(const QByteArray &url); 1157 operator QString() const; // forbidden, use url(), prettyUrl(), or pathOrUrl() instead. 1158 }; 1159 1160 Q_DECLARE_OPERATORS_FOR_FLAGS(KUrl::EncodedPathAndQueryOptions) 1161 Q_DECLARE_OPERATORS_FOR_FLAGS(KUrl::CleanPathOptions) 1162 Q_DECLARE_OPERATORS_FOR_FLAGS(KUrl::QueryItemsOptions) 1163 Q_DECLARE_OPERATORS_FOR_FLAGS(KUrl::EqualsOptions) 1164 Q_DECLARE_OPERATORS_FOR_FLAGS(KUrl::DirectoryOptions) 1165 1166 Q_DECLARE_METATYPE(KUrl) 1167 Q_DECLARE_METATYPE(KUrl::List) 1168 1169 /** 1170 * \relates KUrl 1171 * Compares URLs. They are parsed, split and compared. 1172 * Two malformed URLs with the same string representation 1173 * are nevertheless considered to be unequal. 1174 * That means no malformed URL equals anything else. 1175 * @deprecated since 4.5, use QUrl(_url1) == QUrl(_url2) instead. 1176 */ 1177 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED 1178 KDELIBS4SUPPORT_DEPRECATED_EXPORT bool urlcmp(const QString &_url1, const QString &_url2); // KDE5: remove, KUrl::equals is better API 1179 #endif 1180 1181 /** 1182 * \relates KUrl 1183 * Compares URLs. They are parsed, split and compared. 1184 * Two malformed URLs with the same string representation 1185 * are nevertheless considered to be unequal. 1186 * That means no malformed URL equals anything else. 1187 * 1188 * @param _url1 A reference URL 1189 * @param _url2 A URL that will be compared with the reference URL 1190 * @param options a set of KUrl::EqualsOption flags 1191 * @deprecated since 4.5, use QUrl(_url1).adjusted(options) == QUrl(_url2).adjusted(options) instead. 1192 */ 1193 #ifndef KDELIBS4SUPPORT_NO_DEPRECATED 1194 KDELIBS4SUPPORT_DEPRECATED_EXPORT bool urlcmp(const QString &_url1, const QString &_url2, const KUrl::EqualsOptions &options); // KDE5: remove, KUrl::equals is better API 1195 #endif 1196 1197 #endif 1198