docs/latex/wx/ipcconn.tex

   1 \section{\class{wxConnection}}\label{wxconnection}
   2
   3 A wxConnection object represents the connection between a client
   4 and a server. It is created by making a connection using a\rtfsp
   5 \helpref{wxClient}{wxclient} object, or by the acceptance of a
   6 connection by a\rtfsp \helpref{wxServer}{wxserver} object. The
   7 bulk of a DDE-like (Dynamic Data Exchange) conversation is
   8 controlled by calling members in a {\bf wxConnection} object or
   9 by overriding its members. The actual DDE-based implementation
  10 using wxDDEConnection is available on Windows only, but a
  11 platform-independent, socket-based version of this API is
  12 available using wxTCPConnection, which has the same API.
  13
  14 An application should normally derive a new connection class from
  15 wxConnection, in order to override the communication event
  16 handlers to do something interesting.
  17
  18 \wxheading{Derived from}
  19
  20 wxConnectionBase\\
  21 \helpref{wxObject}{wxobject}
  22
  23 \wxheading{Include files}
  24
  25 <wx/ipc.h>
  26
  27 \wxheading{Types}
  28
  29 \index{wxIPCFormat}wxIPCFormat is defined as follows:
  30
  31 \begin{verbatim}
  32 enum wxIPCFormat
  33 {
  34   wxIPC_INVALID =          0,
  35   wxIPC_TEXT =             1,  /* CF_TEXT */
  36   wxIPC_BITMAP =           2,  /* CF_BITMAP */
  37   wxIPC_METAFILE =         3,  /* CF_METAFILEPICT */
  38   wxIPC_SYLK =             4,
  39   wxIPC_DIF =              5,
  40   wxIPC_TIFF =             6,
  41   wxIPC_OEMTEXT =          7,  /* CF_OEMTEXT */
  42   wxIPC_DIB =              8,  /* CF_DIB */
  43   wxIPC_PALETTE =          9,
  44   wxIPC_PENDATA =          10,
  45   wxIPC_RIFF =             11,
  46   wxIPC_WAVE =             12,
  47   wxIPC_UTF16TEXT =        13, /* CF_UNICODE */
  48   wxIPC_ENHMETAFILE =      14,
  49   wxIPC_FILENAME =         15, /* CF_HDROP */
  50   wxIPC_LOCALE =           16,
  51   wxIPC_UTF8TEXT =         17,
  52   wxIPC_UTF32TEXT =        18,
  53 #if SIZEOF_WCHAR_T == 2
  54   wxIPC_UNICODETEXT =      wxIPC_UTF16TEXT,
  55 #elif SIZEOF_WCHAR_T == 4
  56   wxIPC_UNICODETEXT =      wxIPC_UTF32TEXT,
  57 #endif
  58   wxIPC_PRIVATE =          20
  59 };
  60 \end{verbatim}
  61
  62 \wxheading{See also}
  63
  64 \helpref{wxClient}{wxclient}, \helpref{wxServer}{wxserver},
  65 \helpref{Interprocess communications overview}{ipcoverview}
  66
  67 \latexignore{\rtfignore{\wxheading{Members}}}
  68
  69 \membersection{wxConnection::wxConnection}\label{wxconnectionctor}
  70
  71 \func{}{wxConnection}{\void}
  72
  73 \func{}{wxConnection}{\param{void* }{buffer}, \param{size\_t}{ size}}
  74
  75 Constructs a connection object. If no user-defined connection
  76 object is to be derived from wxConnection, then the constructor
  77 should not be called directly, since the default connection
  78 object will be provided on requesting (or accepting) a
  79 connection. However, if the user defines his or her own derived
  80 connection object, the \helpref{wxServer::OnAcceptConnection}{wxserveronacceptconnection}\rtfsp
  81 and/or \helpref{wxClient::OnMakeConnection}{wxclientonmakeconnection}
  82 members should be replaced by functions which construct the new
  83 connection object.
  84
  85 If the arguments of the wxConnection constructor are void then
  86 the wxConnection object manages its own connection buffer,
  87 allocating memory as needed. A programmer-supplied buffer cannot
  88 be increased if necessary, and the program will assert if it is
  89 not large enough. The programmer-supplied buffer is included
  90 mainly for backwards compatibility.
  91
  92 \membersection{wxConnection::Advise}\label{wxconnectionadvise}
  93
  94 \func{bool}{Advise}{\param{const wxString\& }{item}, \param{const void* }{data}, \param{size\_t }{size}, \param{wxIPCFormat }{format = wxIPC\_PRIVATE}}
  95
  96 \func{bool}{Advise}{\param{const wxString\& }{item}, \param{const char* }{data}, \param{size\_t }{size = (size\_t)-1}}
  97
  98 \func{bool}{Advise}{\param{const wxString\& }{item}, \param{const wchar\_t* }{data}, \param{size\_t }{size = (size\_t)-1}}
  99
 100 \func{bool}{Advise}{\param{const wxString\& }{item}, \param{const wxString& }{data}}
 101
 102 Called by the server application to advise the client of a change
 103 in the data associated with the given item. Causes the client
 104 connection's \helpref{wxConnection::OnAdvise}{wxconnectiononadvise} member
 105 to be called. Returns true if successful.
 106
 107 \membersection{wxConnection::Execute}\label{wxconnectionexecute}
 108
 109 \func{bool}{Execute}{\param{const void* }{data}, \param{size\_t }{size}, \param{wxIPCFormat }{format = wxIPC\_PRIVATE}}
 110
 111 \func{bool}{Execute}{\param{const char* }{data}, \param{size\_t }{size = (size\_t)-1}}
 112
 113 \func{bool}{Execute}{\param{const wchar\_t* }{data}, \param{size\_t }{size = (size\_t)-1}}
 114
 115 \func{bool}{Execute}{\param{const wxString& }{data}}
 116
 117 Called by the client application to execute a command on the
 118 server. Can also be used to transfer arbitrary data to the server
 119 (similar to \helpref{wxConnection::Poke}{wxconnectionpoke} in
 120 that respect). Causes the server connection's \helpref{wxConnection::OnExecute}{wxconnectiononexecute}
 121 member to be called. Returns true if successful.
 122
 123 \membersection{wxConnection::Disconnect}\label{wxconnectiondisconnect}
 124
 125 \func{bool}{Disconnect}{\void}
 126
 127 Called by the client or server application to disconnect from the
 128 other program; it causes the \helpref{wxConnection::OnDisconnect}{wxconnectionondisconnect}
 129 message to be sent to the corresponding connection object in the
 130 other program. Returns true if successful or already disconnected.
 131 The application that calls {\bf Disconnect} must explicitly delete
 132 its side of the connection.
 133
 134 \membersection{wxConnection::OnAdvise}\label{wxconnectiononadvise}
 135
 136 \func{virtual bool}{OnAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{const void* }{data}, \param{size\_t }{size}, \param{wxIPCFormat }{format}}
 137
 138 Message sent to the client application when the server notifies
 139 it of a change in the data associated with the given item, using
 140 \helpref{Advise}{wxconnectionadvise}.
 141
 142 \membersection{wxConnection::OnDisconnect}\label{wxconnectionondisconnect}
 143
 144 \func{virtual bool}{OnDisconnect}{\void}
 145
 146 Message sent to the client or server application when the other
 147 application notifies it to end the connection. The default
 148 behaviour is to delete the connection object and return true, so
 149 applications should generally override {\bf OnDisconnect}
 150 (finally calling the inherited method as well) so that they know
 151 the connection object is no longer available.
 152
 153 \membersection{wxConnection::OnExecute}\label{wxconnectiononexecute}
 154
 155 \func{virtual bool}{OnExecute}{\param{const wxString\& }{topic}, \param{const void* }{data}, \param{size\_t }{size}, \param{wxIPCFormat}{ format}}
 156
 157 Message sent to the server application when the client notifies
 158 it to execute the given data, using \helpref{Execute}{wxconnectionexecute}.
 159 Note that there is no item associated with this message.
 160
 161 \membersection{wxConnection::OnPoke}\label{wxconnectiononpoke}
 162
 163 \func{virtual bool}{OnPoke}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{const void* }{data}, \param{size\_t }{size}, \param{wxIPCFormat }{format}}
 164
 165 Message sent to the server application when the client notifies it to
 166 accept the given data.
 167
 168 \membersection{wxConnection::OnRequest}\label{wxconnectiononrequest}
 169
 170 \func{virtual const void*}{OnRequest}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{size\_t * }{size}, \param{wxIPCFormat }{format}}
 171
 172 Message sent to the server application when the client calls
 173 \helpref{wxConnection::Request}{wxconnectionrequest}. The
 174 server's \helpref{OnRequest}{wxconnectiononrequest} method
 175 should respond by returning a character string, or NULL to
 176 indicate no data, and setting *size. The character string must of
 177 course persist after the call returns.
 178
 179 \membersection{wxConnection::OnStartAdvise}\label{wxconnectiononstartadvise}
 180
 181 \func{virtual bool}{OnStartAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
 182
 183 Message sent to the server application by the client, when the client
 184 wishes to start an `advise loop' for the given topic and item. The
 185 server can refuse to participate by returning false.
 186
 187 \membersection{wxConnection::OnStopAdvise}\label{wxconnectiononstopadvise}
 188
 189 \func{virtual bool}{OnStopAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
 190
 191 Message sent to the server application by the client, when the client
 192 wishes to stop an `advise loop' for the given topic and item. The
 193 server can refuse to stop the advise loop by returning false, although
 194 this doesn't have much meaning in practice.
 195
 196 \membersection{wxConnection::Poke}\label{wxconnectionpoke}
 197
 198 \func{bool}{Poke}{\param{const wxString\& }{item}, \param{const void* }{data}, \param{size\_t }{size}, \param{wxIPCFormat }{format = wxIPC\_PRIVATE}}
 199
 200 \func{bool}{Poke}{\param{const wxString\& }{item}, \param{const char* }{data}, \param{size\_t }{size = (size\_t)-1}}
 201
 202 \func{bool}{Poke}{\param{const wxString\& }{item}, \param{const wchar\_t* }{data}, \param{size\_t }{size = (size\_t)-1}}
 203
 204 \func{bool}{Poke}{\param{const wxString\& }{item}, \param{const wxString& }{data}}
 205
 206 Called by the client application to poke data into the server.
 207 Can be used to transfer arbitrary data to the server. Causes the
 208 server connection's \helpref{wxConnection::OnPoke}{wxconnectiononpoke} member to
 209 be called. If size is -1 the size is computed from the string
 210 length of data.
 211
 212 Returns true if successful.
 213
 214 \membersection{wxConnection::Request}\label{wxconnectionrequest}
 215
 216 \func{const void*}{Request}{\param{const wxString\& }{item}, \param{size\_t *}{size}, \param{wxIPCFormat }{format = wxIPC\_TEXT}}
 217
 218 Called by the client application to request data from the server.
 219 Causes the server connection's \helpref{wxConnection::OnRequest}{wxconnectiononrequest}
 220 member to be called. Size may be NULL or a pointer to a variable
 221 to receive the size of the requested item.
 222
 223 Returns a character string (actually a pointer to the
 224 connection's buffer) if successful, NULL otherwise. This buffer
 225 does not need to be deleted.
 226
 227 \membersection{wxConnection::StartAdvise}\label{wxconnectionstartadvise}
 228
 229 \func{bool}{StartAdvise}{\param{const wxString\& }{item}}
 230
 231 Called by the client application to ask if an advise loop can be
 232 started with the server. Causes the server connection's
 233 \helpref{wxConnection::OnStartAdvise}{wxconnectiononstartadvise}\rtfsp
 234 member to be called. Returns true if the server okays it, false
 235 otherwise.
 236
 237 \membersection{wxConnection::StopAdvise}\label{wxconnectionstopadvise}
 238
 239 \func{bool}{StopAdvise}{\param{const wxString\& }{item}}
 240
 241 Called by the client application to ask if an advise loop can be
 242 stopped. Causes the server connection's \helpref{wxConnection::OnStopAdvise}{wxconnectiononstopadvise}
 243 member to be called. Returns true if the server okays it, false
 244 otherwise.
 245