interface/wx/url.h

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