Updating MSW file list.

[wxWidgets.git] / docs / latex / wx / uri.tex

diff --git a/docs/latex/wx/uri.tex b/docs/latex/wx/uri.tex
index 5b1bfab4bb3afeffebdc5e9f0b0e8b499ee94c08..b81c247ac0bf1a11f975bf28d58aef0626b2fe98 100644 (file)
--- a/docs/latex/wx/uri.tex
+++ b/docs/latex/wx/uri.tex
@@ -15,34 +15,36 @@ wxURI is used to extract information from
 a URI (Uniform Resource Identifier).
 
 For information about URIs, see 
 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 - all 
 acceptable URLs are also acceptable URIs.
 
 
 In short, a URL \em{is} a URI.  In other
 words, URL is a subset of a URI - all 
 acceptable URLs are also acceptable URIs.
 

+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
 furthur functionality.
 
 \wxheading{Derived from}
 
 wxURI supports copy construction and standard assignment
 operators.  wxURI can also be inherited from to provide
 furthur functionality.
 
 \wxheading{Derived from}
 

-No base class
+\helpref{wxObject}{wxobject}

 
 \wxheading{Include files}
 
 
 \wxheading{Include files}
 

-<uri.h>
+<wx/uri.h>

 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{Obtaining individual components}
+\membersection{Obtaining individual components}\label{obtainingwxuricomponents}

 
 To obtain individual components you can use 
 
 To obtain individual components you can use 

-one of the following methods:
+one of the following methods

 
 \helpref{GetScheme}{wxurigetscheme}\\
 
 \helpref{GetScheme}{wxurigetscheme}\\

-\helpref{GetUser}{wxurigetuser}\\
+\helpref{GetUserInfo}{wxurigetuserinfo}\\

 \helpref{GetServer}{wxurigetserver}\\
 \helpref{GetPort}{wxurigetserver}\\
 \helpref{GetPath}{wxurigetpath}\\
 \helpref{GetServer}{wxurigetserver}\\
 \helpref{GetPort}{wxurigetserver}\\
 \helpref{GetPath}{wxurigetpath}\\


@@ -50,10 +52,14 @@ one of the following methods:
 \helpref{GetFragment}{wxurigetfragment}
 
 However, you should check HasXXX before
 \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{HasScheme}{wxurihasscheme}\\

-\helpref{HasUser}{wxurihasuser}\\
+\helpref{HasUserInfo}{wxurihasuserinfo}\\

 \helpref{HasServer}{wxurihasserver}\\
 \helpref{HasPort}{wxurihasserver}\\
 \helpref{HasPath}{wxurihaspath}\\
 \helpref{HasServer}{wxurihasserver}\\
 \helpref{HasPort}{wxurihasserver}\\
 \helpref{HasPath}{wxurihaspath}\\


@@ -69,6 +75,12 @@ if(myuri.HasScheme())
    protocol = myuri.GetScheme();
 \end{verbatim}
 
    protocol = myuri.GetScheme();
 \end{verbatim}
 

+\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}
 \membersection{wxURI::wxURI}\label{wxuriwxuri}
 
 \func{}{wxURI}{\void}


@@ -88,23 +100,39 @@ Copies this URI from another URI.
 \docparam{uri}{URI (Uniform Resource Identifier) to initialize with}
 
 
 \docparam{uri}{URI (Uniform Resource Identifier) to initialize with}
 
 

-\membersection{wxURI::Create}\label{wxuricreate}
+\membersection{wxURI::BuildURI}\label{wxuribuilduri}

 
 

-\func{void}{Create}{\param{const wxChar* }{uri}}
+\constfunc{wxString}{BuildURI}{\void}

 
 

-Creates this URI from the string {\tt 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}
 
 
 \membersection{wxURI::GetFragment}\label{wxurigetfragment}
 


@@ -133,6 +161,18 @@ wxURI::HostType:
 \twocolitem{{\bf wxURI\_IPVFUTURE}}{Server is an IP address, but not versions 4 or 6}
 \end{twocollist}
 
 \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}
 \membersection{wxURI::GetPath}\label{wxurigetpath}
 
 \constfunc{const wxString&}{GetPath}{\void}


@@ -206,75 +246,89 @@ server component.
 
 \constfunc{const wxString&}{GetUser}{\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.
 
 
 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}
 
 
 \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}
 
 
 \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}
 
 
 \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}
 
 
 
 \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}
 
 
 
 \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}
 
 
 
 \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}
 
 
 \constfunc{bool}{HasUser}{\void}
 

-Returns true if the User component of the URI exists.
+Returns \true if the User component of the URI exists.

 
 
 \membersection{wxURI::IsReference}\label{wxuriisreference}
 
 \constfunc{bool}{IsReference}{\void}
 
 
 
 \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
 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}}
 
 
 
 \membersection{wxURI::operator ==}\label{wxurioperatorcompare}
 
 \func{void}{operator ==}{\param{const wxURI\& }{uricomp}}
 

-Compares this URI to another URI, and returns true if 
-this URI equals {\tt 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}
 
 
 \docparam{uricomp}{URI to compare to}
 


@@ -296,7 +350,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}
 "http://mysite.com/john/mydir".
 
 \docparam{base}{Base URI to inherit from.  Must be a full URI and not a reference}

-\docparam{flags}{Currently either \texttt{wxURI\_STRICT} or $0$, in non strict
-mode some compatability layers are enabled to allow loopholes from RFCs prior
+\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}
 
 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}
+
+