Warning: That file was not part of the compilation database. It may have many parsing errors.

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

Warning: That file was not part of the compilation database. It may have many parsing errors.