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