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_UNICODETEXT =      13,
  48   wxIPC_ENHMETAFILE =      14,
  49   wxIPC_FILENAME =         15, /* CF_HDROP */
  50   wxIPC_LOCALE =           16,
  51   wxIPC_PRIVATE =          20
  52 };
  53 \end{verbatim}
  54
  55 \wxheading{See also}
  56
  57 \helpref{wxClient}{wxclient}, \helpref{wxServer}{wxserver},
  58 \helpref{Interprocess communications overview}{ipcoverview}
  59
  60 \latexignore{\rtfignore{\wxheading{Members}}}
  61
  62 \membersection{wxConnection::wxConnection}\label{wxconnectionctor}
  63
  64 \func{}{wxConnection}{\void}
  65
  66 \func{}{wxConnection}{\param{char* }{buffer}, \param{int}{ size}}
  67
  68 Constructs a connection object. If no user-defined connection
  69 object is to be derived from wxConnection, then the constructor
  70 should not be called directly, since the default connection
  71 object will be provided on requesting (or accepting) a
  72 connection. However, if the user defines his or her own derived
  73 connection object, the \helpref{wxServer::OnAcceptConnection}{wxserveronacceptconnection}\rtfsp
  74 and/or \helpref{wxClient::OnMakeConnection}{wxclientonmakeconnection}
  75 members should be replaced by functions which construct the new
  76 connection object.
  77
  78 If the arguments of the wxConnection constructor are void then
  79 the wxConnection object manages its own connection buffer,
  80 allocating memory as needed. A programmer-supplied buffer cannot
  81 be increased if necessary, and the program will assert if it is
  82 not large enough. The programmer-supplied buffer is included
  83 mainly for backwards compatibility.
  84
  85 \membersection{wxConnection::Advise}\label{wxconnectionadvise}
  86
  87 \func{bool}{Advise}{\param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
  88
  89 Called by the server application to advise the client of a change
  90 in the data associated with the given item. Causes the client
  91 connection's \helpref{wxConnection::OnAdvise}{wxconnectiononadvise} member
  92 to be called. Returns true if successful.
  93
  94 \membersection{wxConnection::Execute}\label{wxconnectionexecute}
  95
  96 \func{bool}{Execute}{\param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
  97
  98 Called by the client application to execute a command on the
  99 server. Can also be used to transfer arbitrary data to the server
 100 (similar to \helpref{wxConnection::Poke}{wxconnectionpoke} in
 101 that respect). Causes the server connection's \helpref{wxConnection::OnExecute}{wxconnectiononexecute}
 102 member to be called. Returns true if successful.
 103
 104 \membersection{wxConnection::Disconnect}\label{wxconnectiondisconnect}
 105
 106 \func{bool}{Disconnect}{\void}
 107
 108 Called by the client or server application to disconnect from the
 109 other program; it causes the \helpref{wxConnection::OnDisconnect}{wxconnectionondisconnect}
 110 message to be sent to the corresponding connection object in the
 111 other program. Returns true if successful or already disconnected.
 112 The application that calls {\bf Disconnect} must explicitly delete
 113 its side of the connection.
 114
 115 \membersection{wxConnection::OnAdvise}\label{wxconnectiononadvise}
 116
 117 \func{virtual bool}{OnAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
 118
 119 Message sent to the client application when the server notifies
 120 it of a change in the data associated with the given item, using
 121 \helpref{Advise}{wxconnectionadvise}.
 122
 123 \membersection{wxConnection::OnDisconnect}\label{wxconnectionondisconnect}
 124
 125 \func{virtual bool}{OnDisconnect}{\void}
 126
 127 Message sent to the client or server application when the other
 128 application notifies it to end the connection. The default
 129 behaviour is to delete the connection object and return true, so
 130 applications should generally override {\bf OnDisconnect}
 131 (finally calling the inherited method as well) so that they know
 132 the connection object is no longer available.
 133
 134 \membersection{wxConnection::OnExecute}\label{wxconnectiononexecute}
 135
 136 \func{virtual bool}{OnExecute}{\param{const wxString\& }{topic}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
 137
 138 Message sent to the server application when the client notifies
 139 it to execute the given data, using \helpref{Execute}{wxconnectionexecute}.
 140 Note that there is no item associated with this message.
 141
 142 \membersection{wxConnection::OnPoke}\label{wxconnectiononpoke}
 143
 144 \func{virtual bool}{OnPoke}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
 145
 146 Message sent to the server application when the client notifies it to
 147 accept the given data.
 148
 149 \membersection{wxConnection::OnRequest}\label{wxconnectiononrequest}
 150
 151 \func{virtual char*}{OnRequest}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{int *}{size}, \param{wxIPCFormat}{ format}}
 152
 153 Message sent to the server application when the client calls
 154 \helpref{wxConnection::Request}{wxconnectionrequest}. The
 155 server's \helpref{OnRequest}{wxconnectiononrequest} method
 156 should respond by returning a character string, or NULL to
 157 indicate no data, and setting *size. The character string must of
 158 course persist after the call returns.
 159
 160 \membersection{wxConnection::OnStartAdvise}\label{wxconnectiononstartadvise}
 161
 162 \func{virtual bool}{OnStartAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
 163
 164 Message sent to the server application by the client, when the client
 165 wishes to start an `advise loop' for the given topic and item. The
 166 server can refuse to participate by returning false.
 167
 168 \membersection{wxConnection::OnStopAdvise}\label{wxconnectiononstopadvise}
 169
 170 \func{virtual bool}{OnStopAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
 171
 172 Message sent to the server application by the client, when the client
 173 wishes to stop an `advise loop' for the given topic and item. The
 174 server can refuse to stop the advise loop by returning false, although
 175 this doesn't have much meaning in practice.
 176
 177 \membersection{wxConnection::Poke}\label{wxconnectionpoke}
 178
 179 \func{bool}{Poke}{\param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
 180
 181 Called by the client application to poke data into the server.
 182 Can be used to transfer arbitrary data to the server. Causes the
 183 server connection's \helpref{wxConnection::OnPoke}{wxconnectiononpoke} member to
 184 be called. If size is -1 the size is computed from the string
 185 length of data.
 186
 187 Returns true if successful.
 188
 189 \membersection{wxConnection::Request}\label{wxconnectionrequest}
 190
 191 \func{char*}{Request}{\param{const wxString\& }{item}, \param{int *}{size}, \param{wxIPCFormat}{ format = wxIPC\_TEXT}}
 192
 193 Called by the client application to request data from the server.
 194 Causes the server connection's \helpref{wxConnection::OnRequest}{wxconnectiononrequest}
 195 member to be called. Size may be NULL or a pointer to a variable
 196 to receive the size of the requested item.
 197
 198 Returns a character string (actually a pointer to the
 199 connection's buffer) if successful, NULL otherwise. This buffer
 200 does not need to be deleted.
 201
 202 \membersection{wxConnection::StartAdvise}\label{wxconnectionstartadvise}
 203
 204 \func{bool}{StartAdvise}{\param{const wxString\& }{item}}
 205
 206 Called by the client application to ask if an advise loop can be
 207 started with the server. Causes the server connection's
 208 \helpref{wxConnection::OnStartAdvise}{wxconnectiononstartadvise}\rtfsp
 209 member to be called. Returns true if the server okays it, false
 210 otherwise.
 211
 212 \membersection{wxConnection::StopAdvise}\label{wxconnectionstopadvise}
 213
 214 \func{bool}{StopAdvise}{\param{const wxString\& }{item}}
 215
 216 Called by the client application to ask if an advise loop can be
 217 stopped. Causes the server connection's \helpref{wxConnection::OnStopAdvise}{wxconnectiononstopadvise}
 218 member to be called. Returns true if the server okays it, false
 219 otherwise.
 220