a URI (Uniform Resource Identifier).
For information about URIs, see
-\urlref{RFC 2396}{http://www.ietf.org/rfc/rfc2396.txt} or
-\urlref{RFC 2396.bis (Updated draft of RFC 2396)}{http://www.gbiv.com/protocols/uri/rev-2002/rfc2396bis.html}.
+\urlref{RFC 3986}{http://www.ietf.org/rfc/rfc3986.txt}.
In short, a URL \em{is} a URI. In other
-words, URL is a subset of a URI - most
+words, URL is a subset of a URI - all
acceptable URLs are also acceptable URIs.
-wxURI can be used to validate URIs:
-\begin{verbatim}
-URI myuri;
-
-//will not print "Bad URI" because this is a valid URI
-if(!myuri.Create(("ftp://mysiteftp.com/mydir")))
- wxPrintf("Bad URI");
-
-URI mybaduri;
-
-//will print "Bad URI" because ::x:: is not a valid URI
-if(!mybaduri.Create(("::x::")))
- wxPrintf("Bad URI");
-\end{verbatim}
-
-wxURI also has some uses that may not be apparent at first,
-such as skipping past a URI in a string:
-\begin{verbatim}
-URI myuri;
-wxString mystring = wxT("http://mysite.com A Good Website");
-
-//mystring will contain " A Good Website" after URI::Create()
-mystring = myuri.Extract(mystring);
-\end{verbatim}
+wxURI automatically escapes invalid characters in a string,
+so there is no chance of wxURI "failing" on construction/creation.
wxURI supports copy construction and standard assignment
operators. wxURI can also be inherited from to provide
\wxheading{Derived from}
-No base class
+\helpref{wxObject}{wxobject}
\wxheading{Include files}
-<uri.h>
+<wx/uri.h>
+
+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+
+\wxheading{See also}
+
+\helpref{wxURL}{wxurl}
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{Obtaining individual components}
+\membersection{Obtaining individual components}\label{obtainingwxuricomponents}
To obtain individual components you can use
-one of the following methods:
+one of the following methods
\helpref{GetScheme}{wxurigetscheme}\\
-\helpref{GetUser}{wxurigetuser}\\
+\helpref{GetUserInfo}{wxurigetuserinfo}\\
\helpref{GetServer}{wxurigetserver}\\
-\helpref{GetPort}{wxurigetserver}\\
+\helpref{GetPort}{wxurigetport}\\
\helpref{GetPath}{wxurigetpath}\\
\helpref{GetQuery}{wxurigetquery}\\
\helpref{GetFragment}{wxurigetfragment}
However, you should check HasXXX before
-calling a get method:
-
+calling a get method, which determines whether or not the component referred
+to by the method is defined according to RFC 2396.
+
+Consider an undefined component equivalent to a
+NULL C string.\\
+\\
\helpref{HasScheme}{wxurihasscheme}\\
-\helpref{HasUser}{wxurihasuser}\\
+\helpref{HasUserInfo}{wxurihasuserinfo}\\
\helpref{HasServer}{wxurihasserver}\\
\helpref{HasPort}{wxurihasserver}\\
\helpref{HasPath}{wxurihaspath}\\
protocol = myuri.GetScheme();
\end{verbatim}
-Also, you can get the numeric value of the URI's port
-component by calling \helpref{GetPortValue}{wxurigetportvalue},
-and the host type of the server component by calling
-\helpref{GetHostType}{wxurigethosttype}
+\membersection{Deviations from the RFC}\label{deviationsfromrfc}
+
+Note that on URIs with a "file" scheme wxURI does not
+parse the userinfo, server, or port portion. This is to keep
+compatability with wxFileSystem, the old wxURL, and older url specifications.
\membersection{wxURI::wxURI}\label{wxuriwxuri}
\func{}{wxURI}{\void}
-Creates an empty URI. In order for the URI to be
-useful, Create needs to be called eventually.
-
-\membersection{wxURI::\destruct{wxURI}}\label{wxuridtor}
+Creates an empty URI.
\func{}{wxURI}{\param{const wxChar* }{uri}}
-Constructor for quick creation
+Constructor for quick creation.
\docparam{uri}{string to initialize with}
-
-\func{}{wxURI}{\param{const wxURI& }{uri}}
+\func{}{wxURI}{\param{const wxURI\& }{uri}}
Copies this URI from another URI.
\docparam{uri}{URI (Uniform Resource Identifier) to initialize with}
-\membersection{wxURI::Create}\label{wxuricreate}
+\membersection{wxURI::BuildURI}\label{wxuribuilduri}
-\func{const wxChar*}{Create}{\param{const wxChar* }{uri}}
+\constfunc{wxString}{BuildURI}{\void}
-Creates this URI from a string, and parses \arg{uri} for validity.
-Returns the position where parsing stopped in string,
-or false if \arg{uri} is not a valid URI.
+Builds the URI from its individual components and adds proper separators.
-\docparam{uri}{string to initialize from}
+If the URI is not a reference or is not resolved,
+the URI that is returned from Get is the same one
+passed to Create.
-\membersection{wxURI::Get}\label{wxuriget}
-\constfunc{wxString}{Get}{\void}
+\membersection{wxURI::BuildUnescapedURI}\label{wxuribuildunescapeduri}
-Obtains the full URI.
+\constfunc{wxString}{BuildUnescapedURI}{\void}
+
+Builds the URI from its individual components, adds proper separators, and
+returns escape sequences to normal characters.
+
+Note that it is preferred to call this over Unescape(BuildURI()) since
+\helpref{BuildUnescapedURI}{wxuribuildunescapeduri} performs some optimizations over the plain method.
+
+
+\membersection{wxURI::Create}\label{wxuricreate}
+
+\func{const wxChar*}{Create}{\param{const wxString&}{uri}}
+
+Creates this URI from the string \arg{uri}.
+
+Returns the position at which parsing stopped (there
+is no such thing as an "invalid" wxURI).
+
+\docparam{uri}{string to initialize from}
-If the URI is not a reference or is not resolved,
-the URI that is returned from Get is the same one
-passed to Create.
\membersection{wxURI::GetFragment}\label{wxurigetfragment}
\twocolitem{{\bf wxURI\_IPVFUTURE}}{Server is an IP address, but not versions 4 or 6}
\end{twocollist}
+
+\membersection{wxURI::GetPassword}\label{wxurigetpassword}
+
+\constfunc{const wxString&}{GetPassword}{\void}
+
+Returns the password part of the userinfo component of
+this URI. Note that this is explicitly depreciated by
+RFC 1396 and should generally be avoided if possible.
+
+\tt{http://<user>:<password>@mysite.com/mypath}
+
+
\membersection{wxURI::GetPath}\label{wxurigetpath}
\constfunc{const wxString&}{GetPath}{\void}
\constfunc{const wxString&}{GetUser}{\void}
-Returns the User component of the URI.
+Returns the username part of the userinfo component of
+this URI. Note that this is explicitly depreciated by
+RFC 1396 and should generally be avoided if possible.
+
+\tt{http://<user>:<password>@mysite.com/mypath}
+
+
+\membersection{wxURI::GetUserInfo}\label{wxurigetuserinfo}
+
+\constfunc{const wxString&}{GetUserInfo}{\void}
+
+Returns the UserInfo component of the URI.
The component of a URI before the server component
that is postfixed by a '@' character.
-\tt{http://<user>@mysite.com/mypath}
+\tt{http://<userinfo>@mysite.com/mypath}
+
\membersection{wxURI::HasFragment}\label{wxurihasfragment}
\constfunc{bool}{HasFragment}{\void}
-Returns true if the Fragment component of the URI exists.
+Returns \true if the Fragment component of the URI exists.
+
\membersection{wxURI::HasPath}\label{wxurihaspath}
\constfunc{bool}{HasPath}{\void}
-Returns true if the Path component of the URI exists.
+Returns \true if the Path component of the URI exists.
+
\membersection{wxURI::HasPort}\label{wxurihasport}
\constfunc{bool}{HasPort}{\void}
-Returns true if the Port component of the URI exists.
+Returns \true if the Port component of the URI exists.
\membersection{wxURI::HasQuery}\label{wxurihasquery}
\constfunc{bool}{HasQuery}{\void}
-Returns true if the Query component of the URI exists.
+Returns \true if the Query component of the URI exists.
\membersection{wxURI::HasScheme}\label{wxurihasscheme}
\constfunc{bool}{HasScheme}{\void}
-Returns true if the Scheme component of the URI exists.
+Returns \true if the Scheme component of the URI exists.
\membersection{wxURI::HasServer}\label{wxurihasserver}
\constfunc{bool}{HasServer}{\void}
-Returns true if the Server component of the URI exists.
+Returns \true if the Server component of the URI exists.
-\membersection{wxURI::HasUser}\label{wxurihasuser}
+\membersection{wxURI::HasUser}\label{wxurihasuserinfo}
\constfunc{bool}{HasUser}{\void}
-Returns true if the User component of the URI exists.
-
-
-\membersection{wxURI::IsOk}\label{wxuriisok}
-
-\constfunc{bool}{IsOk}{\void}
-
-Returns true if this is a valid URI.
+Returns \true if the User component of the URI exists.
\membersection{wxURI::IsReference}\label{wxuriisreference}
\constfunc{bool}{IsReference}{\void}
-Returns true if a valid [absolute] URI, otherwise this URI
+Returns \true if a valid [absolute] URI, otherwise this URI
is a URI reference and not a full URI, and IsReference
-returns false.
+returns \false.
\membersection{wxURI::operator ==}\label{wxurioperatorcompare}
-\func{void}{operator ==}{\param{const wxURI& }{uricomp}}
+\func{void}{operator ==}{\param{const wxURI\& }{uricomp}}
-Compares this URI to another URI, and returns true if
-this URI equals uricomp, otherwise it returns false.
+Compares this URI to another URI, and returns \true if
+this URI equals \arg{uricomp}, otherwise it returns \false.
\docparam{uricomp}{URI to compare to}
-\membersection{wxURI::Extract}\label{wxuriextract}
-
-\func{static const wxChar*}{Extract}{\param{const wxChar*}{uri}}
-
-Used to determine where a URI ends in a string.
-
-Returns the position at which parsing stopped
-(will return NULL on malformed URIs).
-
-\docparam{uri}{String to create from}
-
-
\membersection{wxURI::Resolve}\label{wxuriresolve}
-\func{void}{Resolve}{\param{const wxURI\& }{base}, \param{const bool\& }{bStrict = true}}
+\func{void}{Resolve}{\param{const wxURI\& }{base}, \param{int }{flags = \texttt{wxURI\_STRICT}}}
Inherits this URI from a base URI - components that do not
exist in this URI are copied from the base, and if this URI's
"http://mysite.com/john/mydir".
\docparam{base}{Base URI to inherit from. Must be a full URI and not a reference}
-\docparam{bStrict}{If false, some compatability layers are enabled to allow
- loopholes from RFCs prior to 2396}
+\docparam{flags}{Currently either \texttt{wxURI\_STRICT} or $0$, in non-strict
+mode some compatibility layers are enabled to allow loopholes from RFCs prior
+to 2396}
+
+\membersection{wxURI::Unescape}\label{wxuriunescape}
+
+\func{wxString}{Unescape}{\param{const wxString\& }{uri}}
+
+Translates all escape sequences (% hex hex) of \arg{uri} into
+normal characters and returns the result.
+
+This is the preferred over deprecated wxURL::ConvertFromURI.
+
+If you want to unescape an entire wxURI, use \helpref{BuildUnescapedURI}{wxuribuildunescapeduri} instead,
+as it performs some optimizations over this method.
+
+\docparam{uri}{string with escaped characters to convert}
+
projects / wxWidgets.git / blobdiff