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 3792241a2bfe4862af4106aab330ba155e4b9bc6..b81c247ac0bf1a11f975bf28d58aef0626b2fe98 100644 (file)
--- a/docs/latex/wx/uri.tex
+++ b/docs/latex/wx/uri.tex
@@ -15,13 +15,15 @@ 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.
 wxURI supports copy construction and standard assignment
 operators.  wxURI can also be inherited from to provide
 furthur functionality.


@@ -32,17 +34,17 @@ furthur functionality.
 
 \wxheading{Include files}
 
 
 \wxheading{Include files}
 

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

 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \membersection{Obtaining individual components}\label{obtainingwxuricomponents}
 
 To obtain individual components you can use 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \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{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}


@@ -92,7 +104,7 @@ Copies this URI from another URI.
 
 \constfunc{wxString}{BuildURI}{\void}
 
 
 \constfunc{wxString}{BuildURI}{\void}
 

-Builds the URI from its individual components and adds proper seperators.
+Builds the URI from its individual components and adds proper separators.

 
 If the URI is not a reference or is not resolved, 
 the URI that is returned from Get is the same one 
 
 If the URI is not a reference or is not resolved, 
 the URI that is returned from Get is the same one 


@@ -103,19 +115,22 @@ passed to Create.
 
 \constfunc{wxString}{BuildUnescapedURI}{\void}
 
 
 \constfunc{wxString}{BuildUnescapedURI}{\void}
 

-Builds the URI from its individual components, adds proper seperators, and
+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
 returns escape sequences to normal characters.
 
 Note that it is preferred to call this over Unescape(BuildURI()) since

-BuildUnescapedURI performs some optimizations over the plain method.
+\helpref{BuildUnescapedURI}{wxuribuildunescapeduri} performs some optimizations over the plain method.

 
 
 \membersection{wxURI::Create}\label{wxuricreate}
 
 
 
 \membersection{wxURI::Create}\label{wxuricreate}
 

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

 
 Creates this URI from the string \arg{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}
 
 
 \docparam{uri}{string to initialize from}
 
 


@@ -146,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}


@@ -219,12 +246,24 @@ 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}
 
 
 \membersection{wxURI::HasFragment}\label{wxurihasfragment}
 


@@ -232,12 +271,14 @@ that is postfixed by a '@' character.
 
 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.
 
 \membersection{wxURI::HasPath}\label{wxurihaspath}
 
 \constfunc{bool}{HasPath}{\void}
 
 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}


@@ -266,7 +307,7 @@ Returns \true if the Scheme component of the URI exists.
 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}
 


@@ -309,8 +350,8 @@ 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}
 
 \membersection{wxURI::Unescape}\label{wxuriunescape}
 to 2396}
 
 \membersection{wxURI::Unescape}\label{wxuriunescape}


@@ -320,9 +361,9 @@ to 2396}
 Translates all escape sequences (% hex hex) of \arg{uri} into
 normal characters and returns the result.
 
 Translates all escape sequences (% hex hex) of \arg{uri} into
 normal characters and returns the result.
 

-This is the preferred over wxURL::ConvertFromURI.
+This is the preferred over deprecated wxURL::ConvertFromURI.

 
 

-If you want to unescape an entire wxURI, use BuildUnescapedURI instead,
+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}
 as it performs some optimizations over this method.
 
 \docparam{uri}{string with escaped characters to convert}