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 (available in both Windows and UNIX) 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 \wxheading{Derived from}
  16
  17 \helpref{wxObject}{wxobject}
  18
  19 \wxheading{See also}
  20
  21 \helpref{wxDDEClient}{wxddeclient}, \helpref{wxDDEServer}{wxddeserver}, \helpref{Interprocess communications overview}{ipcoverview}
  22
  23 \latexignore{\rtfignore{\wxheading{Members}}}
  24
  25 \membersection{wxDDEConnection::wxDDEConnection}
  26
  27 \func{}{wxDDEConnection}{\void}
  28
  29 \func{}{wxDDEConnection}{\param{char* }{buffer}, \param{int}{ size}}
  30
  31 Constructs a connection object. If no user-defined connection object is
  32 to be derived from wxDDEConnection, then the constructor should not be
  33 called directly, since the default connection object will be provided on
  34 requesting (or accepting) a connection. However, if the user defines his
  35 or her own derived connection object, the \helpref{wxDDEServer::OnAcceptConnection}{wxddeserveronacceptconnection}\rtfsp
  36 and/or \helpref{wxDDEClient::OnMakeConnection}{wxddeclientonmakeconnection} members should be replaced by
  37 functions which construct the new connection object. If the arguments of
  38 the wxDDEConnection constructor are void, then a default buffer is
  39 associated with the connection. Otherwise, the programmer must provide a
  40 a buffer and size of the buffer for the connection object to use in
  41 transactions.
  42
  43 \membersection{wxDDEConnection::Advise}
  44
  45 \func{bool}{Advise}{\param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size = -1}, \param{int}{ format = wxCF\_TEXT}}
  46
  47 Called by the server application to advise the client of a change in
  48 the data associated with the given item. Causes the client
  49 connection's \helpref{wxDDEConnection::OnAdvise}{wxddeconnectiononadvise}
  50 member to be called. Returns TRUE if successful.
  51
  52 \membersection{wxDDEConnection::Execute}
  53
  54 \func{bool}{Execute}{\param{char* }{data}, \param{int}{ size = -1},
  55 \param{int}{ format = wxCF\_TEXT}}
  56
  57 Called by the client application to execute a command on the server. Can
  58 also be used to transfer arbitrary data to the server (similar
  59 to \helpref{wxDDEConnection::Poke}{wxddeconnectionpoke} in that respect). Causes the
  60 server connection's \helpref{wxDDEConnection::OnExecute}{wxddeconnectiononexecute} member to be
  61 called. Returns TRUE if successful.
  62
  63 \membersection{wxDDEConnection::Disconnect}
  64
  65 \func{bool}{Disconnect}{\void}
  66
  67 Called by the client or server application to disconnect from the other
  68 program; it causes the \helpref{wxDDEConnection::OnDisconnect}{wxddeconnectionondisconnect} message
  69 to be sent to the corresponding connection object in the other
  70 program. The default behaviour of {\bf OnDisconnect} is to delete the
  71 connection, but the calling application must explicitly delete its
  72 side of the connection having called {\bf Disconnect}. Returns TRUE if
  73 successful.
  74
  75 \membersection{wxDDEConnection::OnAdvise}\label{wxddeconnectiononadvise}
  76
  77 \func{bool}{OnAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{int}{ format}}
  78
  79 Message sent to the client application when the server notifies it of a
  80 change in the data associated with the given item.
  81
  82 \membersection{wxDDEConnection::OnDisconnect}\label{wxddeconnectionondisconnect}
  83
  84 \func{bool}{OnDisconnect}{\void}
  85
  86 Message sent to the client or server application when the other
  87 application notifies it to delete the connection. Default behaviour is
  88 to delete the connection object.
  89
  90 \membersection{wxDDEConnection::OnExecute}\label{wxddeconnectiononexecute}
  91
  92 \func{bool}{OnExecute}{\param{const wxString\& }{topic}, \param{char* }{data}, \param{int}{ size}, \param{int}{ format}}
  93
  94 Message sent to the server application when the client notifies it to
  95 execute the given data. Note that there is no item associated with
  96 this message.
  97
  98 \membersection{wxDDEConnection::OnPoke}\label{wxddeconnectiononpoke}
  99
 100 \func{bool}{OnPoke}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{int}{ format}}
 101
 102 Message sent to the server application when the client notifies it to
 103 accept the given data.
 104
 105 \membersection{wxDDEConnection::OnRequest}\label{wxddeconnectiononrequest}
 106
 107 \func{char*}{OnRequest}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{int *}{size}, \param{int}{ format}}
 108
 109 Message sent to the server application when the client
 110 calls \helpref{wxDDEConnection::Request}{wxddeconnectionrequest}. The server
 111 should respond by returning a character string from {\bf OnRequest},
 112 or NULL to indicate no data.
 113
 114 \membersection{wxDDEConnection::OnStartAdvise}\label{wxddeconnectiononstartadvise}
 115
 116 \func{bool}{OnStartAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
 117
 118 Message sent to the server application by the client, when the client
 119 wishes to start an `advise loop' for the given topic and item. The
 120 server can refuse to participate by returning FALSE.
 121
 122 \membersection{wxDDEConnection::OnStopAdvise}\label{wxddeconnectiononstopadvise}
 123
 124 \func{bool}{OnStopAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
 125
 126 Message sent to the server application by the client, when the client
 127 wishes to stop an `advise loop' for the given topic and item. The
 128 server can refuse to stop the advise loop by returning FALSE, although
 129 this doesn't have much meaning in practice.
 130
 131 \membersection{wxDDEConnection::Poke}\label{wxddeconnectionpoke}
 132
 133 \func{bool}{Poke}{\param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size = -1}, \param{int}{ format = wxCF\_TEXT}}
 134
 135 Called by the client application to poke data into the server. Can be
 136 used to transfer arbitrary data to the server. Causes the server
 137 connection's \helpref{wxDDEConnection::OnPoke}{wxddeconnectiononpoke} member
 138 to be called. Returns TRUE if successful.
 139
 140 \membersection{wxDDEConnection::Request}\label{wxddeconnectionrequest}
 141
 142 \func{char*}{Request}{\param{const wxString\& }{item}, \param{int *}{size}, \param{int}{ format = wxCF\_TEXT}}
 143
 144 Called by the client application to request data from the server. Causes
 145 the server connection's \helpref{wxDDEConnection::OnRequest}{wxddeconnectiononrequest} member to be called. Returns a
 146 character string (actually a pointer to the connection's buffer) if
 147 successful, NULL otherwise.
 148
 149 \membersection{wxDDEConnection::StartAdvise}\label{wxddeconnectionstartadvise}
 150
 151 \func{bool}{StartAdvise}{\param{const wxString\& }{item}}
 152
 153 Called by the client application to ask if an advise loop can be started
 154 with the server. Causes the server connection's \helpref{wxDDEConnection::OnStartAdvise}{wxddeconnectiononstartadvise}\rtfsp
 155 member to be called. Returns TRUE if the server okays it, FALSE
 156 otherwise.
 157
 158 \membersection{wxDDEConnection::StopAdvise}\label{wxddeconnectionstopadvise}
 159
 160 \func{bool}{StopAdvise}{\param{const wxString\& }{item}}
 161
 162 Called by the client application to ask if an advise loop can be
 163 stopped. Causes the server connection's \helpref{wxDDEConnection::OnStopAdvise}{wxddeconnectiononstopadvise} member
 164 to be called. Returns TRUE if the server okays it, FALSE otherwise.
 165
 166