include/wx/ipcbase.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        ipcbase.h
   3 // Purpose:     Base classes for IPC
   4 // Author:      Julian Smart
   5 // Modified by:
   6 // Created:     4/1/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Julian Smart
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_IPCBASEH__
  13 #define _WX_IPCBASEH__
  14
  15 #include "wx/defs.h"
  16 #include "wx/object.h"
  17 #include "wx/string.h"
  18
  19 enum wxIPCFormat
  20 {
  21   wxIPC_INVALID =          0,
  22   wxIPC_TEXT =             1,  /* CF_TEXT */
  23   wxIPC_BITMAP =           2,  /* CF_BITMAP */
  24   wxIPC_METAFILE =         3,  /* CF_METAFILEPICT */
  25   wxIPC_SYLK =             4,
  26   wxIPC_DIF =              5,
  27   wxIPC_TIFF =             6,
  28   wxIPC_OEMTEXT =          7,  /* CF_OEMTEXT */
  29   wxIPC_DIB =              8,  /* CF_DIB */
  30   wxIPC_PALETTE =          9,
  31   wxIPC_PENDATA =          10,
  32   wxIPC_RIFF =             11,
  33   wxIPC_WAVE =             12,
  34   wxIPC_UTF16TEXT =        13, /* CF_UNICODE */
  35   wxIPC_ENHMETAFILE =      14,
  36   wxIPC_FILENAME =         15, /* CF_HDROP */
  37   wxIPC_LOCALE =           16,
  38   wxIPC_UTF8TEXT =         17,
  39   wxIPC_UTF32TEXT =        18,
  40 #if SIZEOF_WCHAR_T == 2
  41   wxIPC_UNICODETEXT = wxIPC_UTF16TEXT,
  42 #elif SIZEOF_WCHAR_T == 4
  43   wxIPC_UNICODETEXT = wxIPC_UTF32TEXT,
  44 #else
  45 #  error "Unknown wchar_t size"
  46 #endif
  47   wxIPC_PRIVATE =          20
  48 };
  49
  50 class WXDLLIMPEXP_FWD_BASE wxServerBase;
  51 class WXDLLIMPEXP_FWD_BASE wxClientBase;
  52
  53 class WXDLLIMPEXP_BASE wxConnectionBase: public wxObject
  54 {
  55 public:
  56   wxConnectionBase(void *buffer, size_t size); // use external buffer
  57   wxConnectionBase(); // use internal, adaptive buffer
  58   wxConnectionBase(const wxConnectionBase& copy);
  59   virtual ~wxConnectionBase();
  60
  61   void SetConnected( bool c ) { m_connected = c; }
  62   bool GetConnected() { return m_connected; }
  63
  64   // Calls that CLIENT can make
  65   bool Execute(const void *data, size_t size, wxIPCFormat fmt = wxIPC_PRIVATE)
  66       { return DoExecute(data, size, fmt); }
  67   bool Execute(const char *s, size_t size = wxNO_LEN)
  68       { return DoExecute(s, size == wxNO_LEN ? strlen(s) + 1
  69                                              : size, wxIPC_TEXT); }
  70   bool Execute(const wchar_t *ws, size_t size = wxNO_LEN)
  71       { return DoExecute(ws, size == wxNO_LEN ? (wcslen(ws) + 1)*sizeof(wchar_t)
  72                                               : size, wxIPC_UNICODETEXT); }
  73   bool Execute(const wxString& s)
  74   {
  75       const wxUTF8Buf buf = s.utf8_str();
  76       return DoExecute(buf, strlen(buf) + 1, wxIPC_UTF8TEXT);
  77   }
  78   bool Execute(const wxCStrData& cs)
  79       { return Execute(cs.AsString()); }
  80
  81   virtual const void *Request(const wxString& item,
  82                               size_t *size = NULL,
  83                               wxIPCFormat format = wxIPC_TEXT) = 0;
  84
  85   bool Poke(const wxString& item, const void *data, size_t size,
  86             wxIPCFormat fmt = wxIPC_PRIVATE)
  87       { return DoPoke(item, data, size, fmt); }
  88   bool Poke(const wxString& item, const char *s, size_t size = wxNO_LEN)
  89       { return DoPoke(item, s, size == wxNO_LEN ? strlen(s) + 1
  90                                                 : size, wxIPC_TEXT); }
  91   bool Poke(const wxString& item, const wchar_t *ws, size_t size = wxNO_LEN)
  92       { return DoPoke(item, ws,
  93                       size == wxNO_LEN ? (wcslen(ws) + 1)*sizeof(wchar_t)
  94                                        : size, wxIPC_UNICODETEXT); }
  95   bool Poke(const wxString& item, const wxString s)
  96   {
  97       const wxUTF8Buf buf = s.utf8_str();
  98       return DoPoke(item, buf,  strlen(buf) + 1, wxIPC_UTF8TEXT);
  99   }
 100   bool Poke(const wxString& item, const wxCStrData& cs)
 101       { return Poke(item, cs.AsString()); }
 102
 103   virtual bool StartAdvise(const wxString& item) = 0;
 104   virtual bool StopAdvise(const wxString& item) = 0;
 105
 106   // Calls that SERVER can make
 107   bool Advise(const wxString& item, const void *data, size_t size,
 108               wxIPCFormat fmt = wxIPC_PRIVATE)
 109       { return DoAdvise(item, data, size, fmt); }
 110   bool Advise(const wxString& item, const char *s, size_t size = wxNO_LEN)
 111       { return DoAdvise(item, s, size == wxNO_LEN ? strlen(s) + 1
 112                                                   : size, wxIPC_TEXT); }
 113   bool Advise(const wxString& item, const wchar_t *ws, size_t size = wxNO_LEN)
 114       { return DoAdvise(item, ws,
 115                         size == wxNO_LEN ? (wcslen(ws) + 1)*sizeof(wchar_t)
 116                                          : size, wxIPC_UNICODETEXT); }
 117   bool Advise(const wxString& item, const wxString s)
 118   {
 119       const wxUTF8Buf buf = s.utf8_str();
 120       return DoAdvise(item, buf,  strlen(buf) + 1, wxIPC_UTF8TEXT);
 121   }
 122   bool Advise(const wxString& item, const wxCStrData& cs)
 123       { return Advise(item, cs.AsString()); }
 124
 125   // Calls that both can make
 126   virtual bool Disconnect() = 0;
 127
 128
 129   // Callbacks to SERVER - override at will
 130   virtual bool OnExec(const wxString& WXUNUSED(topic),
 131                       const wxString& WXUNUSED(data))
 132   {
 133       wxFAIL_MSG( "This method shouldn't be called, if it is, it probably "
 134                   "means that you didn't update your old code overriding "
 135                   "OnExecute() to use the new parameter types (\"const void *\" "
 136                   "instead of \"wxChar *\" and \"size_t\" instead of \"int\"), "
 137                   "you must do it or your code wouldn't be executed at all!" );
 138       return false;
 139   }
 140
 141   // deprecated function kept for backwards compatibility: usually you will
 142   // want to override OnExec() above instead which receives its data in a more
 143   // convenient format
 144   virtual bool OnExecute(const wxString& topic,
 145                          const void *data,
 146                          size_t size,
 147                          wxIPCFormat format)
 148       { return OnExec(topic, GetTextFromData(data, size, format)); }
 149
 150   virtual const void *OnRequest(const wxString& WXUNUSED(topic),
 151                                 const wxString& WXUNUSED(item),
 152                                 size_t *size,
 153                                 wxIPCFormat WXUNUSED(format))
 154       { *size = 0; return NULL; }
 155
 156   virtual bool OnPoke(const wxString& WXUNUSED(topic),
 157                       const wxString& WXUNUSED(item),
 158                       const void *WXUNUSED(data),
 159                       size_t WXUNUSED(size),
 160                       wxIPCFormat WXUNUSED(format))
 161       { return false; }
 162
 163   virtual bool OnStartAdvise(const wxString& WXUNUSED(topic),
 164                              const wxString& WXUNUSED(item))
 165       { return false; }
 166
 167   virtual bool OnStopAdvise(const wxString& WXUNUSED(topic),
 168                             const wxString& WXUNUSED(item))
 169       { return false; }
 170
 171   // Callbacks to CLIENT - override at will
 172   virtual bool OnAdvise(const wxString& WXUNUSED(topic),
 173                         const wxString& WXUNUSED(item),
 174                         const void *WXUNUSED(data),
 175                         size_t WXUNUSED(size),
 176                         wxIPCFormat WXUNUSED(format))
 177       { return false; }
 178
 179   // Callbacks to BOTH
 180   virtual bool OnDisconnect() { delete this; return true; }
 181
 182
 183   // return true if this is one of the formats used for textual data
 184   // transmission
 185   static bool IsTextFormat(wxIPCFormat format)
 186   {
 187       return format == wxIPC_TEXT ||
 188              format == wxIPC_UTF8TEXT ||
 189              format == wxIPC_UTF16TEXT ||
 190              format == wxIPC_UTF32TEXT;
 191   }
 192
 193   // converts from the data and format into a wxString automatically
 194   //
 195   // this function accepts data in all of wxIPC_TEXT, wxIPC_UNICODETEXT, and
 196   // wxIPC_UTF8TEXT formats but asserts if the format is anything else (i.e.
 197   // such that IsTextFormat(format) doesn't return true)
 198   //
 199   // notice that the size parameter here contains the total size of the data,
 200   // including the terminating '\0' or L'\0'
 201   static
 202   wxString GetTextFromData(const void *data, size_t size, wxIPCFormat format);
 203
 204
 205   // return a buffer at least this size, reallocating buffer if needed
 206   // returns NULL if using an inadequate user buffer which can't be resized
 207   void *GetBufferAtLeast(size_t bytes);
 208
 209 protected:
 210   virtual bool DoExecute(const void *data, size_t size, wxIPCFormat format) = 0;
 211   virtual bool DoPoke(const wxString& item, const void *data, size_t size,
 212                       wxIPCFormat format) = 0;
 213   virtual bool DoAdvise(const wxString& item, const void *data, size_t size,
 214                         wxIPCFormat format) = 0;
 215
 216
 217 private:
 218   char         *m_buffer;
 219   size_t        m_buffersize;
 220   bool          m_deletebufferwhendone;
 221
 222 protected:
 223   bool          m_connected;
 224
 225   DECLARE_NO_ASSIGN_CLASS(wxConnectionBase)
 226   DECLARE_CLASS(wxConnectionBase)
 227 };
 228
 229
 230 class WXDLLIMPEXP_BASE wxServerBase : public wxObject
 231 {
 232 public:
 233   wxServerBase() { }
 234   virtual ~wxServerBase() { }
 235
 236   // Returns false on error (e.g. port number is already in use)
 237   virtual bool Create(const wxString& serverName) = 0;
 238
 239   // Callbacks to SERVER - override at will
 240   virtual wxConnectionBase *OnAcceptConnection(const wxString& topic) = 0;
 241
 242   DECLARE_CLASS(wxServerBase)
 243 };
 244
 245 class WXDLLIMPEXP_BASE wxClientBase : public wxObject
 246 {
 247 public:
 248   wxClientBase() { }
 249   virtual ~wxClientBase() { }
 250
 251   virtual bool ValidHost(const wxString& host) = 0;
 252
 253   // Call this to make a connection. Returns NULL if cannot.
 254   virtual wxConnectionBase *MakeConnection(const wxString& host,
 255                                            const wxString& server,
 256                                            const wxString& topic) = 0;
 257
 258   // Callbacks to CLIENT - override at will
 259   virtual wxConnectionBase *OnMakeConnection() = 0;
 260
 261   DECLARE_CLASS(wxClientBase)
 262 };
 263
 264 #endif // _WX_IPCBASEH__