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