X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4cc4bfafe5a31cb96f35b3ec9b19fa2b0b3a4eef..63b37a4e648320827a5b4a3161be13154370b5c3:/interface/url.h?ds=sidebyside diff --git a/interface/url.h b/interface/url.h index dceb2096d1..3d7eea0c99 100644 --- a/interface/url.h +++ b/interface/url.h @@ -1,41 +1,53 @@ ///////////////////////////////////////////////////////////////////////////// // Name: url.h -// Purpose: documentation for wxURL class +// Purpose: interface of wxURL // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + Error types returned from wxURL::GetError(). +*/ +typedef enum { + wxURL_NOERR = 0, ///< No error. + wxURL_SNTXERR, ///< Syntax error in the URL string. + wxURL_NOPROTO, ///< Found no protocol which can get this URL. + wxURL_NOHOST, ///< A host name is required for this protocol. + wxURL_NOPATH, ///< A path is required for this protocol. + wxURL_CONNERR, ///< Connection error. + wxURL_PROTOERR ///< An error occurred during negotiation. +} wxURLError; + /** @class wxURL @wxheader{url.h} - wxURL is a specialization of wxURI for parsing URLs. - Please look at wxURI documentation for more info about the functions - you can use to retrieve the various parts of the URL (scheme, server, port, - etc). + wxURL is a specialization of wxURI for parsing URLs. Please look at wxURI + documentation for more info about the functions you can use to retrieve the + various parts of the URL (scheme, server, port, etc). - Supports standard assignment operators, copy constructors, - and comparison operators. + Supports standard assignment operators, copy constructors, and comparison + operators. @library{wxnet} @category{net} - @seealso - wxSocketBase, wxProtocol + @see wxSocketBase, wxProtocol */ class wxURL : public wxURI { public: /** - Constructs a URL object from the string. The URL must be valid according - to RFC 1738. In particular, file URLs must be of the format - @c file://hostname/path/to/file otherwise GetError() - will return a value different from @c wxURL_NOERR. - It is valid to leave out the hostname but slashes must remain in place - - i.e. a file URL without a hostname must contain three consecutive slashes - (e.g. @c file:///somepath/myfile). - + Constructs a URL object from the string. The URL must be valid + according to RFC 1738. In particular, file URLs must be of the format + @c "file://hostname/path/to/file", otherwise GetError() will return a + value different from ::wxURL_NOERR. + + It is valid to leave out the hostname but slashes must remain in place, + in other words, a file URL without a hostname must contain three + consecutive slashes (e.g. @c "file:///somepath/myfile"). + @param url Url string to parse. */ @@ -47,50 +59,35 @@ public: ~wxURL(); /** - Returns the last error. This error refers to the URL parsing or to the protocol. - It can be one of these errors: - - @b wxURL_NOERR - - No error. - - @b wxURL_SNTXERR - - Syntax error in the URL string. - - @b wxURL_NOPROTO - - Found no protocol which can get this URL. - - @b wxURL_NOHOST - - A host name is required for this protocol. - - @b wxURL_NOPATH - - A path is required for this protocol. - - @b wxURL_CONNERR - - Connection error. - - @b wxURL_PROTOERR - - An error occurred during negotiation. + Returns the last error. This error refers to the URL parsing or to the + protocol. It can be one of ::wxURLError. */ - wxURLError GetError(); + wxURLError GetError() const; /** - Creates a new input stream on the specified URL. You can use all but seek - functionality of wxStream. Seek isn't available on all streams. For example, - HTTP or FTP streams don't deal with it. - Note that this method is somewhat deprecated, all future wxWidgets applications - should really use wxFileSystem instead. + Creates a new input stream on the specified URL. You can use all but + seek functionality of wxStream. Seek isn't available on all streams. + For example, HTTP or FTP streams don't deal with it. + + Note that this method is somewhat deprecated, all future wxWidgets + applications should use wxFileSystem instead. + Example: - - @returns Returns the initialized stream. You will have to delete it + + @code + wxURL url("http://a.host/a.dir/a.file"); + if (url.GetError() == wxURL_NOERR) + { + wxInputStream *in_stream; + + in_stream = url.GetInputStream(); + // Then, you can use all IO calls of in_stream (See wxStream) + } + @endcode + + @return Returns the initialized stream. You will have to delete it yourself. - + @see wxInputStream */ wxInputStream* GetInputStream(); @@ -102,31 +99,32 @@ public: /** Returns @true if this object is correctly initialized, i.e. if - GetError() returns @c wxURL_NOERR. + GetError() returns ::wxURL_NOERR. */ - bool IsOk(); + bool IsOk() const; /** - Sets the default proxy server to use to get the URL. The string specifies - the proxy like this: hostname:port number. - + Sets the default proxy server to use to get the URL. The string + specifies the proxy like this: @c ":". + @param url_proxy - Specifies the proxy to use - + Specifies the proxy to use. + @see SetProxy() */ static void SetDefaultProxy(const wxString& url_proxy); /** Sets the proxy to use for this URL. - + @see SetDefaultProxy() */ void SetProxy(const wxString& url_proxy); /** - Initializes this object with the given URL and returns @c wxURL_NOERR - if it's valid (see GetError() for more info). + Initializes this object with the given URL and returns ::wxURL_NOERR if + it's valid (see GetError() for more info). */ wxURLError SetURL(const wxString& url); }; +