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