include/wx/ipcbase.h

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