interface/wx/protocol/protocol.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/protocol/protocol.h
   3 // Purpose:     interface of wxProtocol
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     Error values returned by wxProtocol.
  11 */
  12 enum wxProtocolError
  13 {
  14     wxPROTO_NOERR = 0,          //!< No error.
  15     wxPROTO_NETERR,             //!< A generic network error occurred.
  16     wxPROTO_PROTERR,            //!< An error occurred during negotiation.
  17     wxPROTO_CONNERR,            //!< The client failed to connect the server.
  18     wxPROTO_INVVAL,             //!< Invalid value.
  19     wxPROTO_NOHNDLR,            //!< Not currently used.
  20     wxPROTO_NOFILE,             //!< The remote file doesn't exist.
  21     wxPROTO_ABRT,               //!< Last action aborted.
  22     wxPROTO_RCNCT,              //!< An error occurred during reconnection.
  23     wxPROTO_STREAMING           //!< Someone tried to send a command during a transfer.
  24 };
  25
  26 /**
  27     @class wxProtocol
  28
  29     Represents a protocol for use with wxURL.
  30
  31     Note that you may want to change the default time-out for HTTP/FTP connections
  32     and network operations (using SetDefaultTimeout()) since the default time-out
  33     value is quite long (60 seconds).
  34
  35     @library{wxnet}
  36     @category{net}
  37
  38     @see wxSocketBase, wxURL
  39 */
  40 class wxProtocol : public wxSocketClient
  41 {
  42 public:
  43     /**
  44         Abort the current stream.
  45
  46         @warning
  47         It is advised to destroy the input stream instead of aborting the stream
  48         this way.
  49
  50         @return Returns @true, if successful, else @false.
  51     */
  52     virtual bool Abort() = 0;
  53
  54     /**
  55         Returns the type of the content of the last opened stream. It is a mime-type.
  56         May be an empty string if the content-type is unknown.
  57     */
  58     virtual wxString GetContentType() const;
  59
  60     /**
  61         Returns the last occurred error.
  62
  63         @see wxProtocolError
  64     */
  65     virtual wxProtocolError GetError() const;
  66
  67     /**
  68         Creates a new input stream on the specified path.
  69
  70         You can use all but seek() functionality of wxStream.
  71         Seek() isn't available on all streams. For example, HTTP or FTP streams
  72         don't deal with it. Other functions like StreamSize() and Tell() aren't
  73         available for the moment for this sort of stream.
  74         You will be notified when the EOF is reached by an error.
  75
  76         @return Returns the initialized stream. You will have to delete it
  77                  yourself once you don't use it anymore. The destructor
  78                  closes the network connection.
  79
  80         @see wxInputStream
  81     */
  82     virtual wxInputStream* GetInputStream(const wxString& path) = 0;
  83
  84     /**
  85         Tries to reestablish a previous opened connection (close and renegotiate
  86         connection).
  87
  88         @return @true, if the connection is established, else @false.
  89     */
  90     bool Reconnect();
  91
  92     /**
  93         Sets the authentication password.
  94     */
  95     virtual void SetPassword(const wxString& user);
  96
  97     /**
  98         Sets the authentication user.
  99     */
 100     virtual void SetUser(const wxString& user);
 101
 102     /**
 103         Sets a new default timeout for the network operations.
 104
 105         The default timeout is 60 seconds.
 106
 107         @see wxSocketBase::SetTimeout
 108     */
 109     void SetDefaultTimeout(wxUint32 Value);
 110
 111     /**
 112         @name Logging support.
 113
 114         Each wxProtocol object may have the associated logger (by default there
 115         is none) which is used to log network requests and responses.
 116
 117         @see wxProtocolLog
 118     */
 119     //@{
 120
 121     /**
 122         Set the logger, deleting the old one and taking ownership of this one.
 123
 124         @param log
 125             New logger allocated on the heap or @NULL.
 126      */
 127     void SetLog(wxProtocolLog *log);
 128
 129     /**
 130         Return the current logger, may be @NULL.
 131      */
 132     wxProtocolLog *GetLog() const { return m_log; }
 133
 134     /**
 135         Detach the existing logger without deleting it.
 136
 137         The caller is responsible for deleting the returned pointer if it's
 138         non-@c NULL.
 139      */
 140     wxProtocolLog *DetachLog();
 141
 142     /**
 143         Call wxProtocolLog::LogRequest() if we have a valid logger or do
 144         nothing otherwise.
 145      */
 146     void LogRequest(const wxString& str);
 147
 148     /**
 149         Call wxProtocolLog::LogResponse() if we have a valid logger or do
 150         nothing otherwise.
 151      */
 152     void LogResponse(const wxString& str);
 153
 154     //@}
 155 };
 156