1 \section{\class{wxTCPConnection
}}\label{wxtcpconnection
}
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.
6 A DDE-based implementation for Windows is available using
\helpref{wxDDEConnection
}{wxddeconnection
}.
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
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.
18 \wxheading{Derived from
}
21 \helpref{wxObject
}{wxobject
}
23 \wxheading{Include files
}
29 \helpref{wxNet
}{librarieslist
}
33 \index{wxIPCFormat
}wxIPCFormat is defined as follows:
39 wxIPC_TEXT =
1, /* CF_TEXT */
40 wxIPC_BITMAP =
2, /* CF_BITMAP */
41 wxIPC_METAFILE =
3, /* CF_METAFILEPICT */
45 wxIPC_OEMTEXT =
7, /* CF_OEMTEXT */
46 wxIPC_DIB =
8, /* CF_DIB */
51 wxIPC_UTF16TEXT =
13, /* CF_UNICODE */
52 wxIPC_ENHMETAFILE =
14,
53 wxIPC_FILENAME =
15, /* CF_HDROP */
57 #if SIZEOF_WCHAR_T ==
2
58 wxIPC_UNICODETEXT = wxIPC_UTF16TEXT,
59 #elif SIZEOF_WCHAR_T ==
4
60 wxIPC_UNICODETEXT = wxIPC_UTF32TEXT,
68 \helpref{wxTCPClient
}{wxtcpclient
},
\helpref{wxTCPServer
}{wxtcpserver
},
\helpref{Interprocess communications overview
}{ipcoverview
}
70 \latexignore{\rtfignore{\wxheading{Members
}}}
72 \membersection{wxTCPConnection::wxTCPConnection
}\label{wxtcpconnectionctor
}
74 \func{}{wxTCPConnection
}{\void}
76 \func{}{wxTCPConnection
}{\param{void*
}{buffer
},
\param{size
\_t}{ size
}}
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
90 \membersection{wxTCPConnection::Advise
}\label{wxtcpconnectionadvise
}
92 \func{bool
}{Advise
}{\param{const wxString\&
}{item
},
\param{const void*
}{data
},
\param{size
\_t }{size
},
\param{wxIPCFormat
}{format = wxIPC
\_PRIVATE}}
94 \func{bool
}{Advise
}{\param{const wxString\&
}{item
},
\param{const char*
}{data
},
\param{size
\_t }{size = (size
\_t)-
1}}
96 \func{bool
}{Advise
}{\param{const wxString\&
}{item
},
\param{const wchar
\_t*
}{data
},
\param{size
\_t }{size = (size
\_t)-
1}}
98 \func{bool
}{Advise
}{\param{const wxString\&
}{item
},
\param{const wxString&
}{data
}}
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.
105 \membersection{wxTCPConnection::Execute
}\label{wxtcpconnectionexecute
}
107 \func{bool
}{Execute
}{\param{const void*
}{data
},
\param{size
\_t }{size
},
\param{wxIPCFormat
}{format = wxIPC
\_PRIVATE}}
109 \func{bool
}{Execute
}{\param{const char*
}{data
},
\param{size
\_t }{size = (size
\_t)-
1}}
111 \func{bool
}{Execute
}{\param{const wchar
\_t*
}{data
},
\param{size
\_t }{size = (size
\_t)-
1}}
113 \func{bool
}{Execute
}{\param{const wxString&
}{data
}}
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.
121 \membersection{wxTCPConnection::Disconnect
}\label{wxtcpconnectiondisconnect
}
123 \func{bool
}{Disconnect
}{\void}
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
133 \membersection{wxTCPConnection::OnAdvise
}\label{wxtcpconnectiononadvise
}
135 \func{virtual bool
}{OnAdvise
}{\param{const wxString\&
}{topic
},
\param{const wxString\&
}{item
},
\param{const void*
}{data
},
\param{size
\_t }{size
},
\param{wxIPCFormat
}{format
}}
137 Message sent to the client application when the server notifies it of a
138 change in the data associated with the given item.
140 \membersection{wxTCPConnection::OnDisconnect
}\label{wxtcpconnectionondisconnect
}
142 \func{virtual bool
}{OnDisconnect
}{\void}
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.
148 \membersection{wxTCPConnection::OnExecute
}\label{wxtcpconnectiononexecute
}
150 \func{virtual bool
}{OnExecute
}{\param{const wxString\&
}{topic
},
\param{const void*
}{data
},
\param{size
\_t }{size
},
\param{wxIPCFormat
}{ format
}}
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
156 \membersection{wxTCPConnection::OnPoke
}\label{wxtcpconnectiononpoke
}
158 \func{virtual bool
}{OnPoke
}{\param{const wxString\&
}{topic
},
\param{const wxString\&
}{item
},
\param{const void*
}{data
},
\param{size
\_t }{size
},
\param{wxIPCFormat
}{format
}}
160 Message sent to the server application when the client notifies it to
161 accept the given data.
163 \membersection{wxTCPConnection::OnRequest
}\label{wxtcpconnectiononrequest
}
165 \func{virtual const void*
}{OnRequest
}{\param{const wxString\&
}{topic
},
\param{const wxString\&
}{item
},
\param{size
\_t *
}{size
},
\param{wxIPCFormat
}{format
}}
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.
172 \membersection{wxTCPConnection::OnStartAdvise
}\label{wxtcpconnectiononstartadvise
}
174 \func{virtual bool
}{OnStartAdvise
}{\param{const wxString\&
}{topic
},
\param{const wxString\&
}{item
}}
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.
180 \membersection{wxTCPConnection::OnStopAdvise
}\label{wxtcpconnectiononstopadvise
}
182 \func{virtual bool
}{OnStopAdvise
}{\param{const wxString\&
}{topic
},
\param{const wxString\&
}{item
}}
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.
189 \membersection{wxTCPConnection::Poke
}\label{wxtcpconnectionpoke
}
191 \func{bool
}{Poke
}{\param{const wxString\&
}{item
},
\param{const void*
}{data
},
\param{size
\_t }{size
},
\param{wxIPCFormat
}{format = wxIPC
\_PRIVATE}}
193 \func{bool
}{Poke
}{\param{const wxString\&
}{item
},
\param{const char*
}{data
},
\param{size
\_t }{size = (size
\_t)-
1}}
195 \func{bool
}{Poke
}{\param{const wxString\&
}{item
},
\param{const wchar
\_t*
}{data
},
\param{size
\_t }{size = (size
\_t)-
1}}
197 \func{bool
}{Poke
}{\param{const wxString\&
}{item
},
\param{const wxString&
}{data
}}
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.
204 \membersection{wxTCPConnection::Request
}\label{wxtcpconnectionrequest
}
206 \func{const void*
}{Request
}{\param{const wxString\&
}{item
},
\param{size
\_t *
}{size
},
\param{wxIPCFormat
}{format = wxIPC
\_TEXT}}
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.
213 \membersection{wxTCPConnection::StartAdvise
}\label{wxtcpconnectionstartadvise
}
215 \func{bool
}{StartAdvise
}{\param{const wxString\&
}{item
}}
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
222 \membersection{wxTCPConnection::StopAdvise
}\label{wxtcpconnectionstopadvise
}
224 \func{bool
}{StopAdvise
}{\param{const wxString\&
}{item
}}
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.