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_UTF16TEXT =        13, /* CF_UNICODE */
  52   wxIPC_ENHMETAFILE =      14,
  53   wxIPC_FILENAME =         15, /* CF_HDROP */
  54   wxIPC_LOCALE =           16,
  55   wxIPC_UTF8TEXT =         17,
  56   wxIPC_UTF32TEXT =        18,
  57 #if SIZEOF_WCHAR_T == 2
  58   wxIPC_UNICODETEXT =      wxIPC_UTF16TEXT,
  59 #elif SIZEOF_WCHAR_T == 4
  60   wxIPC_UNICODETEXT =      wxIPC_UTF32TEXT,
  61 #endif
  62   wxIPC_PRIVATE =          20
  63 };
  64 \end{verbatim}
  65
  66 \wxheading{See also}
  67
  68 \helpref{wxTCPClient}{wxtcpclient}, \helpref{wxTCPServer}{wxtcpserver}, \helpref{Interprocess communications overview}{ipcoverview}
  69
  70 \latexignore{\rtfignore{\wxheading{Members}}}
  71
  72 \membersection{wxTCPConnection::wxTCPConnection}\label{wxtcpconnectionctor}
  73
  74 \func{}{wxTCPConnection}{\void}
  75
  76 \func{}{wxTCPConnection}{\param{void* }{buffer}, \param{size\_t}{ size}}
  77
  78 Constructs a connection object. If no user-defined connection object is
  79 to be derived from wxTCPConnection, then the constructor should not be
  80 called directly, since the default connection object will be provided on
  81 requesting (or accepting) a connection. However, if the user defines his
  82 or her own derived connection object, the \helpref{wxTCPServer::OnAcceptConnection}{wxtcpserveronacceptconnection}\rtfsp
  83 and/or \helpref{wxTCPClient::OnMakeConnection}{wxtcpclientonmakeconnection} members should be replaced by
  84 functions which construct the new connection object. If the arguments of
  85 the wxTCPConnection constructor are void, then a default buffer is
  86 associated with the connection. Otherwise, the programmer must provide a
  87 a buffer and size of the buffer for the connection object to use in
  88 transactions.
  89
  90 \membersection{wxTCPConnection::Advise}\label{wxtcpconnectionadvise}
  91
  92 \func{bool}{Advise}{\param{const wxString\& }{item}, \param{const void* }{data}, \param{size\_t }{size}, \param{wxIPCFormat }{format = wxIPC\_PRIVATE}}
  93
  94 \func{bool}{Advise}{\param{const wxString\& }{item}, \param{const char* }{data}, \param{size\_t }{size = (size\_t)-1}}
  95
  96 \func{bool}{Advise}{\param{const wxString\& }{item}, \param{const wchar\_t* }{data}, \param{size\_t }{size = (size\_t)-1}}
  97
  98 \func{bool}{Advise}{\param{const wxString\& }{item}, \param{const wxString& }{data}}
  99
 100 Called by the server application to advise the client of a change in
 101 the data associated with the given item. Causes the client
 102 connection's \helpref{wxTCPConnection::OnAdvise}{wxtcpconnectiononadvise}
 103 member to be called. Returns true if successful.
 104
 105 \membersection{wxTCPConnection::Execute}\label{wxtcpconnectionexecute}
 106
 107 \func{bool}{Execute}{\param{const void* }{data}, \param{size\_t }{size}, \param{wxIPCFormat }{format = wxIPC\_PRIVATE}}
 108
 109 \func{bool}{Execute}{\param{const char* }{data}, \param{size\_t }{size = (size\_t)-1}}
 110
 111 \func{bool}{Execute}{\param{const wchar\_t* }{data}, \param{size\_t }{size = (size\_t)-1}}
 112
 113 \func{bool}{Execute}{\param{const wxString& }{data}}
 114
 115 Called by the client application to execute a command on the server. Can
 116 also be used to transfer arbitrary data to the server (similar
 117 to \helpref{wxTCPConnection::Poke}{wxtcpconnectionpoke} in that respect). Causes the
 118 server connection's \helpref{wxTCPConnection::OnExecute}{wxtcpconnectiononexecute} member to be
 119 called. Returns true if successful.
 120
 121 \membersection{wxTCPConnection::Disconnect}\label{wxtcpconnectiondisconnect}
 122
 123 \func{bool}{Disconnect}{\void}
 124
 125 Called by the client or server application to disconnect from the other
 126 program; it causes the \helpref{wxTCPConnection::OnDisconnect}{wxtcpconnectionondisconnect} message
 127 to be sent to the corresponding connection object in the other
 128 program. The default behaviour of {\bf OnDisconnect} is to delete the
 129 connection, but the calling application must explicitly delete its
 130 side of the connection having called {\bf Disconnect}. Returns true if
 131 successful.
 132
 133 \membersection{wxTCPConnection::OnAdvise}\label{wxtcpconnectiononadvise}
 134
 135 \func{virtual bool}{OnAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{const void* }{data}, \param{size\_t }{size}, \param{wxIPCFormat }{format}}
 136
 137 Message sent to the client application when the server notifies it of a
 138 change in the data associated with the given item.
 139
 140 \membersection{wxTCPConnection::OnDisconnect}\label{wxtcpconnectionondisconnect}
 141
 142 \func{virtual bool}{OnDisconnect}{\void}
 143
 144 Message sent to the client or server application when the other
 145 application notifies it to delete the connection. Default behaviour is
 146 to delete the connection object.
 147
 148 \membersection{wxTCPConnection::OnExecute}\label{wxtcpconnectiononexecute}
 149
 150 \func{virtual bool}{OnExecute}{\param{const wxString\& }{topic}, \param{const void* }{data}, \param{size\_t }{size}, \param{wxIPCFormat}{ format}}
 151
 152 Message sent to the server application when the client notifies it to
 153 execute the given data. Note that there is no item associated with
 154 this message.
 155
 156 \membersection{wxTCPConnection::OnPoke}\label{wxtcpconnectiononpoke}
 157
 158 \func{virtual bool}{OnPoke}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{const void* }{data}, \param{size\_t }{size}, \param{wxIPCFormat }{format}}
 159
 160 Message sent to the server application when the client notifies it to
 161 accept the given data.
 162
 163 \membersection{wxTCPConnection::OnRequest}\label{wxtcpconnectiononrequest}
 164
 165 \func{virtual const void*}{OnRequest}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}, \param{size\_t *}{size}, \param{wxIPCFormat }{format}}
 166
 167 Message sent to the server application when the client
 168 calls \helpref{wxTCPConnection::Request}{wxtcpconnectionrequest}. The server
 169 should respond by returning a character string from {\bf OnRequest},
 170 or NULL to indicate no data.
 171
 172 \membersection{wxTCPConnection::OnStartAdvise}\label{wxtcpconnectiononstartadvise}
 173
 174 \func{virtual bool}{OnStartAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
 175
 176 Message sent to the server application by the client, when the client
 177 wishes to start an `advise loop' for the given topic and item. The
 178 server can refuse to participate by returning false.
 179
 180 \membersection{wxTCPConnection::OnStopAdvise}\label{wxtcpconnectiononstopadvise}
 181
 182 \func{virtual bool}{OnStopAdvise}{\param{const wxString\& }{topic}, \param{const wxString\& }{item}}
 183
 184 Message sent to the server application by the client, when the client
 185 wishes to stop an `advise loop' for the given topic and item. The
 186 server can refuse to stop the advise loop by returning false, although
 187 this doesn't have much meaning in practice.
 188
 189 \membersection{wxTCPConnection::Poke}\label{wxtcpconnectionpoke}
 190
 191 \func{bool}{Poke}{\param{const wxString\& }{item}, \param{const void* }{data}, \param{size\_t }{size}, \param{wxIPCFormat }{format = wxIPC\_PRIVATE}}
 192
 193 \func{bool}{Poke}{\param{const wxString\& }{item}, \param{const char* }{data}, \param{size\_t }{size = (size\_t)-1}}
 194
 195 \func{bool}{Poke}{\param{const wxString\& }{item}, \param{const wchar\_t* }{data}, \param{size\_t }{size = (size\_t)-1}}
 196
 197 \func{bool}{Poke}{\param{const wxString\& }{item}, \param{const wxString& }{data}}
 198
 199 Called by the client application to poke data into the server. Can be
 200 used to transfer arbitrary data to the server. Causes the server
 201 connection's \helpref{wxTCPConnection::OnPoke}{wxtcpconnectiononpoke} member
 202 to be called. Returns true if successful.
 203
 204 \membersection{wxTCPConnection::Request}\label{wxtcpconnectionrequest}
 205
 206 \func{const void*}{Request}{\param{const wxString\& }{item}, \param{size\_t *}{size}, \param{wxIPCFormat }{format = wxIPC\_TEXT}}
 207
 208 Called by the client application to request data from the server. Causes
 209 the server connection's \helpref{wxTCPConnection::OnRequest}{wxtcpconnectiononrequest} member to be called. Returns a
 210 character string (actually a pointer to the connection's buffer) if
 211 successful, NULL otherwise.
 212
 213 \membersection{wxTCPConnection::StartAdvise}\label{wxtcpconnectionstartadvise}
 214
 215 \func{bool}{StartAdvise}{\param{const wxString\& }{item}}
 216
 217 Called by the client application to ask if an advise loop can be started
 218 with the server. Causes the server connection's \helpref{wxTCPConnection::OnStartAdvise}{wxtcpconnectiononstartadvise}\rtfsp
 219 member to be called. Returns true if the server okays it, false
 220 otherwise.
 221
 222 \membersection{wxTCPConnection::StopAdvise}\label{wxtcpconnectionstopadvise}
 223
 224 \func{bool}{StopAdvise}{\param{const wxString\& }{item}}
 225
 226 Called by the client application to ask if an advise loop can be
 227 stopped. Causes the server connection's \helpref{wxTCPConnection::OnStopAdvise}{wxtcpconnectiononstopadvise} member
 228 to be called. Returns true if the server okays it, false otherwise.
 229