]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/sckipc.h
Updates to Indonesian translations by Rahmat Bambang.
[wxWidgets.git] / interface / wx / sckipc.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: sckipc.h
3 // Purpose: interface of wxTCPServer
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
9
10 /**
11 See wxTCPConnection.
12 */
13 enum wxIPCFormat
14 {
15 wxIPC_INVALID = 0,
16 wxIPC_TEXT = 1, /* CF_TEXT */
17 wxIPC_BITMAP = 2, /* CF_BITMAP */
18 wxIPC_METAFILE = 3, /* CF_METAFILEPICT */
19 wxIPC_SYLK = 4,
20 wxIPC_DIF = 5,
21 wxIPC_TIFF = 6,
22 wxIPC_OEMTEXT = 7, /* CF_OEMTEXT */
23 wxIPC_DIB = 8, /* CF_DIB */
24 wxIPC_PALETTE = 9,
25 wxIPC_PENDATA = 10,
26 wxIPC_RIFF = 11,
27 wxIPC_WAVE = 12,
28 wxIPC_UTF16TEXT = 13, /* CF_UNICODE */
29 wxIPC_ENHMETAFILE = 14,
30 wxIPC_FILENAME = 15, /* CF_HDROP */
31 wxIPC_LOCALE = 16,
32 wxIPC_UTF8TEXT = 17,
33 wxIPC_UTF32TEXT = 18,
34 wxIPC_UNICODETEXT,
35 wxIPC_PRIVATE = 20
36 };
37
38
39 /**
40 @class wxTCPServer
41
42 A wxTCPServer object represents the server part of a client-server conversation.
43 It emulates a DDE-style protocol, but uses TCP/IP which is available on most
44 platforms.
45
46 A DDE-based implementation for Windows is available using wxDDEServer.
47
48 @library{wxnet}
49 @category{net}
50
51 @see wxTCPClient, wxTCPConnection, @ref overview_ipc
52 */
53 class wxTCPServer : public wxObject
54 {
55 public:
56 /**
57 Constructs a server object.
58 */
59 wxTCPServer();
60
61 /**
62 Registers the server using the given service name.
63
64 Under Unix, the string must contain an integer id which is used as an
65 Internet port number. @false is returned if the call failed
66 (for example, the port number is already in use).
67 */
68 virtual bool Create(const wxString& service);
69
70 /**
71 When a client calls @b MakeConnection, the server receives the
72 message and this member is called.
73
74 The application should derive a member to intercept this message and
75 return a connection object of either the standard wxTCPConnection type,
76 or of a user-derived type.
77 If the topic is "STDIO", the application may wish to refuse the connection.
78 Under Unix, when a server is created the OnAcceptConnection message is
79 always sent for standard input and output.
80 */
81 virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
82 };
83
84
85
86 /**
87 @class wxTCPClient
88
89 A wxTCPClient object represents the client part of a client-server conversation.
90 It emulates a DDE-style protocol, but uses TCP/IP which is available on most
91 platforms.
92
93 A DDE-based implementation for Windows is available using wxDDEClient.
94
95 To create a client which can communicate with a suitable server, you need
96 to derive a class from wxTCPConnection and another from wxTCPClient.
97 The custom wxTCPConnection class will intercept communications in
98 a 'conversation' with a server, and the custom wxTCPServer is required
99 so that a user-overridden wxTCPClient::OnMakeConnection() member can return
100 a wxTCPConnection of the required class, when a connection is made.
101
102 @library{wxnet}
103 @category{net}
104
105 @see wxTCPServer, wxTCPConnection, @ref overview_ipc
106 */
107 class wxTCPClient : public wxObject
108 {
109 public:
110 /**
111 Constructs a client object.
112 */
113 wxTCPClient();
114
115 /**
116 Tries to make a connection with a server specified by the host
117 (a machine name under Unix), service name (must contain an integer
118 port number under Unix), and a topic string.
119
120 If the server allows a connection, a wxTCPConnection object will be returned.
121
122 The type of wxTCPConnection returned can be altered by overriding
123 the OnMakeConnection() member to return your own derived connection object.
124 */
125 virtual wxConnectionBase* MakeConnection(const wxString& host,
126 const wxString& service,
127 const wxString& topic);
128
129 /**
130 The type of wxTCPConnection returned from a MakeConnection() call can
131 be altered by deriving the @b OnMakeConnection member to return your
132 own derived connection object. By default, a wxTCPConnection
133 object is returned.
134
135 The advantage of deriving your own connection class is that it will
136 enable you to intercept messages initiated by the server, such
137 as wxTCPConnection::OnAdvise(). You may also want to store
138 application-specific data in instances of the new class.
139 */
140 virtual wxConnectionBase* OnMakeConnection();
141
142 /**
143 Returns @true if this is a valid host name, @false otherwise.
144 */
145 virtual bool ValidHost(const wxString& host);
146 };
147
148
149
150 /**
151 @class wxTCPConnection
152
153 A wxTCPClient object represents the connection between a client and a server.
154 It emulates a DDE-style protocol, but uses TCP/IP which is available on most
155 platforms.
156
157 A DDE-based implementation for Windows is available using wxDDEConnection.
158
159 A wxTCPConnection object can be created by making a connection using a
160 wxTCPClient object, or by the acceptance of a connection by a wxTCPServer object.
161 The bulk of a conversation is controlled by calling members in a
162 @b wxTCPConnection object or by overriding its members.
163
164 An application should normally derive a new connection class from
165 wxTCPConnection, in order to override the communication event handlers
166 to do something interesting.
167
168 @library{wxnet}
169 @category{net}
170
171 @see wxTCPClient, wxTCPServer, @ref overview_ipc
172 */
173 class wxTCPConnection : public wxObject
174 {
175 public:
176 //@{
177 /**
178 Constructs a connection object.
179
180 If no user-defined connection object is to be derived from wxTCPConnection,
181 then the constructor should not be called directly, since the default
182 connection object will be provided on requesting (or accepting) a connection.
183
184 However, if the user defines his or her own derived connection object,
185 the wxTCPServer::OnAcceptConnection and/or wxTCPClient::OnMakeConnection
186 members should be replaced by functions which construct the new connection object.
187
188 If the arguments of the wxTCPConnection constructor are void, then a default
189 buffer is associated with the connection. Otherwise, the programmer must
190 provide a buffer and size of the buffer for the connection object to use in
191 transactions.
192 */
193 wxTCPConnection();
194 wxTCPConnection(void* buffer, size_t size);
195 //@}
196
197 //@{
198 /**
199 Called by the server application to advise the client of a change in
200 the data associated with the given item.
201
202 Causes the client connection's OnAdvise() member to be called.
203
204 Returns @true if successful.
205 */
206 bool Advise(const wxString& item, const void* data, size_t size,
207 wxIPCFormat format = wxIPC_PRIVATE);
208 bool Advise(const wxString& item, const char* data);
209 bool Advise(const wxString& item, const wchar_t* data);
210 bool Advise(const wxString& item, const wxString data);
211 //@}
212
213 /**
214 Called by the client or server application to disconnect from the other
215 program; it causes the OnDisconnect() message to be sent to the
216 corresponding connection object in the other program.
217
218 The default behaviour of @b OnDisconnect is to delete the
219 connection, but the calling application must explicitly delete its
220 side of the connection having called @b Disconnect.
221
222 Returns @true if successful.
223 */
224 virtual bool Disconnect();
225
226 //@{
227 /**
228 Called by the client application to execute a command on the server.
229 Can also be used to transfer arbitrary data to the server (similar
230 to Poke() in that respect). Causes the server connection's OnExecute()
231 member to be called.
232
233 Returns @true if successful.
234 */
235 bool Execute(const void* data, size_t size,
236 wxIPCFormat format = wxIPC_PRIVATE);
237 bool Execute(const char* data);
238 bool Execute(const wchar_t* data);
239 bool Execute(const wxString data);
240 //@}
241
242 /**
243 Message sent to the client application when the server notifies it of a
244 change in the data associated with the given item.
245 */
246 virtual bool OnAdvise(const wxString& topic,
247 const wxString& item,
248 const void* data,
249 size_t size,
250 wxIPCFormat format);
251
252 /**
253 Message sent to the client or server application when the other
254 application notifies it to delete the connection.
255 Default behaviour is to delete the connection object.
256 */
257 virtual bool OnDisconnect();
258
259 /**
260 Message sent to the server application when the client notifies it to
261 execute the given data.
262 Note that there is no item associated with this message.
263 */
264 virtual bool OnExecute(const wxString& topic, const void* data,
265 size_t size,
266 wxIPCFormat format);
267
268 /**
269 Message sent to the server application when the client notifies it to
270 accept the given data.
271 */
272 virtual bool OnPoke(const wxString& topic, const wxString& item,
273 const void* data,
274 size_t size,
275 wxIPCFormat format);
276
277 /**
278 Message sent to the server application when the client calls Request().
279
280 The server should respond by returning a character string from @b OnRequest,
281 or @NULL to indicate no data.
282 */
283 virtual const void* OnRequest(const wxString& topic,
284 const wxString& item,
285 size_t* size,
286 wxIPCFormat format);
287
288 /**
289 Message sent to the server application by the client, when the client
290 wishes to start an 'advise loop' for the given topic and item.
291 The server can refuse to participate by returning @false.
292 */
293 virtual bool OnStartAdvise(const wxString& topic,
294 const wxString& item);
295
296 /**
297 Message sent to the server application by the client, when the client
298 wishes to stop an 'advise loop' for the given topic and item.
299 The server can refuse to stop the advise loop by returning @false, although
300 this doesn't have much meaning in practice.
301 */
302 virtual bool OnStopAdvise(const wxString& topic,
303 const wxString& item);
304
305 //@{
306 /**
307 Called by the client application to poke data into the server.
308 Can be used to transfer arbitrary data to the server. Causes the server
309 connection's OnPoke() member to be called. Returns @true if successful.
310 */
311 bool Poke(const wxString& item, const void* data, size_t size,
312 wxIPCFormat format = wxIPC_PRIVATE);
313 bool Poke(const wxString& item, const char* data);
314 bool Poke(const wxString& item, const wchar_t* data);
315 bool Poke(const wxString& item, const wxString data);
316 //@}
317
318 /**
319 Called by the client application to request data from the server.
320 Causes the server connection's OnRequest() member to be called.
321
322 Returns a character string (actually a pointer to the connection's buffer) if
323 successful, @NULL otherwise.
324 */
325 virtual const void* Request(const wxString& item, size_t* size = 0,
326 wxIPCFormat format = wxIPC_TEXT);
327
328 /**
329 Called by the client application to ask if an advise loop can be started
330 with the server.
331
332 Causes the server connection's OnStartAdvise() member to be called.
333 Returns @true if the server okays it, @false otherwise.
334 */
335 virtual bool StartAdvise(const wxString& item);
336
337 /**
338 Called by the client application to ask if an advise loop can be stopped.
339 Causes the server connection's OnStopAdvise() member to be called.
340 Returns @true if the server okays it, @false otherwise.
341 */
342 virtual bool StopAdvise(const wxString& item);
343 };
344