summaryrefslogtreecommitdiffabout
path: root/microkde/kurl.h
Unidiff
Diffstat (limited to 'microkde/kurl.h') (more/less context) (show whitespace changes)
-rw-r--r--microkde/kurl.h14
1 files changed, 8 insertions, 6 deletions
diff --git a/microkde/kurl.h b/microkde/kurl.h
index cd65a1c..016eb24 100644
--- a/microkde/kurl.h
+++ b/microkde/kurl.h
@@ -1,196 +1,198 @@
1/* This file is part of the KDE libraries 1/* This file is part of the KDE libraries
2 * Copyright (C) 1999 Torben Weis <weis@kde.org> 2 * Copyright (C) 1999 Torben Weis <weis@kde.org>
3 * 3 *
4 * This library is free software; you can redistribute it and/or 4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public 5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either 6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version. 7 * version 2 of the License, or (at your option) any later version.
8 * 8 *
9 * This library is distributed in the hope that it will be useful, 9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details. 12 * Library General Public License for more details.
13 * 13 *
14 * You should have received a copy of the GNU Library General Public License 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 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, 16 * the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA. 17 * Boston, MA 02111-1307, USA.
18 **/ 18 **/
19 19
20#ifndef __kurl_h__ 20#ifndef __kurl_h__
21#define __kurl_h__ "$Id$" 21#define __kurl_h__ "$Id$"
22 22
23#include <qstring.h> 23#include <qstring.h>
24#include <qvaluelist.h> 24#include <q3valuelist.h>
25//Added by qt3to4:
26#include <Q3CString>
25 27
26class QUrl; 28class Q3Url;
27class QStringList; 29class QStringList;
28template <typename K, typename V> class QMap; 30template <typename K, typename V> class QMap;
29 31
30class KURLPrivate; 32class KURLPrivate;
31/** 33/**
32 * Represents and parses a URL. 34 * Represents and parses a URL.
33 * 35 *
34 * A prototypical URL looks like: 36 * A prototypical URL looks like:
35 * <pre> 37 * <pre>
36 * protocol:/user:password\@hostname:port/path/to/file.ext#reference 38 * protocol:/user:password\@hostname:port/path/to/file.ext#reference
37 * </pre> 39 * </pre>
38 * 40 *
39 * KURL has some restrictions regarding the path 41 * KURL has some restrictions regarding the path
40 * encoding. KURL works internally with the decoded path and 42 * encoding. KURL works internally with the decoded path and
41 * and encoded query. For example, 43 * and encoded query. For example,
42 * <pre> 44 * <pre>
43 * http://localhost/cgi-bin/test%20me.pl?cmd=Hello%20you 45 * http://localhost/cgi-bin/test%20me.pl?cmd=Hello%20you
44 * </pre> 46 * </pre>
45 * would result in a decoded path "/cgi-bin/test me.pl" 47 * would result in a decoded path "/cgi-bin/test me.pl"
46 * and in the encoded query "?cmd=Hello%20you". 48 * and in the encoded query "?cmd=Hello%20you".
47 * Since path is internally always encoded you may @em not use 49 * Since path is internally always encoded you may @em not use
48 * "%00" in the path, although this is OK for the query. 50 * "%00" in the path, although this is OK for the query.
49 * 51 *
50 * @author Torben Weis <weis@kde.org> 52 * @author Torben Weis <weis@kde.org>
51 */ 53 */
52class KURL 54class KURL
53{ 55{
54public: 56public:
55 enum AdjustementFlags 57 enum AdjustementFlags
56 { 58 {
57 NoAdjustements = 0, 59 NoAdjustements = 0,
58 StripFileProtocol = 1 60 StripFileProtocol = 1
59 }; 61 };
60 62
61 /** 63 /**
62 * KURL::List is a QValueList that contains KURLs with a few 64 * KURL::List is a QValueList that contains KURLs with a few
63 * convenience methods. 65 * convenience methods.
64 * @see KURL 66 * @see KURL
65 * @see QValueList 67 * @see QValueList
66 */ 68 */
67 class List : public QValueList<KURL> 69 class List : public Q3ValueList<KURL>
68 { 70 {
69 public: 71 public:
70 /** 72 /**
71 * Creates an empty List. 73 * Creates an empty List.
72 */ 74 */
73 List() { } 75 List() { }
74 /** 76 /**
75 * Creates a list that contains the given URL as only 77 * Creates a list that contains the given URL as only
76 * item. 78 * item.
77 * @param url the url to add. 79 * @param url the url to add.
78 */ 80 */
79 List(const KURL &url); 81 List(const KURL &url);
80 /** 82 /**
81 * Creates a list that contains the URLs from the given 83 * Creates a list that contains the URLs from the given
82 * list. 84 * list.
83 * @param list the list containing the URLs as strings 85 * @param list the list containing the URLs as strings
84 */ 86 */
85 List(const QStringList &list); 87 List(const QStringList &list);
86 /** 88 /**
87 * Converts the URLs of this list to a list of strings. 89 * Converts the URLs of this list to a list of strings.
88 * @return the list of strings 90 * @return the list of strings
89 */ 91 */
90 QStringList toStringList() const; 92 QStringList toStringList() const;
91 }; 93 };
92 /** 94 /**
93 * Constructs an empty URL. 95 * Constructs an empty URL.
94 */ 96 */
95 KURL(); 97 KURL();
96 98
97 /** 99 /**
98 * Destructs the KURL object. 100 * Destructs the KURL object.
99 */ 101 */
100 ~KURL(); 102 ~KURL();
101 103
102 /** 104 /**
103 * Usual constructor, to construct from a string. 105 * Usual constructor, to construct from a string.
104 * @param url A URL, not a filename. If the URL does not have a protocol 106 * @param url A URL, not a filename. If the URL does not have a protocol
105 * part, "file:" is assumed. 107 * part, "file:" is assumed.
106 * It is dangerous to feed unix filenames into this function, 108 * It is dangerous to feed unix filenames into this function,
107 * this will work most of the time but not always. 109 * this will work most of the time but not always.
108 * For example "/home/Torben%20Weis" will be considered a URL 110 * For example "/home/Torben%20Weis" will be considered a URL
109 * pointing to the file "/home/Torben Weis" instead of to the 111 * pointing to the file "/home/Torben Weis" instead of to the
110 * file "/home/Torben%20Weis". 112 * file "/home/Torben%20Weis".
111 * This means that if you have a usual UNIX like path you 113 * This means that if you have a usual UNIX like path you
112 * should not use this constructor. 114 * should not use this constructor.
113 * Instead create an empty url and set the path by using 115 * Instead create an empty url and set the path by using
114 * @ref setPath(). 116 * @ref setPath().
115 * @param encoding_hint MIB of original encoding of URL. 117 * @param encoding_hint MIB of original encoding of URL.
116 * @see QTextCodec::mibEnum() 118 * @see QTextCodec::mibEnum()
117 */ 119 */
118 KURL( const QString& url, int encoding_hint = 0 ); 120 KURL( const QString& url, int encoding_hint = 0 );
119 /** 121 /**
120 * Constructor taking a char * @p url, which is an _encoded_ representation 122 * Constructor taking a char * @p url, which is an _encoded_ representation
121 * of the URL, exactly like the usual constructor. This is useful when 123 * of the URL, exactly like the usual constructor. This is useful when
122 * then URL, in its encoded form, is strictly ascii. 124 * then URL, in its encoded form, is strictly ascii.
123 * @param url A encoded URL. If the URL does not have a protocol part, 125 * @param url A encoded URL. If the URL does not have a protocol part,
124 * "file:" is assumed. 126 * "file:" is assumed.
125 * @param encoding_hint MIB of original encoding of URL. 127 * @param encoding_hint MIB of original encoding of URL.
126 * @see QTextCodec::mibEnum() 128 * @see QTextCodec::mibEnum()
127 */ 129 */
128 KURL( const char * url, int encoding_hint = 0 ); 130 KURL( const char * url, int encoding_hint = 0 );
129 /** 131 /**
130 * Constructor taking a QCString @p url, which is an _encoded_ representation 132 * Constructor taking a QCString @p url, which is an _encoded_ representation
131 * of the URL, exactly like the usual constructor. This is useful when 133 * of the URL, exactly like the usual constructor. This is useful when
132 * then URL, in its encoded form, is strictly ascii. 134 * then URL, in its encoded form, is strictly ascii.
133 * @param url A encoded URL. If the URL does not have a protocol part, 135 * @param url A encoded URL. If the URL does not have a protocol part,
134 * "file:" is assumed. 136 * "file:" is assumed.
135 * @param encoding_hint MIB of original encoding of URL. 137 * @param encoding_hint MIB of original encoding of URL.
136 * @see QTextCodec::mibEnum() 138 * @see QTextCodec::mibEnum()
137 */ 139 */
138 KURL( const QCString& url, int encoding_hint = 0 ); 140 KURL( const Q3CString& url, int encoding_hint = 0 );
139 /** 141 /**
140 * Copy constructor. 142 * Copy constructor.
141 * @param u the KURL to copy 143 * @param u the KURL to copy
142 */ 144 */
143 KURL( const KURL& u ); 145 KURL( const KURL& u );
144 /** 146 /**
145 * Converts from a @ref QUrl. 147 * Converts from a @ref QUrl.
146 * @param u the QUrl 148 * @param u the QUrl
147 */ 149 */
148 KURL( const QUrl &u ); 150 KURL( const Q3Url &u );
149 /** 151 /**
150 * Constructor allowing relative URLs. 152 * Constructor allowing relative URLs.
151 * 153 *
152 * @param _baseurl The base url. 154 * @param _baseurl The base url.
153 * @param _rel_url A relative or absolute URL. 155 * @param _rel_url A relative or absolute URL.
154 * If this is an absolute URL then @p _baseurl will be ignored. 156 * 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. 157 * 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. 158 * Note that _rel_url should be encoded too, in any case.
157 * So do NOT pass a path here (use setPath or addPath instead). 159 * So do NOT pass a path here (use setPath or addPath instead).
158 * @param encoding_hint MIB of original encoding of URL. 160 * @param encoding_hint MIB of original encoding of URL.
159 * @see QTextCodec::mibEnum() 161 * @see QTextCodec::mibEnum()
160 */ 162 */
161 KURL( const KURL& _baseurl, const QString& _rel_url, int encoding_hint=0 ); 163 KURL( const KURL& _baseurl, const QString& _rel_url, int encoding_hint=0 );
162 164
163 /** 165 /**
164 * Returns the protocol for the URL (i.e., file, http, etc.). 166 * 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 167 * @return the protocol of the URL, does not include the colon. If the
166 * URL is malformed, QString::null will be returned. 168 * URL is malformed, QString::null will be returned.
167 **/ 169 **/
168 QString protocol() const { return m_bIsMalformed ? QString::null : m_strProtocol; } 170 QString protocol() const { return m_bIsMalformed ? QString::null : m_strProtocol; }
169 /** 171 /**
170 * Sets the protocol for the URL (i.e., file, http, etc.) 172 * Sets the protocol for the URL (i.e., file, http, etc.)
171 * @param _txt the new protocol of the URL (without colon) 173 * @param _txt the new protocol of the URL (without colon)
172 **/ 174 **/
173 void setProtocol( const QString& _txt ); 175 void setProtocol( const QString& _txt );
174 176
175 /** 177 /**
176 * Returns the decoded user name (login, user id, ...) included in the URL. 178 * 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 179 * @return the user name or QString::null if there is no user name
178 **/ 180 **/
179 QString user() const { return m_strUser; } 181 QString user() const { return m_strUser; }
180 /** 182 /**
181 * Sets the user name (login, user id, ...) included in the URL. 183 * Sets the user name (login, user id, ...) included in the URL.
182 * 184 *
183 * Special characters in the user name will appear encoded in the URL. 185 * 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 186 * @param _txt the name of the user or QString::null to remove the user
185 **/ 187 **/
186 void setUser( const QString& _txt ); 188 void setUser( const QString& _txt );
187 /** 189 /**
188 * Test to see if this URL has a user name included in it. 190 * 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 191 * @return true if the URL has an non-empty user name
190 **/ 192 **/
191 bool hasUser() const { return !m_strUser.isEmpty(); } 193 bool hasUser() const { return !m_strUser.isEmpty(); }
192 194
193 /** 195 /**
194 * Returns the decoded password (corresponding to \ref user()) included in the URL. 196 * Returns the decoded password (corresponding to \ref user()) included in the URL.
195 * @return the password or QString::null if it does not exist 197 * @return the password or QString::null if it does not exist
196 **/ 198 **/
@@ -613,97 +615,97 @@ public:
613 * a trailing '/' if there is none yet and 0 returns the 615 * a trailing '/' if there is none yet and 0 returns the
614 * path unchanged. 616 * path unchanged.
615 * @return A human readable URL, with no non-necessary encodings/escaped 617 * @return A human readable URL, with no non-necessary encodings/escaped
616 * characters. Password will not be shown. 618 * characters. Password will not be shown.
617 * @see url() 619 * @see url()
618 */ 620 */
619 QString prettyURL( int _trailing = 0) const; 621 QString prettyURL( int _trailing = 0) const;
620 622
621 623
622 /** 624 /**
623 * Returns the URL as string, escaped for HTML. 625 * Returns the URL as string, escaped for HTML.
624 * @return A human readable URL, with no non-necessary encodings/escaped 626 * @return A human readable URL, with no non-necessary encodings/escaped
625 * characters which is html encoded for safe inclusion in html or 627 * characters which is html encoded for safe inclusion in html or
626 * rich text. Password will not be shown. 628 * rich text. Password will not be shown.
627 */ 629 */
628 QString htmlURL() const; 630 QString htmlURL() const;
629 631
630 /** 632 /**
631 * Returns the URL as string, escaped for HTML. 633 * Returns the URL as string, escaped for HTML.
632 * Example: 634 * Example:
633 * <pre> 635 * <pre>
634 * http://localhost:8080/test.cgi?test=hello world&name=fred 636 * http://localhost:8080/test.cgi?test=hello world&name=fred
635 * </pre> 637 * </pre>
636 * @return A human readable URL, with no non-necessary encodings/escaped 638 * @return A human readable URL, with no non-necessary encodings/escaped
637 * characters. Password will not be shown. 639 * characters. Password will not be shown.
638 */ 640 */
639 QString prettyURL( int _trailing, AdjustementFlags _flags) const; 641 QString prettyURL( int _trailing, AdjustementFlags _flags) const;
640 // ### BIC: Merge the two above 642 // ### BIC: Merge the two above
641 643
642 /** 644 /**
643 * Test to see if the KURL is empty. 645 * Test to see if the KURL is empty.
644 * @return true if the URL is empty 646 * @return true if the URL is empty
645 **/ 647 **/
646 bool isEmpty() const; 648 bool isEmpty() const;
647 649
648 /** 650 /**
649 * This function is useful to implement the "Up" button in a file manager for example. 651 * 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 652 * @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 653 * 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 654 * 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. 655 * possible it strips the right most URL. It continues stripping URLs.
654 * @return a URL that is a level higher 656 * @return a URL that is a level higher
655 */ 657 */
656 KURL upURL( ) const; 658 KURL upURL( ) const;
657 659
658 KURL& operator=( const KURL& _u ); 660 KURL& operator=( const KURL& _u );
659 KURL& operator=( const QString& _url ); 661 KURL& operator=( const QString& _url );
660 KURL& operator=( const char * _url ); 662 KURL& operator=( const char * _url );
661 KURL& operator=( const QUrl & u ); 663 KURL& operator=( const Q3Url & u );
662 664
663 bool operator==( const KURL& _u ) const; 665 bool operator==( const KURL& _u ) const;
664 bool operator==( const QString& _u ) const; 666 bool operator==( const QString& _u ) const;
665 bool operator!=( const KURL& _u ) const { return !( *this == _u ); } 667 bool operator!=( const KURL& _u ) const { return !( *this == _u ); }
666 bool operator!=( const QString& _u ) const { return !( *this == _u ); } 668 bool operator!=( const QString& _u ) const { return !( *this == _u ); }
667 669
668 /** 670 /**
669 * The same as equals(), just with a less obvious name. 671 * The same as equals(), just with a less obvious name.
670 * Compares this url with @p u. 672 * Compares this url with @p u.
671 * @param ignore_trailing set to true to ignore trailing '/' characters. 673 * @param ignore_trailing set to true to ignore trailing '/' characters.
672 * @return true if both urls are the same 674 * @return true if both urls are the same
673 * @see operator==. This function should be used if you want to 675 * @see operator==. This function should be used if you want to
674 * ignore trailing '/' characters. 676 * ignore trailing '/' characters.
675 * @deprecated 677 * @deprecated
676 */ 678 */
677 bool cmp( const KURL &u, bool ignore_trailing = false ) const; 679 bool cmp( const KURL &u, bool ignore_trailing = false ) const;
678 680
679 /** 681 /**
680 * Compares this url with @p u. 682 * Compares this url with @p u.
681 * @param ignore_trailing set to true to ignore trailing '/' characters. 683 * @param ignore_trailing set to true to ignore trailing '/' characters.
682 * @return true if both urls are the same 684 * @return true if both urls are the same
683 * @see operator==. This function should be used if you want to 685 * @see operator==. This function should be used if you want to
684 * ignore trailing '/' characters. 686 * ignore trailing '/' characters.
685 * @since 3.1 687 * @since 3.1
686 */ 688 */
687 bool equals( const KURL &u, bool ignore_trailing = false ) const; 689 bool equals( const KURL &u, bool ignore_trailing = false ) const;
688 690
689 /** 691 /**
690 * Checks whether the given URL is parent of this URL. 692 * 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/. 693 * 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) 694 * @return true if this url is a parent of @p u (or the same URL as @p u)
693 */ 695 */
694 bool isParentOf( const KURL& u ) const; 696 bool isParentOf( const KURL& u ) const;
695 697
696 /** 698 /**
697 * Splits nested URLs like file:/home/weis/kde.tgz#gzip:/#tar:/kdebase 699 * 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 700 * 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. 701 * 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. 702 * That means in turn that "#ref1" is an HTML-style reference and not a new sub URL.
701 * Since HTML-style references mark 703 * Since HTML-style references mark
702 * a certain position in a document this reference is appended to every URL. 704 * 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 705 * 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. 706 * the rest is not of interest to them.
705 * 707 *
706 * 708 *
707 * @param _url The URL that has to be split. 709 * @param _url The URL that has to be split.
708 * @return An empty list on error or the list of split URLs. 710 * @return An empty list on error or the list of split URLs.
709 * @see #hasSubURL 711 * @see #hasSubURL