X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/dd65d8c83003ebbf9ab3275957fefa8cd7c87cc3..d9605e634b503651fd349a3d2c6781b2407ea273:/docs/latex/wx/uri.tex diff --git a/docs/latex/wx/uri.tex b/docs/latex/wx/uri.tex index 80377111bc..ee47d04936 100644 --- a/docs/latex/wx/uri.tex +++ b/docs/latex/wx/uri.tex @@ -15,37 +15,14 @@ wxURI is used to extract information from 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 @@ -53,32 +30,40 @@ furthur functionality. \wxheading{Derived from} -No base class +\helpref{wxObject}{wxobject} \wxheading{Include files} - + + +\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}\\ @@ -94,53 +79,64 @@ if(myuri.HasScheme()) 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} @@ -169,6 +165,18 @@ wxURI::HostType: \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://:@mysite.com/mypath} + + \membersection{wxURI::GetPath}\label{wxurigetpath} \constfunc{const wxString&}{GetPath}{\void} @@ -242,101 +250,96 @@ server component. \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://:@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://@mysite.com/mypath} +\tt{http://@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 @@ -351,6 +354,22 @@ of the base's is merged with this URI's path, resulting in the URI "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} +