src/corelib/io/qurl.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the QtCore module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #ifndef QURL_H
  43 #define QURL_H
  44
  45 #include <QtCore/qbytearray.h>
  46 #include <QtCore/qobjectdefs.h>
  47 #include <QtCore/qpair.h>
  48 #include <QtCore/qstring.h>
  49
  50 QT_BEGIN_HEADER
  51
  52 QT_BEGIN_NAMESPACE
  53
  54 QT_MODULE(Core)
  55
  56 class QUrlPrivate;
  57 class QDataStream;
  58
  59 class Q_CORE_EXPORT QUrl
  60 {
  61 public:
  62     enum ParsingMode {
  63         TolerantMode,
  64         StrictMode
  65     };
  66
  67     // encoding / toString values
  68     enum FormattingOption {
  69         None = 0x0,
  70         RemoveScheme = 0x1,
  71         RemovePassword = 0x2,
  72         RemoveUserInfo = RemovePassword | 0x4,
  73         RemovePort = 0x8,
  74         RemoveAuthority = RemoveUserInfo | RemovePort | 0x10,
  75         RemovePath = 0x20,
  76         RemoveQuery = 0x40,
  77         RemoveFragment = 0x80,
  78
  79         StripTrailingSlash = 0x10000
  80     };
  81     Q_DECLARE_FLAGS(FormattingOptions, FormattingOption)
  82
  83     QUrl();
  84 #ifdef QT_NO_URL_CAST_FROM_STRING
  85     explicit
  86 #endif
  87     QUrl(const QString &url);
  88     QUrl(const QString &url, ParsingMode mode);
  89     // ### Qt 5: merge the two constructors, with mode = TolerantMode
  90     QUrl(const QUrl &copy);
  91     QUrl &operator =(const QUrl &copy);
  92 #ifndef QT_NO_URL_CAST_FROM_STRING
  93     QUrl &operator =(const QString &url);
  94 #endif
  95     ~QUrl();
  96
  97     void setUrl(const QString &url);
  98     void setUrl(const QString &url, ParsingMode mode);
  99     // ### Qt 5: merge the two setUrl() functions, with mode = TolerantMode
 100     void setEncodedUrl(const QByteArray &url);
 101     void setEncodedUrl(const QByteArray &url, ParsingMode mode);
 102     // ### Qt 5: merge the two setEncodedUrl() functions, with mode = TolerantMode
 103
 104     bool isValid() const;
 105
 106     bool isEmpty() const;
 107
 108     void clear();
 109
 110     void setScheme(const QString &scheme);
 111     QString scheme() const;
 112
 113     void setAuthority(const QString &authority);
 114     QString authority() const;
 115
 116     void setUserInfo(const QString &userInfo);
 117     QString userInfo() const;
 118
 119     void setUserName(const QString &userName);
 120     QString userName() const;
 121     void setEncodedUserName(const QByteArray &userName);
 122     QByteArray encodedUserName() const;
 123
 124     void setPassword(const QString &password);
 125     QString password() const;
 126     void setEncodedPassword(const QByteArray &password);
 127     QByteArray encodedPassword() const;
 128
 129     void setHost(const QString &host);
 130     QString host() const;
 131     void setEncodedHost(const QByteArray &host);
 132     QByteArray encodedHost() const;
 133
 134     void setPort(int port);
 135     int port() const;
 136     int port(int defaultPort) const;
 137     // ### Qt 5: merge the two port() functions, with defaultPort = -1
 138
 139     void setPath(const QString &path);
 140     QString path() const;
 141     void setEncodedPath(const QByteArray &path);
 142     QByteArray encodedPath() const;
 143
 144     bool hasQuery() const;
 145
 146     void setEncodedQuery(const QByteArray &query);
 147     QByteArray encodedQuery() const;
 148
 149     void setQueryDelimiters(char valueDelimiter, char pairDelimiter);
 150     char queryValueDelimiter() const;
 151     char queryPairDelimiter() const;
 152
 153     void setQueryItems(const QList<QPair<QString, QString> > &query);
 154     void addQueryItem(const QString &key, const QString &value);
 155     QList<QPair<QString, QString> > queryItems() const;
 156     bool hasQueryItem(const QString &key) const;
 157     QString queryItemValue(const QString &key) const;
 158     QStringList allQueryItemValues(const QString &key) const;
 159     void removeQueryItem(const QString &key);
 160     void removeAllQueryItems(const QString &key);
 161
 162     void setEncodedQueryItems(const QList<QPair<QByteArray, QByteArray> > &query);
 163     void addEncodedQueryItem(const QByteArray &key, const QByteArray &value);
 164     QList<QPair<QByteArray, QByteArray> > encodedQueryItems() const;
 165     bool hasEncodedQueryItem(const QByteArray &key) const;
 166     QByteArray encodedQueryItemValue(const QByteArray &key) const;
 167     QList<QByteArray> allEncodedQueryItemValues(const QByteArray &key) const;
 168     void removeEncodedQueryItem(const QByteArray &key);
 169     void removeAllEncodedQueryItems(const QByteArray &key);
 170
 171     void setFragment(const QString &fragment);
 172     QString fragment() const;
 173     void setEncodedFragment(const QByteArray &fragment);
 174     QByteArray encodedFragment() const;
 175     bool hasFragment() const;
 176
 177     QUrl resolved(const QUrl &relative) const;
 178
 179     bool isRelative() const;
 180     bool isParentOf(const QUrl &url) const;
 181
 182     static QUrl fromLocalFile(const QString &localfile);
 183     QString toLocalFile() const;
 184
 185     QString toString(FormattingOptions options = None) const;
 186
 187     QByteArray toEncoded(FormattingOptions options = None) const;
 188     static QUrl fromEncoded(const QByteArray &url);
 189     static QUrl fromEncoded(const QByteArray &url, ParsingMode mode);
 190     // ### Qt 5: merge the two fromEncoded() functions, with mode = TolerantMode
 191
 192     static QUrl fromUserInput(const QString &userInput);
 193
 194     void detach();
 195     bool isDetached() const;
 196
 197     bool operator <(const QUrl &url) const;
 198     bool operator ==(const QUrl &url) const;
 199     bool operator !=(const QUrl &url) const;
 200
 201     static QString fromPercentEncoding(const QByteArray &);
 202     static QByteArray toPercentEncoding(const QString &,
 203                                         const QByteArray &exclude = QByteArray(),
 204                                         const QByteArray &include = QByteArray());
 205     static QString fromPunycode(const QByteArray &);
 206     static QByteArray toPunycode(const QString &);
 207     static QString fromAce(const QByteArray &);
 208     static QByteArray toAce(const QString &);
 209     static QStringList idnWhitelist();
 210     static void setIdnWhitelist(const QStringList &);
 211
 212 #if defined QT3_SUPPORT
 213     inline QT3_SUPPORT QString protocol() const { return scheme(); }
 214     inline QT3_SUPPORT void setProtocol(const QString &s) { setScheme(s); }
 215     inline QT3_SUPPORT void setUser(const QString &s) { setUserName(s); }
 216     inline QT3_SUPPORT QString user() const { return userName(); }
 217     inline QT3_SUPPORT bool hasUser() const { return !userName().isEmpty(); }
 218     inline QT3_SUPPORT bool hasPassword() const { return !password().isEmpty(); }
 219     inline QT3_SUPPORT bool hasHost() const { return !host().isEmpty(); }
 220     inline QT3_SUPPORT bool hasPort() const { return port() != -1; }
 221     inline QT3_SUPPORT bool hasPath() const { return !path().isEmpty(); }
 222     inline QT3_SUPPORT void setQuery(const QString &txt)
 223     {
 224         setEncodedQuery(txt.toLatin1());
 225     }
 226     inline QT3_SUPPORT QString query() const
 227     {
 228         return QString::fromLatin1(encodedQuery().constData());
 229     }
 230     inline QT3_SUPPORT QString ref() const { return fragment(); }
 231     inline QT3_SUPPORT void setRef(const QString &txt) { setFragment(txt); }
 232     inline QT3_SUPPORT bool hasRef() const { return !fragment().isEmpty(); }
 233     inline QT3_SUPPORT void addPath(const QString &p) { setPath(path() + QLatin1Char('/') + p); }
 234     QT3_SUPPORT void setFileName(const QString &txt);
 235     QT3_SUPPORT QString fileName() const;
 236     QT3_SUPPORT QString dirPath() const;
 237     static inline QT3_SUPPORT void decode(QString &url)
 238     {
 239         url = QUrl::fromPercentEncoding(url.toLatin1());
 240     }
 241     static inline QT3_SUPPORT void encode(QString &url)
 242     {
 243         url = QString::fromLatin1(QUrl::toPercentEncoding(url).constData());
 244     }
 245     inline QT3_SUPPORT operator QString() const { return toString(); }
 246     inline QT3_SUPPORT bool cdUp()
 247     {
 248         *this = resolved(QUrl(QLatin1String("..")));
 249         return true;
 250     }
 251     static inline QT3_SUPPORT bool isRelativeUrl(const QString &url)
 252     {
 253         return QUrl(url).isRelative();
 254     }
 255 #endif
 256
 257     QString errorString() const;
 258
 259 protected:
 260 #if defined (QT3_SUPPORT)
 261     inline QT3_SUPPORT void reset() { clear(); }
 262 #endif
 263
 264 private:
 265     QUrlPrivate *d;
 266 public:
 267     typedef QUrlPrivate * DataPtr;
 268     inline DataPtr &data_ptr() { return d; }
 269 };
 270
 271 Q_DECLARE_TYPEINFO(QUrl, Q_MOVABLE_TYPE);
 272 Q_DECLARE_SHARED(QUrl)
 273 Q_DECLARE_OPERATORS_FOR_FLAGS(QUrl::FormattingOptions)
 274
 275 #ifndef QT_NO_DATASTREAM
 276 Q_CORE_EXPORT QDataStream &operator<<(QDataStream &, const QUrl &);
 277 Q_CORE_EXPORT QDataStream &operator>>(QDataStream &, QUrl &);
 278 #endif
 279
 280 #ifndef QT_NO_DEBUG_STREAM
 281 Q_CORE_EXPORT QDebug operator<<(QDebug, const QUrl &);
 282 #endif
 283
 284 QT_END_NAMESPACE
 285
 286 QT_END_HEADER
 287
 288 #endif // QURL_H