docs/latex/wx/tcpconn.tex

   1 \section{\class{wxTCPConnection}}\label{wxtcpconnection}
   2
   3 A wxTCPClient object represents the connection between a client and a server.
   4 It emulates a DDE-style protocol, but uses TCP/IP which is available on most platforms.
   5
   6 A DDE-based implementation for Windows is available using \helpref{wxDDEConnection}{wxddeconnection}.
   7
   8 A wxTCPConnection object can be created by making a connection using a\rtfsp
   9 \helpref{wxTCPClient}{wxtcpclient} object, or by the acceptance of a connection by a\rtfsp
  10 \helpref{wxTCPServer}{wxtcpserver} object. The bulk of a conversation is controlled by
  11 calling members in a {\bf wxTCPConnection} object or by overriding its
  12 members.
  13
  14 An application should normally derive a new connection class from
  15 wxTCPConnection, in order to override the communication event handlers
  16 to do something interesting.
  17
  18 \wxheading{Derived from}
  19
  20 wxConnectionBase\\
  21 \helpref{wxObject}{wxobject}
  22
  23 \wxheading{Include files}
  24
  25 <wx/sckipc.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{wxTCPClient}{wxtcpclient}, \helpref{wxTCPServer}{wxtcpserver}, \helpref{Interprocess communications overview}{ipcoverview}
  58
  59 \latexignore{\rtfignore{\wxheading{Members}}}
  60
  61 \membersection{wxTCPConnection::wxTCPConnection}\label{wxtcpconnectionctor}
  62
  63 \func{}{wxTCPConnection}{\void}
  64
  65 \func{}{wxTCPConnection}{\param{char* }{buffer}, \param{int}{ size}}
  66
  67 Constructs a connection object. If no user-defined connection object is
  68 to be derived from wxTCPConnection, then the constructor should not be
  69 called directly, since the default connection object will be provided on
  70 requesting (or accepting) a connection. However, if the user defines his
  71 or her own derived connection object, the \helpref{wxTCPServer::OnAcceptConnection}{wxtcpserveronacceptconnection}\rtfsp
  72 and/or \helpref{wxTCPClient::OnMakeConnection}{wxtcpclientonmakeconnection} members should be replaced by
  73 functions which construct the new connection object. If the arguments of
  74 the wxTCPConnection constructor are void, then a default buffer is
  75 associated with the connection. Otherwise, the programmer must provide a
  76 a buffer and size of the buffer for the connection object to use in
  77 transactions.
  78
  79 \membersection{wxTCPConnection::Advise}\label{wxtcpconnectionadvise}
  80
  81 \func{bool}{Advise}{\param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
  82
  83 Called by the server application to advise the client of a change in
  84 the data associated with the given item. Causes the client
  85 connection's \helpref{wxTCPConnection::OnAdvise}{wxtcpconnectiononadvise}
  86 member to be called. Returns true if successful.
  87
  88 \membersection{wxTCPConnection::Execute}\label{wxtcpconnectionexecute}
  89
  90 \func{bool}{Execute}{\param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
  91
  92 Called by the client application to execute a command on the server. Can
  93 also be used to transfer arbitrary data to the server (similar
  94 to \helpref{wxTCPConnection::Poke}{wxtcpconnectionpoke} in that respect). Causes the
  95 server connection's \helpref{wxTCPConnection::OnExecute}{wxtcpconnectiononexecute} member to be
  96 called. Returns true if successful.
  97
  98 \membersection{wxTCPConnection::Disconnect}\label{wxtcpconnectiondisconnect}
  99
 100 \func{bool}{Disconnect}{\void}
 101
 102 Called by the client or server application to disconnect from the other
 103 program; it causes the \helpref{wxTCPConnection::OnDisconnect}{wxtcpconnectionondisconnect} message
 104 to be sent to the corresponding connection object in the other
 105 program. The default behaviour of {\bf OnDisconnect} is to delete the
 106 connection, but the calling application must explicitly delete its
 107 side of the connection having called {\bf Disconnect}. Returns true if
 108 successful.
 109
 110 \membersection{wxTCPConnection::OnAdvise}\label{wxtcpconnectiononadvise}
 111
 112 \func{virtual bool}{OnAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
 113
 114 Message sent to the client application when the server notifies it of a
 115 change in the data associated with the given item.
 116
 117 \membersection{wxTCPConnection::OnDisconnect}\label{wxtcpconnectionondisconnect}
 118
 119 \func{virtual bool}{OnDisconnect}{\void}
 120
 121 Message sent to the client or server application when the other
 122 application notifies it to delete the connection. Default behaviour is
 123 to delete the connection object.
 124
 125 \membersection{wxTCPConnection::OnExecute}\label{wxtcpconnectiononexecute}
 126
 127 \func{virtual bool}{OnExecute}{\param{const wxString\& }{topic}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
 128
 129 Message sent to the server application when the client notifies it to
 130 execute the given data. Note that there is no item associated with
 131 this message.
 132
 133 \membersection{wxTCPConnection::OnPoke}\label{wxtcpconnectiononpoke}
 134
 135 \func{virtual bool}{OnPoke}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size}, \param{wxIPCFormat}{ format}}
 136
 137 Message sent to the server application when the client notifies it to
 138 accept the given data.
 139
 140 \membersection{wxTCPConnection::OnRequest}\label{wxtcpconnectiononrequest}
 141
 142 \func{virtual char*}{OnRequest}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{int *}{size}, \param{wxIPCFormat}{ format}}
 143
 144 Message sent to the server application when the client
 145 calls \helpref{wxTCPConnection::Request}{wxtcpconnectionrequest}. The server
 146 should respond by returning a character string from {\bf OnRequest},
 147 or NULL to indicate no data.
 148
 149 \membersection{wxTCPConnection::OnStartAdvise}\label{wxtcpconnectiononstartadvise}
 150
 151 \func{virtual bool}{OnStartAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
 152
 153 Message sent to the server application by the client, when the client
 154 wishes to start an `advise loop' for the given topic and item. The
 155 server can refuse to participate by returning false.
 156
 157 \membersection{wxTCPConnection::OnStopAdvise}\label{wxtcpconnectiononstopadvise}
 158
 159 \func{virtual bool}{OnStopAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
 160
 161 Message sent to the server application by the client, when the client
 162 wishes to stop an `advise loop' for the given topic and item. The
 163 server can refuse to stop the advise loop by returning false, although
 164 this doesn't have much meaning in practice.
 165
 166 \membersection{wxTCPConnection::Poke}\label{wxtcpconnectionpoke}
 167
 168 \func{bool}{Poke}{\param{const wxString\& }{item}, \param{char* }{data}, \param{int}{ size = -1}, \param{wxIPCFormat}{ format = wxCF\_TEXT}}
 169
 170 Called by the client application to poke data into the server. Can be
 171 used to transfer arbitrary data to the server. Causes the server
 172 connection's \helpref{wxTCPConnection::OnPoke}{wxtcpconnectiononpoke} member
 173 to be called. Returns true if successful.
 174
 175 \membersection{wxTCPConnection::Request}\label{wxtcpconnectionrequest}
 176
 177 \func{char*}{Request}{\param{const wxString\& }{item}, \param{int *}{size}, \param{wxIPCFormat}{ format = wxIPC\_TEXT}}
 178
 179 Called by the client application to request data from the server. Causes
 180 the server connection's \helpref{wxTCPConnection::OnRequest}{wxtcpconnectiononrequest} member to be called. Returns a
 181 character string (actually a pointer to the connection's buffer) if
 182 successful, NULL otherwise.
 183
 184 \membersection{wxTCPConnection::StartAdvise}\label{wxtcpconnectionstartadvise}
 185
 186 \func{bool}{StartAdvise}{\param{const wxString\& }{item}}
 187
 188 Called by the client application to ask if an advise loop can be started
 189 with the server. Causes the server connection's \helpref{wxTCPConnection::OnStartAdvise}{wxtcpconnectiononstartadvise}\rtfsp
 190 member to be called. Returns true if the server okays it, false
 191 otherwise.
 192
 193 \membersection{wxTCPConnection::StopAdvise}\label{wxtcpconnectionstopadvise}
 194
 195 \func{bool}{StopAdvise}{\param{const wxString\& }{item}}
 196
 197 Called by the client application to ask if an advise loop can be
 198 stopped. Causes the server connection's \helpref{wxTCPConnection::OnStopAdvise}{wxtcpconnectiononstopadvise} member
 199 to be called. Returns true if the server okays it, false otherwise.
 200