synchronize GTK2 minimum version in docs

[wxWidgets.git] / include / wx / ipcbase.h

diff --git a/include/wx/ipcbase.h b/include/wx/ipcbase.h
index 6d3e80562cd165a4ec6fd742a86dbed7970fad70..521bef85951f5c672628553fd7f33b2bbb476925 100644 (file)
--- a/include/wx/ipcbase.h
+++ b/include/wx/ipcbase.h
@@ -1,21 +1,17 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        ipcbase.h
+// Name:        wx/ipcbase.h

 // Purpose:     Base classes for IPC
 // Author:      Julian Smart
 // Modified by:
 // Created:     4/1/98
 // RCS-ID:      $Id$
 // Purpose:     Base classes for IPC
 // Author:      Julian Smart
 // Modified by:
 // Created:     4/1/98
 // RCS-ID:      $Id$

-// Copyright:   (c) Julian Smart and Markus Holzem
-// Licence:    wxWindows license
+// Copyright:   (c) Julian Smart
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 #ifndef _WX_IPCBASEH__
 #define _WX_IPCBASEH__
 
 /////////////////////////////////////////////////////////////////////////////
 
 #ifndef _WX_IPCBASEH__
 #define _WX_IPCBASEH__
 

-#ifdef __GNUG__
-#pragma interface "ipcbase.h"
-#endif
-

 #include "wx/defs.h"
 #include "wx/object.h"
 #include "wx/string.h"
 #include "wx/defs.h"
 #include "wx/object.h"
 #include "wx/string.h"


@@ -35,101 +31,222 @@ enum wxIPCFormat
   wxIPC_PENDATA =          10,
   wxIPC_RIFF =             11,
   wxIPC_WAVE =             12,
   wxIPC_PENDATA =          10,
   wxIPC_RIFF =             11,
   wxIPC_WAVE =             12,

-  wxIPC_UNICODETEXT =      13,
+  wxIPC_UTF16TEXT =        13, /* CF_UNICODE */

   wxIPC_ENHMETAFILE =      14,
   wxIPC_FILENAME =         15, /* CF_HDROP */
   wxIPC_LOCALE =           16,
   wxIPC_ENHMETAFILE =      14,
   wxIPC_FILENAME =         15, /* CF_HDROP */
   wxIPC_LOCALE =           16,

+  wxIPC_UTF8TEXT =         17,
+  wxIPC_UTF32TEXT =        18,
+#if SIZEOF_WCHAR_T == 2
+  wxIPC_UNICODETEXT = wxIPC_UTF16TEXT,
+#elif SIZEOF_WCHAR_T == 4
+  wxIPC_UNICODETEXT = wxIPC_UTF32TEXT,
+#else
+#  error "Unknown wchar_t size"
+#endif

   wxIPC_PRIVATE =          20
 };
 
   wxIPC_PRIVATE =          20
 };
 

-class WXDLLEXPORT wxServerBase;
-class WXDLLEXPORT wxClientBase;
+class WXDLLIMPEXP_FWD_BASE wxServerBase;
+class WXDLLIMPEXP_FWD_BASE wxClientBase;

 
 

