interface/url.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        url.h
   3 // Purpose:     documentation for wxURL class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxURL
  11     @wxheader{url.h}
  12
  13     wxURL is a specialization of wxURI for parsing URLs.
  14     Please look at wxURI documentation for more info about the functions
  15     you can use to retrieve the various parts of the URL (scheme, server, port,
  16     etc).
  17
  18     Supports standard assignment operators, copy constructors,
  19     and comparison operators.
  20
  21     @library{wxnet}
  22     @category{net}
  23
  24     @seealso
  25     wxSocketBase, wxProtocol
  26 */
  27 class wxURL : public wxURI
  28 {
  29 public:
  30     /**
  31         Constructs a URL object from the string.  The URL must be valid according
  32         to RFC 1738.  In particular, file URLs must be of the format
  33         @c file://hostname/path/to/file otherwise GetError()
  34         will return a value different from @c wxURL_NOERR.
  35
  36         It is valid to leave out the hostname but slashes must remain in place -
  37         i.e. a file URL without a hostname must contain three consecutive slashes
  38         (e.g. @c file:///somepath/myfile).
  39
  40         @param url
  41         Url string to parse.
  42     */
  43 #define wxURL(const wxString& url = wxEmptyString)     /* implementation is private */
  44
  45     /**
  46         Destroys the URL object.
  47     */
  48 #define ~wxURL()     /* implementation is private */
  49
  50     /**
  51         Returns the last error. This error refers to the URL parsing or to the protocol.
  52         It can be one of these errors:
  53
  54
  55         @b wxURL_NOERR
  56
  57
  58         No error.
  59
  60         @b wxURL_SNTXERR
  61
  62
  63         Syntax error in the URL string.
  64
  65         @b wxURL_NOPROTO
  66
  67
  68         Found no protocol which can get this URL.
  69
  70         @b wxURL_NOHOST
  71
  72
  73         A host name is required for this protocol.
  74
  75         @b wxURL_NOPATH
  76
  77
  78         A path is required for this protocol.
  79
  80         @b wxURL_CONNERR
  81
  82
  83         Connection error.
  84
  85         @b wxURL_PROTOERR
  86
  87
  88         An error occurred during negotiation.
  89     */
  90     wxURLError GetError();
  91
  92     /**
  93         Creates a new input stream on the specified URL. You can use all but seek
  94         functionality of wxStream. Seek isn't available on all streams. For example,
  95         HTTP or FTP streams don't deal with it.
  96
  97         Note that this method is somewhat deprecated, all future wxWidgets applications
  98         should really use wxFileSystem instead.
  99
 100         Example:
 101
 102         @returns Returns the initialized stream. You will have to delete it
 103                    yourself.
 104
 105         @sa wxInputStream
 106     */
 107     wxInputStream * GetInputStream();
 108
 109     /**
 110         Returns a reference to the protocol which will be used to get the URL.
 111     */
 112     wxProtocol GetProtocol();
 113
 114     /**
 115         Returns @true if this object is correctly initialized, i.e. if
 116         GetError() returns @c wxURL_NOERR.
 117     */
 118 #define bool IsOk()     /* implementation is private */
 119
 120     /**
 121         Sets the default proxy server to use to get the URL. The string specifies
 122         the proxy like this: hostname:port number.
 123
 124         @param url_proxy
 125         Specifies the proxy to use
 126
 127         @sa SetProxy()
 128     */
 129     static void SetDefaultProxy(const wxString& url_proxy);
 130
 131     /**
 132         Sets the proxy to use for this URL.
 133
 134         @sa SetDefaultProxy()
 135     */
 136     void SetProxy(const wxString& url_proxy);
 137
 138     /**
 139         Initializes this object with the given URL and returns @c wxURL_NOERR
 140         if it's valid (see GetError() for more info).
 141     */
 142 #define wxURLError SetURL(const wxString& url)     /* implementation is private */
 143 };