summaryrefslogtreecommitdiffabout
path: root/microkde/kurl.h
Unidiff
Diffstat (limited to 'microkde/kurl.h') (more/less context) (ignore whitespace changes)
-rw-r--r--microkde/kurl.h853
1 files changed, 853 insertions, 0 deletions
diff --git a/microkde/kurl.h b/microkde/kurl.h
new file mode 100644
index 0000000..cd65a1c
--- a/dev/null
+++ b/microkde/kurl.h
@@ -0,0 +1,853 @@
1/* This file is part of the KDE libraries
2 * Copyright (C) 1999 Torben Weis <weis@kde.org>
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
8 *
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 *
14 * You should have received a copy of the GNU Library General Public License
15 * along with this library; see the file COPYING.LIB. If not, write to
16 * the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
18 **/
19
20#ifndef __kurl_h__
21#define __kurl_h__ "$Id$"
22
23#include <qstring.h>
24#include <qvaluelist.h>
25
26class QUrl;
27class QStringList;
28template <typename K, typename V> class QMap;
29
30class KURLPrivate;
31/**
32 * Represents and parses a URL.
33 *
34 * A prototypical URL looks like:
35 * <pre>
36 * protocol:/user:password\@hostname:port/path/to/file.ext#reference
37 * </pre>
38 *
39 * KURL has some restrictions regarding the path
40 * encoding. KURL works internally with the decoded path and
41 * and encoded query. For example,
42 * <pre>
43 * http://localhost/cgi-bin/test%20me.pl?cmd=Hello%20you
44 * </pre>
45 * would result in a decoded path "/cgi-bin/test me.pl"
46 * and in the encoded query "?cmd=Hello%20you".
47 * Since path is internally always encoded you may @em not use
48 * "%00" in the path, although this is OK for the query.
49 *
50 * @author Torben Weis <weis@kde.org>
51 */
52class KURL
53{
54public:
55 enum AdjustementFlags
56 {
57 NoAdjustements = 0,
58 StripFileProtocol = 1
59 };
60
61 /**
62 * KURL::List is a QValueList that contains KURLs with a few
63 * convenience methods.
64 * @see KURL
65 * @see QValueList
66 */
67 class List : public QValueList<KURL>
68 {
69 public:
70 /**
71 * Creates an empty List.
72 */
73 List() { }
74 /**
75 * Creates a list that contains the given URL as only
76 * item.
77 * @param url the url to add.
78 */
79 List(const KURL &url);
80 /**
81 * Creates a list that contains the URLs from the given
82 * list.
83 * @param list the list containing the URLs as strings
84 */
85 List(const QStringList &list);
86 /**
87 * Converts the URLs of this list to a list of strings.
88 * @return the list of strings
89 */
90 QStringList toStringList() const;
91 };
92 /**
93 * Constructs an empty URL.
94 */
95 KURL();
96
97 /**
98 * Destructs the KURL object.
99 */
100 ~KURL();
101
102 /**
103 * Usual constructor, to construct from a string.
104 * @param url A URL, not a filename. If the URL does not have a protocol
105 * part, "file:" is assumed.
106 * It is dangerous to feed unix filenames into this function,
107 * this will work most of the time but not always.
108 * For example "/home/Torben%20Weis" will be considered a URL
109 * pointing to the file "/home/Torben Weis" instead of to the
110 * file "/home/Torben%20Weis".
111 * This means that if you have a usual UNIX like path you
112 * should not use this constructor.
113 * Instead create an empty url and set the path by using
114 * @ref setPath().
115 * @param encoding_hint MIB of original encoding of URL.
116 * @see QTextCodec::mibEnum()
117 */
118 KURL( const QString& url, int encoding_hint = 0 );
119 /**
120 * Constructor taking a char * @p url, which is an _encoded_ representation
121 * of the URL, exactly like the usual constructor. This is useful when
122 * then URL, in its encoded form, is strictly ascii.
123 * @param url A encoded URL. If the URL does not have a protocol part,
124 * "file:" is assumed.
125 * @param encoding_hint MIB of original encoding of URL.
126 * @see QTextCodec::mibEnum()
127 */
128 KURL( const char * url, int encoding_hint = 0 );
129 /**
130 * Constructor taking a QCString @p url, which is an _encoded_ representation
131 * of the URL, exactly like the usual constructor. This is useful when
132 * then URL, in its encoded form, is strictly ascii.
133 * @param url A encoded URL. If the URL does not have a protocol part,
134 * "file:" is assumed.
135 * @param encoding_hint MIB of original encoding of URL.
136 * @see QTextCodec::mibEnum()
137 */
138 KURL( const QCString& url, int encoding_hint = 0 );
139 /**
140 * Copy constructor.
141 * @param u the KURL to copy
142 */
143 KURL( const KURL& u );
144 /**
145 * Converts from a @ref QUrl.
146 * @param u the QUrl
147 */
148 KURL( const QUrl &u );
149 /**
150 * Constructor allowing relative URLs.
151 *
152 * @param _baseurl The base url.
153 * @param _rel_url A relative or absolute URL.
154 * If this is an absolute URL then @p _baseurl will be ignored.
155 * If this is a relative URL it will be combined with @p _baseurl.
156 * Note that _rel_url should be encoded too, in any case.
157 * So do NOT pass a path here (use setPath or addPath instead).
158 * @param encoding_hint MIB of original encoding of URL.
159 * @see QTextCodec::mibEnum()
160 */
161 KURL( const KURL& _baseurl, const QString& _rel_url, int encoding_hint=0 );
162
163 /**
164 * Returns the protocol for the URL (i.e., file, http, etc.).
165 * @return the protocol of the URL, does not include the colon. If the
166 * URL is malformed, QString::null will be returned.
167 **/
168 QString protocol() const { return m_bIsMalformed ? QString::null : m_strProtocol; }
169 /**
170 * Sets the protocol for the URL (i.e., file, http, etc.)
171 * @param _txt the new protocol of the URL (without colon)
172 **/
173 void setProtocol( const QString& _txt );
174
175 /**
176 * Returns the decoded user name (login, user id, ...) included in the URL.
177 * @return the user name or QString::null if there is no user name
178 **/
179 QString user() const { return m_strUser; }
180 /**
181 * Sets the user name (login, user id, ...) included in the URL.
182 *
183 * Special characters in the user name will appear encoded in the URL.
184 * @param _txt the name of the user or QString::null to remove the user
185 **/
186 void setUser( const QString& _txt );
187 /**
188 * Test to see if this URL has a user name included in it.
189 * @return true if the URL has an non-empty user name
190 **/
191 bool hasUser() const { return !m_strUser.isEmpty(); }
192
193 /**
194 * Returns the decoded password (corresponding to \ref user()) included in the URL.
195 * @return the password or QString::null if it does not exist
196 **/
197 QString pass() const { return m_strPass; }
198 /**
199 * Sets the password (corresponding to @ref user()) included in the URL.
200 *
201 * Special characters in the password will appear encoded in the URL.
202 * Note that a password can only appear in a URL string if you also set
203 * a user.
204 * @param _txt the password to set or QString::null to remove the password
205 * @see #setUser
206 * @see #hasUser
207 **/
208 void setPass( const QString& _txt );
209 /**
210 * Test to see if this URL has a password included in it.
211 * @return true if there is a non-empty password set
212 **/
213 bool hasPass() const { return !m_strPass.isEmpty(); }
214
215 /**
216 * Returns the decoded hostname included in the URL.
217 * @return the name of the host or QString::null if no host is set
218 **/
219 QString host() const { return m_strHost; }
220
221 /**
222 * Sets the hostname included in the URL.
223 *
224 * Special characters in the hostname will appear encoded in the URL.
225 * @param _txt the new name of the host or QString::null to remove the host
226 **/
227 void setHost( const QString& _txt );
228 /**
229 * Test to see if this URL has a hostname included in it.
230 * @return true if the URL has a host
231 **/
232 bool hasHost() const { return !m_strHost.isEmpty(); }
233
234 /**
235 * Returns the port number included in the URL.
236 * @return the port number. If there is no port number specified in the
237 * URL, returns 0.
238 **/
239 unsigned short int port() const { return m_iPort; }
240 /**
241 * Sets the port number included in the URL.
242 * @param _p the new port number or 0 to have no port number
243 **/
244 void setPort( unsigned short int _p );
245
246 /**
247 * Returns the current decoded path. This does @em not include the query.
248 * @return the path of the URL (without query), or QString::null if no
249 * path set.
250 */
251 QString path() const { return m_strPath; }
252
253 /**
254 * @param _trailing May be ( -1, 0 +1 ). -1 strips a trailing '/', +1 adds
255 * a trailing '/' if there is none yet and 0 returns the
256 * path unchanged. If the URL has no path, then no '/' is added
257 * anyway. And on the other side: If the path is "/", then this
258 * character won't be stripped. Reason: "ftp://weis\@host" means something
259 * completely different than "ftp://weis\@host/". So adding or stripping
260 * the '/' would really alter the URL, while "ftp://host/path" and
261 * "ftp://host/path/" mean the same directory.
262 *
263 * @return The current decoded path. This does not include the query. Can
264 * be QString::null if no path is set.
265 */
266 QString path( int _trailing ) const;
267
268 /**
269 * Sets the path of the URL. The query is not changed by this function.
270 *
271 * @param path The new path. This is considered to be decoded. This
272 * means: %3f does not become decoded
273 * and the ? does not indicate the start of the query part.
274 * Can be QString::null to delete the path.
275 */
276 void setPath( const QString& path );
277
278 /**
279 * Test to see if this URL has a path is included in it.
280 * @return true if there is a path
281 **/
282 bool hasPath() const { return !m_strPath.isEmpty(); }
283
284 /**
285 * Resolves "." and ".." components in path.
286 * Some servers seem not to like the removal of extra '/'
287 * even though it is against the specification in RFC 2396.
288 *
289 * @param cleanDirSeparator if true, occurrances of consecutive
290 * directory separators (e.g. /foo//bar) are cleaned up as well.
291 */
292 void cleanPath(bool cleanDirSeparator = true);
293
294 /**
295 * Add or remove a trailing slash to/from the path.
296 * @param _trailing May be ( -1, 0 +1 ). -1 strips a trailing '/', +1 adds
297 * a trailing '/' if there is none yet and 0 returns the
298 * path unchanged. If the URL has no path, then no '/' is added
299 * anyway. And on the other side: If the path is "/", then this
300 * character won't be stripped. Reason: "ftp://weis\@host" means something
301 * completely different than "ftp://weis\@host/". So adding or stripping
302 * the '/' would really alter the URL, while "ftp://host/path" and
303 * "ftp://host/path/" mean the same directory.
304 */
305 void adjustPath(int _trailing);
306
307 /**
308 * This is useful for HTTP. It looks first for '?' and decodes then.
309 * The encoded path is the concatenation of the current path and the query.
310 * @param _txt the new path and query.
311 * @param encoding_hint MIB of original encoding of @p _txt .
312 * @see QTextCodec::mibEnum()
313 */
314 void setEncodedPathAndQuery( const QString& _txt, int encoding_hint = 0 );
315
316 /**
317 * Sets the (already encoded) path
318 * @param _txt the new path
319 * @param encoding_hint MIB of original encoding of @p _txt .
320 * @see QTextCodec::mibEnum()
321 */
322 void setEncodedPath(const QString& _txt, int encoding_hint = 0 );
323
324 /**
325 * Returns the encoded path and the query.
326 *
327 * @param _trailing May be ( -1, 0 +1 ). -1 strips a trailing '/', +1 adds
328 * a trailing '/' if there is none yet and 0 returns the
329 * path unchanged. If the URL has no path, then no '/' is added
330 * anyway. And on the other side: If the path is "/", then this
331 * character won't be stripped. Reason: "ftp://weis\@host" means something
332 * completely different than "ftp://weis\@host/". So adding or stripping
333 * the '/' would really alter the URL, while "ftp://host/path" and
334 * "ftp://host/path/" mean the same directory.
335 * @param _no_empty_path If set to true then an empty path is substituted by "/".
336 * @param encoding_hint MIB of desired encoding of URL.
337 * @see QTextCodec::mibEnum()
338 * @return The concatenation if the encoded path , '?' and the encoded query.
339 *
340 */
341 QString encodedPathAndQuery( int _trailing = 0, bool _no_empty_path = false, int encoding_hint = 0) const;
342
343 /**
344 * @param _txt This is considered to be encoded. This has a good reason:
345 * The query may contain the 0 character.
346 *
347 * The query should start with a '?'. If it doesn't '?' is prepended.
348 * @param encoding_hint Reserved, should be 0.
349 * @see QTextCodec::mibEnum()
350 */
351 void setQuery( const QString& _txt, int encoding_hint = 0);
352
353 /**
354 * Returns the query of the URL.
355 * The query may contain the 0 character.
356 * If a query is present it always starts with a '?'.
357 * A single '?' means an empty query.
358 * An empty string means no query.
359 * @return The encoded query, or QString::null if there is none.
360 */
361 QString query() const;
362
363 /**
364 * The reference is @em never decoded automatically.
365 * @return the undecoded reference, or QString::null if there is none
366 */
367 QString ref() const { return m_strRef_encoded; }
368
369 /**
370 * Sets the reference part (everything after '#').
371 * @param _txt The encoded reference (or QString::null to remove it).
372 */
373 void setRef( const QString& _txt ) { m_strRef_encoded = _txt; }
374
375 /**
376 * Checks whether the URL has a reference part.
377 * @return true if the URL has a reference part. In a URL like
378 * http://www.kde.org/kdebase.tar#tar:/README it would
379 * return true, too.
380 */
381 bool hasRef() const { return !m_strRef_encoded.isNull(); }
382
383 /**
384 * Returns the HTML reference (the part of the URL after "#").
385 * @return The HTML-style reference.
386 * @see #split
387 * @see #hasSubURL
388 * @see #encodedHtmlRef
389 */
390 QString htmlRef() const;
391
392 /**
393 * Returns the HTML reference (the part of the URL after "#") in
394 * encoded form.
395 * @return The HTML-style reference in its original form.
396 */
397 QString encodedHtmlRef() const;
398
399 /**
400 * Sets the HTML-style reference.
401 *
402 * @param _ref The new reference. This is considered to be @em not encoded in
403 * contrast to @ref setRef(). Use QString::null to remove it.
404 * @see htmlRef()
405 */
406 void setHTMLRef( const QString& _ref );
407
408 /**
409 * Checks whether there is a HTML reference.
410 * @return true if the URL has an HTML-style reference.
411 * @see htmlRef()
412 */
413 bool hasHTMLRef() const;
414
415 /**
416 * Checks whether the URL is well formed.
417 * @return false if the URL is malformed. This function does @em not test
418 * whether sub URLs are well-formed, too.
419 */
420 bool isValid() const { return !m_bIsMalformed; }
421 /**
422 * @deprecated
423 */
424 bool isMalformed() const { return !isValid(); }
425
426 /**
427 * Checks whether the file is local.
428 * @return true if the file is a plain local file and has no filter protocols
429 * attached to it.
430 */
431 bool isLocalFile() const;
432
433 /**
434 * Adds encoding information to url by adding a "charset" parameter. If there
435 * is already a charset parameter, it will be replaced.
436 * @param encoding the encoding to add or QString::null to remove the
437 * encoding.
438 */
439 void setFileEncoding(const QString &encoding);
440
441 /**
442 * Returns encoding information from url, the content of the "charset"
443 * parameter.
444 * @return An encoding suitable for QTextCodec::codecForName()
445 * or QString::null if not encoding was specified.
446 */
447 QString fileEncoding() const;
448
449 /**
450 * Checks whether the URL has any sub URLs. See @ref #split()
451 * for examples for sub URLs.
452 * @return true if the file has at least one sub URL.
453 * @see #split
454 */
455 bool hasSubURL() const;
456
457 /**
458 * Adds to the current path.
459 * Assumes that the current path is a directory. @p _txt is appended to the
460 * current path. The function adds '/' if needed while concatenating.
461 * This means it does not matter whether the current path has a trailing
462 * '/' or not. If there is none, it becomes appended. If @p _txt
463 * has a leading '/' then this one is stripped.
464 *
465 * @param _txt The text to add. It is considered to be decoded.
466 */
467 void addPath( const QString& _txt );
468
469 /**
470 * Returns the value of a certain query item.
471 *
472 * @param _item Item whose value we want
473 * @param encoding_hint MIB of encoding of query.
474 *
475 * @return the value of the given query item name or QString::null if the
476 * specified item does not exist.
477 */
478/*US we do not need this functions
479 QString queryItem( const QString& _item ) const;
480 QString queryItem( const QString& _item, int encoding_hint ) const;
481*/
482 /**
483 * Options for @ref #queryItems. Currently, only one option is
484 * defined:
485 *
486 * @param CaseInsensitiveKeys normalize query keys to lowercase.
487 *
488 * @since 3.1
489 **/
490 enum QueryItemsOptions { CaseInsensitiveKeys = 1 };
491
492 /**
493 * Returns the list of query items as a map mapping keys to values.
494 *
495 * @param options any of @ref QueryItemsOptions <em>or</or>ed together.
496 * @param encoding_hint MIB of encoding of query.
497 *
498 * @return the map of query items or the empty map if the url has no
499 * query items.
500 *
501 * @since 3.1
502 */
503 QMap< QString, QString > queryItems( int options=0 ) const;
504 QMap< QString, QString > queryItems( int options, int encoding_hint ) const;
505
506 /**
507 * Add an additional query item.
508 * To replace an existing query item, the item should first be
509 * removed with @ref removeQueryItem()
510 *
511 * @param _item Name of item to add
512 * @param _value Value of item to add
513 * @param encoding_hint MIB of encoding to use for _value.
514 * @see QTextCodec::mibEnum()
515 */
516 void addQueryItem( const QString& _item, const QString& _value, int encoding_hint = 0 );
517
518 /**
519 * Remove an item from the query.
520 *
521 * @param _item Item to be removed
522 */
523 void removeQueryItem( const QString& _item );
524
525 /**
526 * Sets the filename of the path.
527 * In comparison to @ref addPath() this function does not assume that the current
528 * path is a directory. This is only assumed if the current path ends with '/'.
529 *
530 * Any reference is reset.
531 *
532 * @param _txt The filename to be set. It is considered to be decoded. If the
533 * current path ends with '/' then @p _txt int just appended, otherwise
534 * all text behind the last '/' in the current path is erased and
535 * @p _txt is appended then. It does not matter whether @p _txt starts
536 * with '/' or not.
537 */
538 void setFileName( const QString&_txt );
539
540 /**
541 * Returns the filename of the path.
542 * @param _ignore_trailing_slash_in_path This tells whether a trailing '/' should
543 * be ignored. This means that the function would return "torben" for
544 * <tt>file:/hallo/torben/</tt> and <tt>file:/hallo/torben</tt>.
545 * If the flag is set to false, then everything behind the last '/'
546 * is considered to be the filename.
547 * @return The filename of the current path. The returned string is decoded. Null
548 * if there is no file (and thus no path).
549 */
550 QString fileName( bool _ignore_trailing_slash_in_path = true ) const;
551
552 /**
553 * Returns the directory of the path.
554 * @param _strip_trailing_slash_from_result tells whether the returned result should end with '/' or not.
555 * If the path is empty or just "/" then this flag has no effect.
556 * @param _ignore_trailing_slash_in_path means that <tt>file:/hallo/torben</tt> and
557 * <tt>file:/hallo/torben/"</tt> would both return <tt>/hallo/</tt>
558 * or <tt>/hallo</tt> depending on the other flag
559 * @return The directory part of the current path. Everything between the last and the second last '/'
560 * is returned. For example <tt>file:/hallo/torben/</tt> would return "/hallo/torben/" while
561 * <tt>file:/hallo/torben</tt> would return "hallo/". The returned string is decoded. QString::null is returned when there is no path.
562 */
563 QString directory( bool _strip_trailing_slash_from_result = true,
564 bool _ignore_trailing_slash_in_path = true ) const;
565
566 /**
567 * Set the directory to @p dir, leaving the filename empty.
568 */
569 void setDirectory(const QString &dir);
570
571 /**
572 * Changes the directory by descending into the given directory.
573 * It is assumed the current URL represents a directory.
574 * If @p dir starts with a "/" the
575 * current URL will be "protocol://host/dir" otherwise @p _dir will
576 * be appended to the path. @p _dir can be ".."
577 * This function won't strip protocols. That means that when you are in
578 * file:/dir/dir2/my.tgz#tar:/ and you do cd("..") you will
579 * still be in file:/dir/dir2/my.tgz#tar:/
580 *
581 * @param _dir the directory to change to
582 * @return true if successful
583 */
584 bool cd( const QString& _dir );
585
586 /**
587 * Returns the URL as string, with all escape sequences intact,
588 * encoded in a given charset.
589 * This is used in particular for encoding URLs in UTF-8 before using them
590 * in a drag and drop operation.
591 * Please note that the string returned by @ref url() will include
592 * the password of the URL. If you want to show the URL to the
593 * user, use @ref prettyURL().
594 *
595 * @param _trailing This may be ( -1, 0 +1 ). -1 strips a trailing '/' from the path, +1 adds
596 * a trailing '/' if there is none yet and 0 returns the
597 * path unchanged.
598 * @param encoding_hint MIB of encoding to use.
599 * @return The complete URL, with all escape sequences intact, encoded
600 * in a given charset.
601 * @see QTextCodec::mibEnum()
602 * @see prettyURL()
603 */
604 QString url( int _trailing = 0, int encoding_hint = 0) const;
605
606 /**
607 * Returns the URL as string in human-friendly format.
608 * Example:
609 * <pre>
610 * http://localhost:8080/test.cgi?test=hello world&name=fred
611 * </pre>
612 * @param _trailing -1 to strip a trailing '/' from the path, +1 adds
613 * a trailing '/' if there is none yet and 0 returns the
614 * path unchanged.
615 * @return A human readable URL, with no non-necessary encodings/escaped
616 * characters. Password will not be shown.
617 * @see url()
618 */
619 QString prettyURL( int _trailing = 0) const;
620
621
622 /**
623 * Returns the URL as string, escaped for HTML.
624 * @return A human readable URL, with no non-necessary encodings/escaped
625 * characters which is html encoded for safe inclusion in html or
626 * rich text. Password will not be shown.
627 */
628 QString htmlURL() const;
629
630 /**
631 * Returns the URL as string, escaped for HTML.
632 * Example:
633 * <pre>
634 * http://localhost:8080/test.cgi?test=hello world&name=fred
635 * </pre>
636 * @return A human readable URL, with no non-necessary encodings/escaped
637 * characters. Password will not be shown.
638 */
639 QString prettyURL( int _trailing, AdjustementFlags _flags) const;
640 // ### BIC: Merge the two above
641
642 /**
643 * Test to see if the KURL is empty.
644 * @return true if the URL is empty
645 **/
646 bool isEmpty() const;
647
648 /**
649 * This function is useful to implement the "Up" button in a file manager for example.
650 * @ref cd() never strips a sub-protocol. That means that if you are in
651 * file:/home/x.tgz#gzip:/#tar:/ and hit the up button you expect to see
652 * file:/home. The algorithm tries to go up on the right-most URL. If that is not
653 * possible it strips the right most URL. It continues stripping URLs.
654 * @return a URL that is a level higher
655 */
656 KURL upURL( ) const;
657
658 KURL& operator=( const KURL& _u );
659 KURL& operator=( const QString& _url );
660 KURL& operator=( const char * _url );
661 KURL& operator=( const QUrl & u );
662
663 bool operator==( const KURL& _u ) const;
664 bool operator==( const QString& _u ) const;
665 bool operator!=( const KURL& _u ) const { return !( *this == _u ); }
666 bool operator!=( const QString& _u ) const { return !( *this == _u ); }
667
668 /**
669 * The same as equals(), just with a less obvious name.
670 * Compares this url with @p u.
671 * @param ignore_trailing set to true to ignore trailing '/' characters.
672 * @return true if both urls are the same
673 * @see operator==. This function should be used if you want to
674 * ignore trailing '/' characters.
675 * @deprecated
676 */
677 bool cmp( const KURL &u, bool ignore_trailing = false ) const;
678
679 /**
680 * Compares this url with @p u.
681 * @param ignore_trailing set to true to ignore trailing '/' characters.
682 * @return true if both urls are the same
683 * @see operator==. This function should be used if you want to
684 * ignore trailing '/' characters.
685 * @since 3.1
686 */
687 bool equals( const KURL &u, bool ignore_trailing = false ) const;
688
689 /**
690 * Checks whether the given URL is parent of this URL.
691 * For instance, ftp://host/dir/ is a parent of ftp://host/dir/subdir/subsubdir/.
692 * @return true if this url is a parent of @p u (or the same URL as @p u)
693 */
694 bool isParentOf( const KURL& u ) const;
695
696 /**
697 * Splits nested URLs like file:/home/weis/kde.tgz#gzip:/#tar:/kdebase
698 * A URL like http://www.kde.org#tar:/kde/README.hml#ref1 will be split in
699 * http://www.kde.org and tar:/kde/README.html#ref1.
700 * That means in turn that "#ref1" is an HTML-style reference and not a new sub URL.
701 * Since HTML-style references mark
702 * a certain position in a document this reference is appended to every URL.
703 * The idea behind this is that browsers, for example, only look at the first URL while
704 * the rest is not of interest to them.
705 *
706 *
707 * @param _url The URL that has to be split.
708 * @return An empty list on error or the list of split URLs.
709 * @see #hasSubURL
710 */
711 static List split( const QString& _url );
712
713 /**
714 * Splits nested URLs like file:/home/weis/kde.tgz#gzip:/#tar:/kdebase
715 * A URL like http://www.kde.org#tar:/kde/README.hml#ref1 will be split in
716 * http://www.kde.org and tar:/kde/README.html#ref1.
717 * That means in turn that "#ref1" is an HTML-style reference and not a new sub URL.
718 * Since HTML-style references mark
719 * a certain position in a document this reference is appended to every URL.
720 * The idea behind this is that browsers, for example, only look at the first URL while
721 * the rest is not of interest to them.
722 *
723 * @return An empty list on error or the list of split URLs.
724 *
725 * @param _url The URL that has to be split.
726 * @see #hasSubURL
727 */
728 static List split( const KURL& _url );
729
730 /**
731 * Reverses @ref #split(). Only the first URL may have a reference. This reference
732 * is considered to be HTML-like and is appended at the end of the resulting
733 * joined URL.
734 * @param _list the list to join
735 * @return the joined URL
736 */
737 static KURL join( const List& _list );
738
739 /**
740 * Creates a KURL object from a QString representing either an absolute path
741 * or a real URL. Use this method instead of
742 * <pre>
743 * QString someDir = ...
744 * KURL url = someDir;
745 * </pre>
746 *
747 * Otherwise some characters (e.g. the '#') won't be encoded properly.
748 * @param text the string representation of the URL to convert
749 * @return the new KURL
750 * @since 3.1
751 */
752 static KURL fromPathOrURL( const QString& text );
753
754/**
755 * Convenience function.
756 *
757 * Convert unicoded string to local encoding and use %-style
758 * encoding for all common delimiters / non-ascii characters.
759 * @param str String to encode (can be QString::null).
760 * @param encoding_hint MIB of encoding to use.
761 * @see QTextCodec::mibEnum()
762 * @return the encoded string
763 **/
764 static QString encode_string(const QString &str, int encoding_hint = 0);
765
766 /**
767 * Convenience function.
768 *
769 * Convert unicoded string to local encoding and use %-style
770 * encoding for all common delimiters / non-ascii characters
771 * as well as the slash '/'.
772 * @param str String to encode
773 * @param encoding_hint MIB of encoding to use.
774 * @see QTextCodec::mibEnum()
775 **/
776 static QString encode_string_no_slash(const QString &str, int encoding_hint = 0);
777
778 /**
779 * Convenience function.
780 *
781 * Decode %-style encoding and convert from local encoding to unicode.
782 *
783 * Reverse of encode_string()
784 * @param str String to decode (can be QString::null).
785 * @param encoding_hint MIB of original encoding of @p str .
786 * @see QTextCodec::mibEnum()
787 **/
788 static QString decode_string(const QString &str, int encoding_hint = 0);
789
790 /**
791 * Convenience function.
792 *
793 * Returns whether '_url' is likely to be a "relative" URL instead of
794 * an "absolute" URL.
795 * @param _url URL to examine
796 * @return true when the URL is likely to be "relative", false otherwise.
797 */
798 static bool isRelativeURL(const QString &_url);
799
800#ifdef KDE_NO_COMPAT
801private:
802#endif
803 QString filename( bool _ignore_trailing_slash_in_path = true ) const
804 {
805 return fileName(_ignore_trailing_slash_in_path);
806 }
807
808protected:
809 void reset();
810 void parse( const QString& _url, int encoding_hint = 0);
811
812private:
813 QString m_strProtocol;
814 QString m_strUser;
815 QString m_strPass;
816 QString m_strHost;
817 QString m_strPath;
818 QString m_strRef_encoded;
819 QString m_strQuery_encoded;
820 bool m_bIsMalformed : 1;
821 int freeForUse : 7;
822 unsigned short int m_iPort;
823 QString m_strPath_encoded;
824
825 friend QDataStream & operator<< (QDataStream & s, const KURL & a);
826 friend QDataStream & operator>> (QDataStream & s, KURL & a);
827private:
828 KURLPrivate* d;
829};
830
831/**
832 * Compares URLs. They are parsed, split and compared.
833 * Two malformed URLs with the same string representation
834 * are nevertheless considered to be unequal.
835 * That means no malformed URL equals anything else.
836 */
837bool urlcmp( const QString& _url1, const QString& _url2 );
838
839/**
840 * Compares URLs. They are parsed, split and compared.
841 * Two malformed URLs with the same string representation
842 * are nevertheless considered to be unequal.
843 * That means no malformed URL equals anything else.
844 *
845 * @param _ignore_trailing Described in @ref KURL::cmp
846 * @param _ignore_ref If true, disables comparison of HTML-style references.
847 */
848bool urlcmp( const QString& _url1, const QString& _url2, bool _ignore_trailing, bool _ignore_ref );
849
850QDataStream & operator<< (QDataStream & s, const KURL & a);
851QDataStream & operator>> (QDataStream & s, KURL & a);
852
853#endif