-class WXDLLEXPORT wxConnectionBase: public wxObject
+class WXDLLIMPEXP_BASE wxConnectionBase: public wxObject

 {
 {

-  DECLARE_CLASS(wxConnectionBase)
-

 public:
 public:

-  inline wxConnectionBase(void) {}
-  inline ~wxConnectionBase(void) {}
+  wxConnectionBase(void *buffer, size_t size); // use external buffer
+  wxConnectionBase(); // use internal, adaptive buffer
+  wxConnectionBase(const wxConnectionBase& copy);
+  virtual ~wxConnectionBase();
+
+  void SetConnected( bool c ) { m_connected = c; }
+  bool GetConnected() { return m_connected; }

 
   // Calls that CLIENT can make
 
   // Calls that CLIENT can make

-  virtual bool Execute(const wxChar *data, int size = -1, wxIPCFormat format = wxIPC_TEXT ) = 0;
-  virtual bool Execute(const wxString& str) { return Execute(str, -1, wxIPC_TEXT); }
-  virtual char *Request(const wxString& item, int *size = (int *) NULL, wxIPCFormat format = wxIPC_TEXT) = 0;
-  virtual bool Poke(const wxString& item, wxChar *data, int size = -1, wxIPCFormat format = wxIPC_TEXT) = 0;
+  bool Execute(const void *data, size_t size, wxIPCFormat fmt = wxIPC_PRIVATE)
+      { return DoExecute(data, size, fmt); }
+  bool Execute(const char *s, size_t size = wxNO_LEN)
+      { return DoExecute(s, size == wxNO_LEN ? strlen(s) + 1
+                                             : size, wxIPC_TEXT); }
+  bool Execute(const wchar_t *ws, size_t size = wxNO_LEN)
+      { return DoExecute(ws, size == wxNO_LEN ? (wcslen(ws) + 1)*sizeof(wchar_t)
+                                              : size, wxIPC_UNICODETEXT); }
+  bool Execute(const wxString& s)
+  {
+      const wxScopedCharBuffer buf = s.utf8_str();
+      return DoExecute(buf, strlen(buf) + 1, wxIPC_UTF8TEXT);
+  }
+  bool Execute(const wxCStrData& cs)
+      { return Execute(cs.AsString()); }
+
+  virtual const void *Request(const wxString& item,
+                              size_t *size = NULL,
+                              wxIPCFormat format = wxIPC_TEXT) = 0;
+
+  bool Poke(const wxString& item, const void *data, size_t size,
+            wxIPCFormat fmt = wxIPC_PRIVATE)
+      { return DoPoke(item, data, size, fmt); }
+  bool Poke(const wxString& item, const char *s, size_t size = wxNO_LEN)
+      { return DoPoke(item, s, size == wxNO_LEN ? strlen(s) + 1
+                                                : size, wxIPC_TEXT); }
+  bool Poke(const wxString& item, const wchar_t *ws, size_t size = wxNO_LEN)
+      { return DoPoke(item, ws,
+                      size == wxNO_LEN ? (wcslen(ws) + 1)*sizeof(wchar_t)
+                                       : size, wxIPC_UNICODETEXT); }
+  bool Poke(const wxString& item, const wxString s)
+  {
+      const wxScopedCharBuffer buf = s.utf8_str();
+      return DoPoke(item, buf,  strlen(buf) + 1, wxIPC_UTF8TEXT);
+  }
+  bool Poke(const wxString& item, const wxCStrData& cs)
+      { return Poke(item, cs.AsString()); }
+

   virtual bool StartAdvise(const wxString& item) = 0;
   virtual bool StopAdvise(const wxString& item) = 0;
 
   // Calls that SERVER can make
   virtual bool StartAdvise(const wxString& item) = 0;
   virtual bool StopAdvise(const wxString& item) = 0;
 
   // Calls that SERVER can make

-  virtual bool Advise(const wxString& item, wxChar *data, int size = -1, wxIPCFormat format = wxIPC_TEXT) = 0;
+  bool Advise(const wxString& item, const void *data, size_t size,
+              wxIPCFormat fmt = wxIPC_PRIVATE)
+      { return DoAdvise(item, data, size, fmt); }
+  bool Advise(const wxString& item, const char *s, size_t size = wxNO_LEN)
+      { return DoAdvise(item, s, size == wxNO_LEN ? strlen(s) + 1
+                                                  : size, wxIPC_TEXT); }
+  bool Advise(const wxString& item, const wchar_t *ws, size_t size = wxNO_LEN)
+      { return DoAdvise(item, ws,
+                        size == wxNO_LEN ? (wcslen(ws) + 1)*sizeof(wchar_t)
+                                         : size, wxIPC_UNICODETEXT); }
+  bool Advise(const wxString& item, const wxString s)
+  {
+      const wxScopedCharBuffer buf = s.utf8_str();
+      return DoAdvise(item, buf,  strlen(buf) + 1, wxIPC_UTF8TEXT);
+  }
+  bool Advise(const wxString& item, const wxCStrData& cs)
+      { return Advise(item, cs.AsString()); }

 
   // Calls that both can make
 
   // Calls that both can make

-  virtual bool Disconnect(void) = 0;
+  virtual bool Disconnect() = 0;
+

 
   // Callbacks to SERVER - override at will
 
   // Callbacks to SERVER - override at will

-  virtual bool OnExecute     ( const wxString& WXUNUSED(topic),
-                               char *WXUNUSED(data),
-                               int WXUNUSED(size),
-                               wxIPCFormat WXUNUSED(format) )
-                             { return FALSE; };
-
-  virtual char *OnRequest    ( const wxString& WXUNUSED(topic),
-                               const wxString& WXUNUSED(item),
-                               int *WXUNUSED(size),
-                               wxIPCFormat WXUNUSED(format) )
-                             { return (char *) NULL; };
-
-  virtual bool OnPoke        ( const wxString& WXUNUSED(topic),
-                               const wxString& WXUNUSED(item),
-                               wxChar *WXUNUSED(data),
-                               int WXUNUSED(size),
-                               wxIPCFormat WXUNUSED(format) )
-                             { return FALSE; };
-
-  virtual bool OnStartAdvise ( const wxString& WXUNUSED(topic),
-                               const wxString& WXUNUSED(item) )
-                             { return FALSE; };
-
-  virtual bool OnStopAdvise  ( const wxString& WXUNUSED(topic),
-                               const wxString& WXUNUSED(item) )
-                             { return FALSE; };
+  virtual bool OnExec(const wxString& WXUNUSED(topic),
+                      const wxString& WXUNUSED(data))
+  {
+      wxFAIL_MSG( "This method shouldn't be called, if it is, it probably "
+                  "means that you didn't update your old code overriding "
+                  "OnExecute() to use the new parameter types (\"const void *\" "
+                  "instead of \"wxChar *\" and \"size_t\" instead of \"int\"), "
+                  "you must do it or your code wouldn't be executed at all!" );
+      return false;
+  }
+
+  // deprecated function kept for backwards compatibility: usually you will
+  // want to override OnExec() above instead which receives its data in a more
+  // convenient format
+  virtual bool OnExecute(const wxString& topic,
+                         const void *data,
+                         size_t size,
+                         wxIPCFormat format)
+      { return OnExec(topic, GetTextFromData(data, size, format)); }
+
+  virtual const void *OnRequest(const wxString& WXUNUSED(topic),
+                                const wxString& WXUNUSED(item),
+                                size_t *size,
+                                wxIPCFormat WXUNUSED(format))
+      { *size = 0; return NULL; }
+
+  virtual bool OnPoke(const wxString& WXUNUSED(topic),
+                      const wxString& WXUNUSED(item),
+                      const void *WXUNUSED(data),
+                      size_t WXUNUSED(size),
+                      wxIPCFormat WXUNUSED(format))
+      { return false; }
+
+  virtual bool OnStartAdvise(const wxString& WXUNUSED(topic),
+                             const wxString& WXUNUSED(item))
+      { return false; }
+
+  virtual bool OnStopAdvise(const wxString& WXUNUSED(topic),
+                            const wxString& WXUNUSED(item))
+      { return false; }

 
   // Callbacks to CLIENT - override at will
 
   // Callbacks to CLIENT - override at will

-  virtual bool OnAdvise      ( const wxString& WXUNUSED(topic),
-                               const wxString& WXUNUSED(item),
-                               char *WXUNUSED(data),
-                               int WXUNUSED(size),
-                               wxIPCFormat WXUNUSED(format) )
-                             { return FALSE; };
-
-  // Callbacks to BOTH - override at will
-  // Default behaviour is to delete connection and return TRUE
-  virtual bool OnDisconnect(void) = 0;
+  virtual bool OnAdvise(const wxString& WXUNUSED(topic),
+                        const wxString& WXUNUSED(item),
+                        const void *WXUNUSED(data),
+                        size_t WXUNUSED(size),
+                        wxIPCFormat WXUNUSED(format))
+      { return false; }
+
+  // Callbacks to BOTH
+  virtual bool OnDisconnect() { delete this; return true; }
+
+
+  // return true if this is one of the formats used for textual data
+  // transmission
+  static bool IsTextFormat(wxIPCFormat format)
+  {
+      return format == wxIPC_TEXT ||
+             format == wxIPC_UTF8TEXT ||
+             format == wxIPC_UTF16TEXT ||
+             format == wxIPC_UTF32TEXT;
+  }
+
+  // converts from the data and format into a wxString automatically
+  //
+  // this function accepts data in all of wxIPC_TEXT, wxIPC_UNICODETEXT, and
+  // wxIPC_UTF8TEXT formats but asserts if the format is anything else (i.e.
+  // such that IsTextFormat(format) doesn't return true)
+  //
+  // notice that the size parameter here contains the total size of the data,
+  // including the terminating '\0' or L'\0'
+  static
+  wxString GetTextFromData(const void *data, size_t size, wxIPCFormat format);
+
+
+  // return a buffer at least this size, reallocating buffer if needed
+  // returns NULL if using an inadequate user buffer which can't be resized
+  void *GetBufferAtLeast(size_t bytes);
+
+protected:
+  virtual bool DoExecute(const void *data, size_t size, wxIPCFormat format) = 0;
+  virtual bool DoPoke(const wxString& item, const void *data, size_t size,
+                      wxIPCFormat format) = 0;
+  virtual bool DoAdvise(const wxString& item, const void *data, size_t size,
+                        wxIPCFormat format) = 0;
+
+
+private:
+  char         *m_buffer;
+  size_t        m_buffersize;
+  bool          m_deletebufferwhendone;
+
+protected:
+  bool          m_connected;
+
+  wxDECLARE_NO_ASSIGN_CLASS(wxConnectionBase);
+  DECLARE_CLASS(wxConnectionBase)

 };
 
 };
 

