X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/23324ae1c7938ba904770fc456d3c07764b9c5e9..de536319f16406adf967003637b2655c61f6cb09:/interface/url.h diff --git a/interface/url.h b/interface/url.h index ff1ed7915d..3d7eea0c99 100644 --- a/interface/url.h +++ b/interface/url.h @@ -1,110 +1,96 @@ ///////////////////////////////////////////////////////////////////////////// // 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). - - Supports standard assignment operators, copy constructors, - and comparison operators. - + + 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. + @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). - - @param url - Url string to parse. + 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. */ -#define wxURL(const wxString& url = wxEmptyString) /* implementation is private */ + wxURL(const wxString& url = wxEmptyString); /** Destroys the URL object. */ -#define ~wxURL() /* implementation is private */ + ~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 - yourself. - - @sa wxInputStream + + @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(); + wxInputStream* GetInputStream(); /** Returns a reference to the protocol which will be used to get the URL. @@ -112,32 +98,33 @@ public: wxProtocol GetProtocol(); /** - Returns @true if this object is correctly initialized, i.e. if - GetError() returns @c wxURL_NOERR. + Returns @true if this object is correctly initialized, i.e. if + GetError() returns ::wxURL_NOERR. */ -#define bool IsOk() /* implementation is private */ + bool IsOk() const; /** - Sets the default proxy server to use to get the URL. The string specifies - the proxy like this: hostname:port number. - - @param url_proxy - Specifies the proxy to use - - @sa SetProxy() + 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. + + @see SetProxy() */ static void SetDefaultProxy(const wxString& url_proxy); /** Sets the proxy to use for this URL. - - @sa SetDefaultProxy() + + @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). */ -#define wxURLError SetURL(const wxString& url) /* implementation is private */ + wxURLError SetURL(const wxString& url); }; +