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       { return false; }
 133
 134   // deprecated function kept for backwards compatibility: usually you will
 135   // want to override OnExec() above instead which receives its data in a more
 136   // convenient format
 137   virtual bool OnExecute(const wxString& topic,
 138                          const void *data,
 139                          size_t size,
 140                          wxIPCFormat format)
 141       { return OnExec(topic, GetTextFromData(data, size, format)); }
 142
 143   virtual const void *OnRequest(const wxString& WXUNUSED(topic),
 144                                 const wxString& WXUNUSED(item),
 145                                 size_t *size,
 146                                 wxIPCFormat WXUNUSED(format))
 147       { *size = 0; return NULL; }
 148
 149   virtual bool OnPoke(const wxString& WXUNUSED(topic),
 150                       const wxString& WXUNUSED(item),
 151                       const void *WXUNUSED(data),
 152                       size_t WXUNUSED(size),
 153                       wxIPCFormat WXUNUSED(format))
 154       { return false; }
 155
 156   virtual bool OnStartAdvise(const wxString& WXUNUSED(topic),
 157                              const wxString& WXUNUSED(item))
 158       { return false; }
 159
 160   virtual bool OnStopAdvise(const wxString& WXUNUSED(topic),
 161                             const wxString& WXUNUSED(item))
 162       { return false; }
 163
 164   // Callbacks to CLIENT - override at will
 165   virtual bool OnAdvise(const wxString& WXUNUSED(topic),
 166                         const wxString& WXUNUSED(item),
 167                         const void *WXUNUSED(data),
 168                         size_t WXUNUSED(size),
 169                         wxIPCFormat WXUNUSED(format))
 170       { return false; }
 171
 172   // Callbacks to BOTH
 173   virtual bool OnDisconnect() { delete this; return true; }
 174
 175
 176   // converts from the data and format into a wxString automatically
 177   //
 178   // this function accepts data in all of wxIPC_TEXT, wxIPC_UNICODETEXT, and
 179   // wxIPC_UTF8TEXT formats but asserts if the format is anything else
 180   //
 181   // notice that the size parameter here contains the total size of the data,
 182   // including the terminating '\0' or L'\0'
 183   static
 184   wxString GetTextFromData(const void *data, size_t size, wxIPCFormat format);
 185
 186
 187   // return a buffer at least this size, reallocating buffer if needed
 188   // returns NULL if using an inadequate user buffer which can't be resized
 189   void *GetBufferAtLeast(size_t bytes);
 190
 191 protected:
 192   virtual bool DoExecute(const void *data, size_t size, wxIPCFormat format) = 0;
 193   virtual bool DoPoke(const wxString& item, const void *data, size_t size,
 194                       wxIPCFormat format) = 0;
 195   virtual bool DoAdvise(const wxString& item, const void *data, size_t size,
 196                         wxIPCFormat format) = 0;
 197
 198
 199 private:
 200   char         *m_buffer;
 201   size_t        m_buffersize;
 202   bool          m_deletebufferwhendone;
 203
 204 protected:
 205   bool          m_connected;
 206
 207   DECLARE_NO_ASSIGN_CLASS(wxConnectionBase)
 208   DECLARE_CLASS(wxConnectionBase)
 209 };
 210
 211
 212 class WXDLLIMPEXP_BASE wxServerBase : public wxObject
 213 {
 214 public:
 215   wxServerBase() { }
 216   virtual ~wxServerBase() { }
 217
 218   // Returns false on error (e.g. port number is already in use)
 219   virtual bool Create(const wxString& serverName) = 0;
 220
 221   // Callbacks to SERVER - override at will
 222   virtual wxConnectionBase *OnAcceptConnection(const wxString& topic) = 0;
 223
 224   DECLARE_CLASS(wxServerBase)
 225 };
 226
 227 class WXDLLIMPEXP_BASE wxClientBase : public wxObject
 228 {
 229 public:
 230   wxClientBase() { }
 231   virtual ~wxClientBase() { }
 232
 233   virtual bool ValidHost(const wxString& host) = 0;
 234
 235   // Call this to make a connection. Returns NULL if cannot.
 236   virtual wxConnectionBase *MakeConnection(const wxString& host,
 237                                            const wxString& server,
 238                                            const wxString& topic) = 0;
 239
 240   // Callbacks to CLIENT - override at will
 241   virtual wxConnectionBase *OnMakeConnection() = 0;
 242
 243   DECLARE_CLASS(wxClientBase)
 244 };
 245
 246 #endif // _WX_IPCBASEH__