interface/url.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        url.h
   3 // Purpose:     interface of wxURL
   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     @see wxSocketBase, wxProtocol
  25 */
  26 class wxURL : public wxURI
  27 {
  28 public:
  29     /**
  30         Constructs a URL object from the string.  The URL must be valid according
  31         to RFC 1738.  In particular, file URLs must be of the format
  32         @c file://hostname/path/to/file otherwise GetError()
  33         will return a value different from @c wxURL_NOERR.
  34         It is valid to leave out the hostname but slashes must remain in place -
  35         i.e. a file URL without a hostname must contain three consecutive slashes
  36         (e.g. @c file:///somepath/myfile).
  37
  38         @param url
  39             Url string to parse.
  40     */
  41     wxURL(const wxString& url = wxEmptyString);
  42
  43     /**
  44         Destroys the URL object.
  45     */
  46     ~wxURL();
  47
  48     /**
  49         Returns the last error. This error refers to the URL parsing or to the protocol.
  50         It can be one of these errors:
  51
  52         @b wxURL_NOERR
  53
  54         No error.
  55
  56         @b wxURL_SNTXERR
  57
  58         Syntax error in the URL string.
  59
  60         @b wxURL_NOPROTO
  61
  62         Found no protocol which can get this URL.
  63
  64         @b wxURL_NOHOST
  65
  66         A host name is required for this protocol.
  67
  68         @b wxURL_NOPATH
  69
  70         A path is required for this protocol.
  71
  72         @b wxURL_CONNERR
  73
  74         Connection error.
  75
  76         @b wxURL_PROTOERR
  77
  78         An error occurred during negotiation.
  79     */
  80     wxURLError GetError() const;
  81
  82     /**
  83         Creates a new input stream on the specified URL. You can use all but seek
  84         functionality of wxStream. Seek isn't available on all streams. For example,
  85         HTTP or FTP streams don't deal with it.
  86         Note that this method is somewhat deprecated, all future wxWidgets applications
  87         should really use wxFileSystem instead.
  88         Example:
  89
  90         @returns Returns the initialized stream. You will have to delete it
  91                  yourself.
  92
  93         @see wxInputStream
  94     */
  95     wxInputStream* GetInputStream();
  96
  97     /**
  98         Returns a reference to the protocol which will be used to get the URL.
  99     */
 100     wxProtocol GetProtocol();
 101
 102     /**
 103         Returns @true if this object is correctly initialized, i.e. if
 104         GetError() returns @c wxURL_NOERR.
 105     */
 106     bool IsOk() const;
 107
 108     /**
 109         Sets the default proxy server to use to get the URL. The string specifies
 110         the proxy like this: hostname:port number.
 111
 112         @param url_proxy
 113             Specifies the proxy to use
 114
 115         @see SetProxy()
 116     */
 117     static void SetDefaultProxy(const wxString& url_proxy);
 118
 119     /**
 120         Sets the proxy to use for this URL.
 121
 122         @see SetDefaultProxy()
 123     */
 124     void SetProxy(const wxString& url_proxy);
 125
 126     /**
 127         Initializes this object with the given URL and returns @c wxURL_NOERR
 128         if it's valid (see GetError() for more info).
 129     */
 130     wxURLError SetURL(const wxString& url);
 131 };
 132