diff options
Diffstat (limited to 'doc/man/man3/qurl.3qt')
| -rw-r--r-- | doc/man/man3/qurl.3qt | 496 |
1 files changed, 496 insertions, 0 deletions
diff --git a/doc/man/man3/qurl.3qt b/doc/man/man3/qurl.3qt new file mode 100644 index 000000000..579bed77f --- /dev/null +++ b/doc/man/man3/qurl.3qt @@ -0,0 +1,496 @@ +'\" 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 retquires 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). |