interface/wx/protocol/protocol.h

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