X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..7bf2b0881a6bf28138f258504e88b2643daa854e:/interface/url.h diff --git a/interface/url.h b/interface/url.h index 070c044e0c..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). + 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. + 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. @@ -113,31 +99,32 @@ public: /** Returns @true if this object is correctly initialized, i.e. if - GetError() returns @c wxURL_NOERR. + 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. - + 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 - - @sa SetProxy() + 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); }; +