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