/////////////////////////////////////////////////////////////////////////////
// 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.
*/
~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();
/**
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 "<hostname>:<port number>".
+
@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);
};
+
projects / wxWidgets.git / blobdiff