-class WXDLLEXPORT wxServerBase: public wxObject
-{
-  DECLARE_CLASS(wxServerBase)

 
 

+class WXDLLIMPEXP_BASE wxServerBase : public wxObject
+{

 public:
 public:

-  inline wxServerBase(void) {}
-  inline ~wxServerBase(void) {};
+  wxServerBase() { }
+  virtual ~wxServerBase() { }

 
 

-  // Returns FALSE on error (e.g. port number is already in use)
+  // Returns false on error (e.g. port number is already in use)

   virtual bool Create(const wxString& serverName) = 0;
 
   // Callbacks to SERVER - override at will
   virtual wxConnectionBase *OnAcceptConnection(const wxString& topic) = 0;
   virtual bool Create(const wxString& serverName) = 0;
 
   // Callbacks to SERVER - override at will
   virtual wxConnectionBase *OnAcceptConnection(const wxString& topic) = 0;

+
+  DECLARE_CLASS(wxServerBase)

 };
 
 };
 

-class WXDLLEXPORT wxClientBase: public wxObject
+class WXDLLIMPEXP_BASE wxClientBase : public wxObject

 {
 {

-  DECLARE_CLASS(wxClientBase)
-

 public:
 public:

-  inline wxClientBase(void) {};
-  inline ~wxClientBase(void) {};
+  wxClientBase() { }
+  virtual ~wxClientBase() { }

 
   virtual bool ValidHost(const wxString& host) = 0;
 
 
   virtual bool ValidHost(const wxString& host) = 0;
 


@@ -139,8 +256,9 @@ public:
                                            const wxString& topic) = 0;
 
   // Callbacks to CLIENT - override at will
                                            const wxString& topic) = 0;
 
   // Callbacks to CLIENT - override at will

-  virtual wxConnectionBase *OnMakeConnection(void) = 0;
+  virtual wxConnectionBase *OnMakeConnection() = 0;
+
+  DECLARE_CLASS(wxClientBase)

 };
 
 };
 

-#endif
-    // _WX_IPCBASEH__
+#endif // _WX_IPCBASEH__