You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
497 lines
16 KiB
497 lines
16 KiB
'\" t
|
|
.TH QUrl 3qt "2 February 2007" "Trolltech AS" \" -*- nroff -*-
|
|
.\" Copyright 1992-2007 Trolltech ASA. All rights reserved. See the
|
|
.\" license file included in the distribution for a complete license
|
|
.\" statement.
|
|
.\"
|
|
.ad l
|
|
.nh
|
|
.SH NAME
|
|
QUrl \- URL parser and simplifies working with URLs
|
|
.SH SYNOPSIS
|
|
\fC#include <qurl.h>\fR
|
|
.PP
|
|
Inherited by QUrlOperator.
|
|
.PP
|
|
.SS "Public Members"
|
|
.in +1c
|
|
.ti -1c
|
|
.BI "\fBQUrl\fR ()"
|
|
.br
|
|
.ti -1c
|
|
.BI "\fBQUrl\fR ( const QString & url )"
|
|
.br
|
|
.ti -1c
|
|
.BI "\fBQUrl\fR ( const QUrl & url )"
|
|
.br
|
|
.ti -1c
|
|
.BI "\fBQUrl\fR ( const QUrl & url, const QString & relUrl, bool checkSlash = FALSE )"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual \fB~QUrl\fR ()"
|
|
.br
|
|
.ti -1c
|
|
.BI "QString \fBprotocol\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual void \fBsetProtocol\fR ( const QString & protocol )"
|
|
.br
|
|
.ti -1c
|
|
.BI "QString \fBuser\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual void \fBsetUser\fR ( const QString & user )"
|
|
.br
|
|
.ti -1c
|
|
.BI "bool \fBhasUser\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "QString \fBpassword\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual void \fBsetPassword\fR ( const QString & pass )"
|
|
.br
|
|
.ti -1c
|
|
.BI "bool \fBhasPassword\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "QString \fBhost\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual void \fBsetHost\fR ( const QString & host )"
|
|
.br
|
|
.ti -1c
|
|
.BI "bool \fBhasHost\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "int \fBport\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual void \fBsetPort\fR ( int port )"
|
|
.br
|
|
.ti -1c
|
|
.BI "bool \fBhasPort\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "QString \fBpath\fR ( bool correct = TRUE ) const"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual void \fBsetPath\fR ( const QString & path )"
|
|
.br
|
|
.ti -1c
|
|
.BI "bool \fBhasPath\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual void \fBsetEncodedPathAndQuery\fR ( const QString & pathAndQuery )"
|
|
.br
|
|
.ti -1c
|
|
.BI "QString \fBencodedPathAndQuery\fR ()"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual void \fBsetQuery\fR ( const QString & txt )"
|
|
.br
|
|
.ti -1c
|
|
.BI "QString \fBquery\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "QString \fBref\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual void \fBsetRef\fR ( const QString & txt )"
|
|
.br
|
|
.ti -1c
|
|
.BI "bool \fBhasRef\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "bool \fBisValid\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "bool \fBisLocalFile\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual void \fBaddPath\fR ( const QString & pa )"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual void \fBsetFileName\fR ( const QString & name )"
|
|
.br
|
|
.ti -1c
|
|
.BI "QString \fBfileName\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "QString \fBdirPath\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "QUrl & \fBoperator=\fR ( const QUrl & url )"
|
|
.br
|
|
.ti -1c
|
|
.BI "QUrl & \fBoperator=\fR ( const QString & url )"
|
|
.br
|
|
.ti -1c
|
|
.BI "bool \fBoperator==\fR ( const QUrl & url ) const"
|
|
.br
|
|
.ti -1c
|
|
.BI "bool \fBoperator==\fR ( const QString & url ) const"
|
|
.br
|
|
.ti -1c
|
|
.BI "\fBoperator QString\fR () const"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual QString \fBtoString\fR ( bool encodedPath = FALSE, bool forcePrependProtocol = TRUE ) const"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual bool \fBcdUp\fR ()"
|
|
.br
|
|
.in -1c
|
|
.SS "Static Public Members"
|
|
.in +1c
|
|
.ti -1c
|
|
.BI "void \fBdecode\fR ( QString & url )"
|
|
.br
|
|
.ti -1c
|
|
.BI "void \fBencode\fR ( QString & url )"
|
|
.br
|
|
.ti -1c
|
|
.BI "bool \fBisRelativeUrl\fR ( const QString & url )"
|
|
.br
|
|
.in -1c
|
|
.SS "Protected Members"
|
|
.in +1c
|
|
.ti -1c
|
|
.BI "virtual void \fBreset\fR ()"
|
|
.br
|
|
.ti -1c
|
|
.BI "virtual bool \fBparse\fR ( const QString & url )"
|
|
.br
|
|
.in -1c
|
|
.SH DESCRIPTION
|
|
The QUrl class provides a URL parser and simplifies working with URLs.
|
|
.PP
|
|
The QUrl class is provided for simple work with URLs. It can parse, decode, encode, etc.
|
|
.PP
|
|
QUrl works with the decoded path and encoded query in turn.
|
|
.PP
|
|
Example:
|
|
.PP
|
|
\fChttp://www.trolltech.com:80/cgi-bin/test%20me.pl?cmd=Hello%20you\fR
|
|
.PP
|
|
<center>.nf
|
|
.TS
|
|
l - l. Function Returns protocol() "http" host() "www.trolltech.com" port() 80 path() "/cgi-bin/testme.pl" fileName() "testme.pl" query()
|
|
.TE
|
|
.fi
|
|
</center>
|
|
.PP
|
|
Example:
|
|
.PP
|
|
\fChttp://doc.trolltech.com/qdockarea.html#lines\fR
|
|
.PP
|
|
<center>.nf
|
|
.TS
|
|
l - l. Function Returns protocol() "http" host() "doc.trolltech.com" fileName() "qdockarea.html" ref()
|
|
.TE
|
|
.fi
|
|
</center>
|
|
.PP
|
|
The individual parts of a URL can be set with setProtocol(), setHost(), setPort(), setPath(), setFileName(), setRef() and setQuery(). A URL could contain, for example, an ftp address which requires a user name and password; these can be set with setUser() and setPassword().
|
|
.PP
|
|
Because path is always encoded internally you must not use "%00" in the path, although this is okay (but not recommended) for the query.
|
|
.PP
|
|
QUrl is normally used like this:
|
|
.PP
|
|
.nf
|
|
.br
|
|
QUrl url( "http://www.trolltech.com" );
|
|
.br
|
|
// or
|
|
.br
|
|
QUrl url( "file:/home/myself/Mail", "Inbox" );
|
|
.br
|
|
.fi
|
|
.PP
|
|
You can then access and manipulate the various parts of the URL.
|
|
.PP
|
|
To make it easy to work with QUrls and QStrings, QUrl implements the necessary cast and assignment operators so you can do following:
|
|
.PP
|
|
.nf
|
|
.br
|
|
QUrl url( "http://www.trolltech.com" );
|
|
.br
|
|
QString s = url;
|
|
.br
|
|
// or
|
|
.br
|
|
QString s( "http://www.trolltech.com" );
|
|
.br
|
|
QUrl url( s );
|
|
.br
|
|
.fi
|
|
.PP
|
|
Use the static functions, encode() and decode() to encode or decode a URL in a string. (They operate on the string in-place.) The isRelativeUrl() static function returns TRUE if the given string is a relative URL.
|
|
.PP
|
|
If you want to use a URL to work on a hierarchical structure (e.g. a local or remote filesystem), you might want to use the subclass QUrlOperator.
|
|
.PP
|
|
See also QUrlOperator, Input/Output and Networking, and Miscellaneous Classes.
|
|
.SH MEMBER FUNCTION DOCUMENTATION
|
|
.SH "QUrl::QUrl ()"
|
|
Constructs an empty URL that is invalid.
|
|
.SH "QUrl::QUrl ( const QString & url )"
|
|
Constructs a URL by parsing the string \fIurl\fR.
|
|
.PP
|
|
If you pass a string like "/home/qt", the "file" protocol is assumed.
|
|
.SH "QUrl::QUrl ( const QUrl & url )"
|
|
Copy constructor. Copies the data of \fIurl\fR.
|
|
.SH "QUrl::QUrl ( const QUrl & url, const QString & relUrl, bool checkSlash = FALSE )"
|
|
Constructs an URL taking \fIurl\fR as the base (context) and \fIrelUrl\fR as a relative URL to \fIurl\fR. If \fIrelUrl\fR is not relative, \fIrelUrl\fR is taken as the new URL.
|
|
.PP
|
|
For example, the path of
|
|
.PP
|
|
.nf
|
|
.br
|
|
QUrl url( "ftp://ftp.trolltech.com/qt/source", "qt-2.1.0.tar.gz" );
|
|
.br
|
|
.fi
|
|
will be "/qt/srource/qt-2.1.0.tar.gz".
|
|
.PP
|
|
On the other hand,
|
|
.PP
|
|
.nf
|
|
.br
|
|
QUrl url( "ftp://ftp.trolltech.com/qt/source", "/usr/local" );
|
|
.br
|
|
.fi
|
|
will result in a new URL, "ftp://ftp.trolltech.com/usr/local", because "/usr/local" isn't relative.
|
|
.PP
|
|
Similarly,
|
|
.PP
|
|
.nf
|
|
.br
|
|
QUrl url( "ftp://ftp.trolltech.com/qt/source", "file:/usr/local" );
|
|
.br
|
|
.fi
|
|
will result in a new URL, with "/usr/local" as the path and "file" as the protocol.
|
|
.PP
|
|
Normally it is expected that the path of \fIurl\fR points to a directory, even if the path has no slash at the end. But if you want the constructor to handle the last part of the path as a file name if there is no slash at the end, and to let it be replaced by the file name of \fIrelUrl\fR (if it contains one), set \fIcheckSlash\fR to TRUE.
|
|
.SH "QUrl::~QUrl ()\fC [virtual]\fR"
|
|
Destructor.
|
|
.SH "void QUrl::addPath ( const QString & pa )\fC [virtual]\fR"
|
|
Adds the path \fIpa\fR to the path of the URL.
|
|
.PP
|
|
See also setPath() and hasPath().
|
|
.SH "bool QUrl::cdUp ()\fC [virtual]\fR"
|
|
Changes the directory to one directory up.
|
|
.PP
|
|
See also setPath().
|
|
.SH "void QUrl::decode ( QString & url )\fC [static]\fR"
|
|
Decodes the \fIurl\fR in-place into UTF-8. For example
|
|
.PP
|
|
.nf
|
|
.br
|
|
QString url = "http%3A//www%20trolltech%20com"
|
|
.br
|
|
QUrl::decode( url );
|
|
.br
|
|
// url is now "http://www.trolltech.com"
|
|
.br
|
|
.fi
|
|
.PP
|
|
See also encode().
|
|
.SH "QString QUrl::dirPath () const"
|
|
Returns the directory path of the URL. This is the part of the path of the URL without the fileName(). See the documentation of fileName() for a discussion of what is handled as file name and what is handled as directory path.
|
|
.PP
|
|
See also setPath() and hasPath().
|
|
.PP
|
|
Example: network/networkprotocol/nntp.cpp.
|
|
.SH "void QUrl::encode ( QString & url )\fC [static]\fR"
|
|
Encodes the \fIurl\fR in-place into UTF-8. For example
|
|
.PP
|
|
.nf
|
|
.br
|
|
QString url = http://www.trolltech.com
|
|
.br
|
|
QUrl::encode( url );
|
|
.br
|
|
// url is now "http%3A//www%20trolltech%20com"
|
|
.br
|
|
.fi
|
|
.PP
|
|
See also decode().
|
|
.PP
|
|
Example: network/archivesearch/archivedialog.ui.h.
|
|
.SH "QString QUrl::encodedPathAndQuery ()"
|
|
Returns the encoded path and query.
|
|
.PP
|
|
See also decode().
|
|
.SH "QString QUrl::fileName () const"
|
|
Returns the file name of the URL. If the path of the URL doesn't have a slash at the end, the part between the last slash and the end of the path string is considered to be the file name. If the path has a slash at the end, an empty string is returned here.
|
|
.PP
|
|
See also setFileName().
|
|
.PP
|
|
Example: network/networkprotocol/nntp.cpp.
|
|
.SH "bool QUrl::hasHost () const"
|
|
Returns TRUE if the URL contains a hostname; otherwise returns FALSE.
|
|
.PP
|
|
See also setHost().
|
|
.SH "bool QUrl::hasPassword () const"
|
|
Returns TRUE if the URL contains a password; otherwise returns FALSE.
|
|
.PP
|
|
\fBWarning:\fR Passwords passed in URLs are normally \fIinsecure\fR; this is due to the mechanism, not because of Qt.
|
|
.PP
|
|
See also setPassword() and setUser().
|
|
.SH "bool QUrl::hasPath () const"
|
|
Returns TRUE if the URL contains a path; otherwise returns FALSE.
|
|
.PP
|
|
See also path() and setPath().
|
|
.SH "bool QUrl::hasPort () const"
|
|
Returns TRUE if the URL contains a port; otherwise returns FALSE.
|
|
.PP
|
|
See also setPort().
|
|
.SH "bool QUrl::hasRef () const"
|
|
Returns TRUE if the URL has a reference; otherwise returns FALSE.
|
|
.PP
|
|
See also setRef().
|
|
.SH "bool QUrl::hasUser () const"
|
|
Returns TRUE if the URL contains a username; otherwise returns FALSE.
|
|
.PP
|
|
See also setUser() and setPassword().
|
|
.SH "QString QUrl::host () const"
|
|
Returns the hostname of the URL.
|
|
.PP
|
|
See also setHost() and hasHost().
|
|
.PP
|
|
Example: network/archivesearch/archivedialog.ui.h.
|
|
.SH "bool QUrl::isLocalFile () const"
|
|
Returns TRUE if the URL is a local file; otherwise returns FALSE.
|
|
.PP
|
|
Example: qdir/qdir.cpp.
|
|
.SH "bool QUrl::isRelativeUrl ( const QString & url )\fC [static]\fR"
|
|
Returns TRUE if \fIurl\fR is relative; otherwise returns FALSE.
|
|
.SH "bool QUrl::isValid () const"
|
|
Returns TRUE if the URL is valid; otherwise returns FALSE. A URL is invalid if it cannot be parsed, for example.
|
|
.SH "QUrl::operator QString () const"
|
|
Composes a string version of the URL and returns it.
|
|
.PP
|
|
See also QUrl::toString().
|
|
.SH "QUrl & QUrl::operator= ( const QUrl & url )"
|
|
Assigns the data of \fIurl\fR to this class.
|
|
.SH "QUrl & QUrl::operator= ( const QString & url )"
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|
.PP
|
|
Parses \fIurl\fR and assigns the resulting data to this class.
|
|
.PP
|
|
If you pass a string like "/home/qt" the "file" protocol will be assumed.
|
|
.SH "bool QUrl::operator== ( const QUrl & url ) const"
|
|
Compares this URL with \fIurl\fR and returns TRUE if they are equal; otherwise returns FALSE.
|
|
.SH "bool QUrl::operator== ( const QString & url ) const"
|
|
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
|
|
.PP
|
|
Compares this URL with \fIurl\fR. \fIurl\fR is parsed first. Returns TRUE if \fIurl\fR is equal to this url; otherwise returns FALSE.
|
|
.SH "bool QUrl::parse ( const QString & url )\fC [virtual protected]\fR"
|
|
Parses the \fIurl\fR.
|
|
.SH "QString QUrl::password () const"
|
|
Returns the password of the URL.
|
|
.PP
|
|
\fBWarning:\fR Passwords passed in URLs are normally \fIinsecure\fR; this is due to the mechanism, not because of Qt.
|
|
.PP
|
|
See also setPassword() and setUser().
|
|
.SH "QString QUrl::path ( bool correct = TRUE ) const"
|
|
Returns the path of the URL. If \fIcorrect\fR is TRUE, the path is cleaned (deals with too many or too few slashes, cleans things like "/../..", etc). Otherwise path() returns exactly the path that was parsed or set.
|
|
.PP
|
|
See also setPath() and hasPath().
|
|
.PP
|
|
Example: qdir/qdir.cpp.
|
|
.SH "int QUrl::port () const"
|
|
Returns the port of the URL or -1 if no port has been set.
|
|
.PP
|
|
See also setPort().
|
|
.SH "QString QUrl::protocol () const"
|
|
Returns the protocol of the URL. Typically, "file", "http", "ftp", etc.
|
|
.PP
|
|
See also setProtocol().
|
|
.SH "QString QUrl::query () const"
|
|
Returns the (encoded) query of the URL.
|
|
.PP
|
|
See also setQuery() and decode().
|
|
.SH "QString QUrl::ref () const"
|
|
Returns the (encoded) reference of the URL.
|
|
.PP
|
|
See also setRef(), hasRef(), and decode().
|
|
.SH "void QUrl::reset ()\fC [virtual protected]\fR"
|
|
Resets all parts of the URL to their default values and invalidates it.
|
|
.SH "void QUrl::setEncodedPathAndQuery ( const QString & pathAndQuery )\fC [virtual]\fR"
|
|
Parses \fIpathAndQuery\fR for a path and query and sets those values. The whole string must be encoded.
|
|
.PP
|
|
See also encode().
|
|
.SH "void QUrl::setFileName ( const QString & name )\fC [virtual]\fR"
|
|
Sets the file name of the URL to \fIname\fR. If this URL contains a fileName(), the original file name is replaced by \fIname\fR.
|
|
.PP
|
|
See the documentation of fileName() for a more detailed discussion of what is handled as file name and what is handled as a directory path.
|
|
.PP
|
|
See also fileName().
|
|
.SH "void QUrl::setHost ( const QString & host )\fC [virtual]\fR"
|
|
Sets the hostname of the URL to \fIhost\fR.
|
|
.PP
|
|
See also host() and hasHost().
|
|
.SH "void QUrl::setPassword ( const QString & pass )\fC [virtual]\fR"
|
|
Sets the password of the URL to \fIpass\fR.
|
|
.PP
|
|
\fBWarning:\fR Passwords passed in URLs are normally \fIinsecure\fR; this is due to the mechanism, not because of Qt.
|
|
.PP
|
|
See also password() and setUser().
|
|
.SH "void QUrl::setPath ( const QString & path )\fC [virtual]\fR"
|
|
Sets the path of the URL to \fIpath\fR.
|
|
.PP
|
|
See also path() and hasPath().
|
|
.SH "void QUrl::setPort ( int port )\fC [virtual]\fR"
|
|
Sets the port of the URL to \fIport\fR.
|
|
.PP
|
|
See also port().
|
|
.SH "void QUrl::setProtocol ( const QString & protocol )\fC [virtual]\fR"
|
|
Sets the protocol of the URL to \fIprotocol\fR. Typically, "file"," http", "ftp", etc.
|
|
.PP
|
|
See also protocol().
|
|
.SH "void QUrl::setQuery ( const QString & txt )\fC [virtual]\fR"
|
|
Sets the query of the URL to \fItxt\fR. \fItxt\fR must be encoded.
|
|
.PP
|
|
See also query() and encode().
|
|
.SH "void QUrl::setRef ( const QString & txt )\fC [virtual]\fR"
|
|
Sets the reference of the URL to \fItxt\fR. \fItxt\fR must be encoded.
|
|
.PP
|
|
See also ref(), hasRef(), and encode().
|
|
.SH "void QUrl::setUser ( const QString & user )\fC [virtual]\fR"
|
|
Sets the username of the URL to \fIuser\fR.
|
|
.PP
|
|
See also user() and setPassword().
|
|
.SH "QString QUrl::toString ( bool encodedPath = FALSE, bool forcePrependProtocol = TRUE ) const\fC [virtual]\fR"
|
|
Composes a string version of the URL and returns it. If \fIencodedPath\fR is TRUE the path in the returned string is encoded. If \fIforcePrependProtocol\fR is TRUE and \fIencodedPath\fR looks like a local filename, the "file:/" protocol is also prepended.
|
|
.PP
|
|
See also encode() and decode().
|
|
.SH "QString QUrl::user () const"
|
|
Returns the username of the URL.
|
|
.PP
|
|
See also setUser() and setPassword().
|
|
|
|
.SH "SEE ALSO"
|
|
.BR http://doc.trolltech.com/qurl.html
|
|
.BR http://www.trolltech.com/faq/tech.html
|
|
.SH COPYRIGHT
|
|
Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
|
|
license file included in the distribution for a complete license
|
|
statement.
|
|
.SH AUTHOR
|
|
Generated automatically from the source code.
|
|
.SH BUGS
|
|
If you find a bug in Qt, please report it as described in
|
|
.BR http://doc.trolltech.com/bughowto.html .
|
|
Good bug reports help us to help you. Thank you.
|
|
.P
|
|
The definitive Qt documentation is provided in HTML format; it is
|
|
located at $QTDIR/doc/html and can be read using Qt Assistant or with
|
|
a web browser. This man page is provided as a convenience for those
|
|
users who prefer man pages, although this format is not officially
|
|
supported by Trolltech.
|
|
.P
|
|
If you find errors in this manual page, please report them to
|
|
.BR qt-bugs@trolltech.com .
|
|
Please include the name of the manual page (qurl.3qt) and the Qt
|
|
version (3.3.8).
|