docs/latex/wx/ddeconn.tex

   1 \section{\class{wxDDEConnection}}\label{wxddeconnection}
   2
   3 A wxDDEConnection object represents the connection between a client and a
   4 server. It can be created by making a connection using a\rtfsp
   5 \helpref{wxDDEClient}{wxddeclient} object, or by the acceptance of a connection by a\rtfsp
   6 \helpref{wxDDEServer}{wxddeserver} object. The bulk of a DDE (Dynamic Data Exchange)
   7 conversation is controlled by
   8 calling members in a {\bf wxDDEConnection} object or by overriding its
   9 members.
  10
  11 An application should normally derive a new connection class from
  12 wxDDEConnection, in order to override the communication event handlers
  13 to do something interesting.
  14
  15 This DDE-based implementation is available on Windows only,
  16 but a platform-independent, socket-based version
  17 of this API is available using \helpref{wxTCPConnection}{wxtcpconnection}.
  18
  19 \wxheading{Derived from}
  20
  21 wxConnectionBase\\
  22 \helpref{wxObject}{wxobject}
  23
  24 \wxheading{Include files}
  25
  26 <wx/dde.h>
  27
  28 \wxheading{Library}
  29
  30 \helpref{wxBase}{librarieslist}
  31
  32 \wxheading{Types}
  33
  34 \index{wxIPCFormat}wxIPCFormat is defined as follows:
  35
  36 \begin{verbatim}
  37 enum wxIPCFormat
  38 {
  39   wxIPC_INVALID =          0,
  40   wxIPC_TEXT =             1,  /* CF_TEXT */
  41   wxIPC_BITMAP =           2,  /* CF_BITMAP */
  42   wxIPC_METAFILE =         3,  /* CF_METAFILEPICT */
  43   wxIPC_SYLK =             4,
  44   wxIPC_DIF =              5,
  45   wxIPC_TIFF =             6,
  46   wxIPC_OEMTEXT =          7,  /* CF_OEMTEXT */
  47   wxIPC_DIB =              8,  /* CF_DIB */
  48   wxIPC_PALETTE =          9,
  49   wxIPC_PENDATA =          10,
  50   wxIPC_RIFF =             11,
  51   wxIPC_WAVE =             12,
  52   wxIPC_UNICODETEXT =      13,
  53   wxIPC_ENHMETAFILE =      14,
  54   wxIPC_FILENAME =         15, /* CF_HDROP */
  55   wxIPC_LOCALE =           16,
  56   wxIPC_PRIVATE =          20
  57 };
  58 \end{verbatim}
  59
  60 \wxheading{See also}
  61
  62 \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEServer}{wxddeserver}, \helpref{Interprocess communications overview}{ipcoverview}
  63
  64 \latexignore{\rtfignore{\wxheading{Members}}}
  65
  66 \membersection{wxDDEConnection::wxDDEConnection}\label{wxddeconnectionctor}
  67
  68 \func{}{wxDDEConnection}{\void}
  69
  70 \func{}{wxDDEConnection}{\param{char* }{buffer}, \param{int}{ size}}
  71
  72 Constructs a connection object. If no user-defined connection object is
  73 to be derived from wxDDEConnection, then the constructor should not be
  74 called directly, since the default connection object will be provided on
  75 requesting (or accepting) a connection. However, if the user defines his
  76 or her own derived connection object, the \helpref{wxDDEServer::OnAcceptConnection}{wxddeserveronacceptconnection}\rtfsp
  77 and/or \helpref{wxDDEClient::OnMakeConnection}{wxddeclientonmakeconnection} members should be replaced by
  78 functions which construct the new connection object. If the arguments of
  79 the wxDDEConnection constructor are void, then a default buffer is
  80 associated with the connection. Otherwise, the programmer must provide a
  81 a buffer and size of the buffer for the connection object to use in
  82 transactions.
  83
  84 \membersection{wxDDEConnection::Advise}\label{wxddeconnectionadvise}
  85
  86 \func{bool}{Advise}{\param{const wxString\& }{item}, \param{const char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
  87
  88 Called by the server application to advise the client of a change in
  89 the data associated with the given item. Causes the client
  90 connection's \helpref{wxDDEConnection::OnAdvise}{wxddeconnectiononadvise}
  91 member to be called. Returns true if successful.
  92
  93 \membersection{wxDDEConnection::Execute}\label{wxddeconnectionexecute}
  94
  95 \func{bool}{Execute}{\param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
  96
  97 Called by the client application to execute a command on the server. Can
  98 also be used to transfer arbitrary data to the server (similar
  99 to \helpref{wxDDEConnection::Poke}{wxddeconnectionpoke} in that respect). Causes the
 100 server connection's \helpref{wxDDEConnection::OnExecute}{wxddeconnectiononexecute} member to be
 101 called. Returns true if successful.
 102
 103 \membersection{wxDDEConnection::Disconnect}\label{wxddeconnectiondisconnect}
 104
 105 \func{bool}{Disconnect}{\void}
 106
 107 Called by the client or server application to disconnect from the other
 108 program; it causes the \helpref{wxDDEConnection::OnDisconnect}{wxddeconnectionondisconnect} message
 109 to be sent to the corresponding connection object in the other
 110 program. The default behaviour of {\bf OnDisconnect} is to delete the
 111 connection, but the calling application must explicitly delete its
 112 side of the connection having called {\bf Disconnect}. Returns true if
 113 successful.
 114
 115 \membersection{wxDDEConnection::OnAdvise}\label{wxddeconnectiononadvise}
 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 it of a
 120 change in the data associated with the given item.
 121
 122 \membersection{wxDDEConnection::OnDisconnect}\label{wxddeconnectionondisconnect}
 123
 124 \func{virtual bool}{OnDisconnect}{\void}
 125
 126 Message sent to the client or server application when the other
 127 application notifies it to delete the connection. Default behaviour is
 128 to delete the connection object.
 129
 130 \membersection{wxDDEConnection::OnExecute}\label{wxddeconnectiononexecute}
 131
 132 \func{virtual bool}{OnExecute}{\param{const wxString\& }{topic}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
 133
 134 Message sent to the server application when the client notifies it to
 135 execute the given data. Note that there is no item associated with
 136 this message.
 137
 138 \membersection{wxDDEConnection::OnPoke}\label{wxddeconnectiononpoke}
 139
 140 \func{virtual bool}{OnPoke}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
 141
 142 Message sent to the server application when the client notifies it to
 143 accept the given data.
 144
 145 \membersection{wxDDEConnection::OnRequest}\label{wxddeconnectiononrequest}
 146
 147 \func{virtual const char*}{OnRequest}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{int *}{size}, \param{wxIPCFormat}{ format}}
 148
 149 Message sent to the server application when the client
 150 calls \helpref{wxDDEConnection::Request}{wxddeconnectionrequest}. The server
 151 should respond by returning a character string from {\bf OnRequest},
 152 or NULL to indicate no data.
 153
 154 \membersection{wxDDEConnection::OnStartAdvise}\label{wxddeconnectiononstartadvise}
 155
 156 \func{virtual bool}{OnStartAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
 157
 158 Message sent to the server application by the client, when the client
 159 wishes to start an `advise loop' for the given topic and item. The
 160 server can refuse to participate by returning false.
 161
 162 \membersection{wxDDEConnection::OnStopAdvise}\label{wxddeconnectiononstopadvise}
 163
 164 \func{virtual bool}{OnStopAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
 165
 166 Message sent to the server application by the client, when the client
 167 wishes to stop an `advise loop' for the given topic and item. The
 168 server can refuse to stop the advise loop by returning false, although
 169 this doesn't have much meaning in practice.
 170
 171 \membersection{wxDDEConnection::Poke}\label{wxddeconnectionpoke}
 172
 173 \func{bool}{Poke}{\param{const wxString\& }{item}, \param{const char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
 174
 175 Called by the client application to poke data into the server. Can be
 176 used to transfer arbitrary data to the server. Causes the server
 177 connection's \helpref{wxDDEConnection::OnPoke}{wxddeconnectiononpoke} member
 178 to be called. Returns true if successful.
 179
 180 \membersection{wxDDEConnection::Request}\label{wxddeconnectionrequest}
 181
 182 \func{char*}{Request}{\param{const wxString\& }{item}, \param{int *}{size}, \param{wxIPCFormat}{ format = wxIPC\_TEXT}}
 183
 184 Called by the client application to request data from the server. Causes
 185 the server connection's \helpref{wxDDEConnection::OnRequest}{wxddeconnectiononrequest} member to be called. Returns a
 186 character string (actually a pointer to the connection's buffer) if
 187 successful, NULL otherwise.
 188
 189 \membersection{wxDDEConnection::StartAdvise}\label{wxddeconnectionstartadvise}
 190
 191 \func{bool}{StartAdvise}{\param{const wxString\& }{item}}
 192
 193 Called by the client application to ask if an advise loop can be started
 194 with the server. Causes the server connection's \helpref{wxDDEConnection::OnStartAdvise}{wxddeconnectiononstartadvise}\rtfsp
 195 member to be called. Returns true if the server okays it, false
 196 otherwise.
 197
 198 \membersection{wxDDEConnection::StopAdvise}\label{wxddeconnectionstopadvise}
 199
 200 \func{bool}{StopAdvise}{\param{const wxString\& }{item}}
 201
 202 Called by the client application to ask if an advise loop can be
 203 stopped. Causes the server connection's \helpref{wxDDEConnection::OnStopAdvise}{wxddeconnectiononstopadvise} member
 204 to be called. Returns true if the server okays it, false otherwise.
 205