]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/ipc.h
support for iPhone callbacks
[wxWidgets.git] / interface / wx / ipc.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: ipc.h
3 // Purpose: interface of wxConnection
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxConnection
11
12 A wxConnection object represents the connection between a client and a server.
13 It is created by making a connection using a wxClient object, or by the acceptance
14 of a connection by a wxServer object.
15
16 The bulk of a DDE-like (Dynamic Data Exchange) conversation is controlled by
17 calling members in a @b wxConnection object or by overriding its members.
18 The actual DDE-based implementation using wxDDEConnection is available on
19 Windows only, but a platform-independent, socket-based version of this API is
20 available using wxTCPConnection, which has the same API.
21
22 An application should normally derive a new connection class from wxConnection,
23 in order to override the communication event handlers to do something interesting.
24
25 @library{wxbase}
26 @category{ipc}
27
28 @see wxClient, wxServer, @ref overview_ipc
29 */
30 class wxConnection : public wxObject
31 {
32 public:
33 //@{
34 /**
35 Constructs a connection object.
36
37 If no user-defined connection object is to be derived from wxConnection,
38 then the constructor should not be called directly, since the default connection
39 object will be provided on requesting (or accepting) a connection.
40
41 However, if the user defines his or her own derived connection object,
42 the wxServer::OnAcceptConnection and/or wxClient::OnMakeConnection
43 members should be replaced by functions which construct the new
44 connection object.
45
46 If the arguments of the wxConnection constructor are void then
47 the wxConnection object manages its own connection buffer,
48 allocating memory as needed. A programmer-supplied buffer cannot
49 be increased if necessary, and the program will assert if it is
50 not large enough.
51
52 The programmer-supplied buffer is included mainly for backwards compatibility.
53 */
54 wxConnection();
55 wxConnection(void* buffer, size_t size);
56 //@}
57
58 //@{
59 /**
60 Called by the server application to advise the client of a change
61 in the data associated with the given item. Causes the client
62 connection's OnAdvise() member to be called.
63
64 @return @true if successful.
65 */
66 bool Advise(const wxString& item, const void* data, size_t size,
67 wxIPCFormat format = wxIPC_PRIVATE);
68 bool Advise(const wxString& item, const char* data);
69 bool Advise(const wxString& item, const wchar_t* data);
70 bool Advise(const wxString& item, const wxString data);
71 //@}
72
73 /**
74 Called by the client or server application to disconnect from the
75 other program; it causes the OnDisconnect() message to be sent to the
76 corresponding connection object in the other program.
77
78 Returns @true if successful or already disconnected.
79 The application that calls Disconnect() must explicitly delete
80 its side of the connection.
81 */
82 bool Disconnect();
83
84 //@{
85 /**
86 Called by the client application to execute a command on the server.
87 Can also be used to transfer arbitrary data to the server (similar to
88 Poke() in that respect). Causes the server connection's OnExec()
89 member to be called. Returns @true if successful.
90 */
91 bool Execute(const void* data, size_t size,
92 wxIPCFormat format = wxIPC_PRIVATE);
93 bool Execute(const char* data);
94 bool Execute(const wchar_t* data);
95 bool Execute(const wxString data);
96 //@}
97
98 /**
99 Message sent to the client application when the server notifies it of a
100 change in the data associated with the given item, using Advise().
101 */
102 virtual bool OnAdvise(const wxString& topic,
103 const wxString& item,
104 const void* data,
105 size_t size,
106 wxIPCFormat format);
107
108 /**
109 Message sent to the client or server application when the other
110 application notifies it to end the connection.
111
112 The default behaviour is to delete the connection object and return @true,
113 so applications should generally override OnDisconnect() (finally calling
114 the inherited method as well) so that they know the connection object is
115 no longer available.
116 */
117 virtual bool OnDisconnect();
118
119 /**
120 Message sent to the server application when the client notifies
121 it to execute the given data, using Execute().
122
123 Note that there is no item associated with this message.
124 */
125 virtual bool OnExec(const wxString& topic, const wxString& data);
126
127 /**
128 Message sent to the server application when the client notifies it to
129 accept the given data.
130 */
131 virtual bool OnPoke(const wxString& topic, const wxString& item,
132 const void* data,
133 size_t size,
134 wxIPCFormat format);
135
136 /**
137 Message sent to the server application when the client calls Request().
138 The server's OnRequest() method should respond by returning a character
139 string, or @NULL to indicate no data, and setting *size.
140
141 The character string must of course persist after the call returns.
142 */
143 virtual const void* OnRequest(const wxString& topic,
144 const wxString& item,
145 size_t* size,
146 wxIPCFormat format);
147
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.
151 The server can refuse to participate by returning @false.
152 */
153 virtual bool OnStartAdvise(const wxString& topic,
154 const wxString& item);
155
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.
159 The server can refuse to stop the advise loop by returning @false, although
160 this doesn't have much meaning in practice.
161 */
162 virtual bool OnStopAdvise(const wxString& topic,
163 const wxString& item);
164
165 //@{
166 /**
167 Called by the client application to poke data into the server.
168 Can be used to transfer arbitrary data to the server.
169 Causes the server connection's OnPoke() member to be called.
170 If size is -1 the size is computed from the string length of data.
171
172 Returns @true if successful.
173 */
174 bool Poke(const wxString& item, const void* data, size_t size,
175 wxIPCFormat format = wxIPC_PRIVATE);
176 bool Poke(const wxString& item, const char* data);
177 bool Poke(const wxString& item, const wchar_t* data);
178 bool Poke(const wxString& item, const wxString data);
179 //@}
180
181 /**
182 Called by the client application to request data from the server.
183 Causes the server connection's OnRequest() member to be called.
184 Size may be @NULL or a pointer to a variable to receive the size of the
185 requested item.
186
187 Returns a character string (actually a pointer to the connection's buffer)
188 if successful, @NULL otherwise. This buffer does not need to be deleted.
189 */
190 const void* Request(const wxString& item, size_t* size,
191 wxIPCFormat format = wxIPC_TEXT);
192
193 /**
194 Called by the client application to ask if an advise loop can be started
195 with the server. Causes the server connection's OnStartAdvise()
196 member to be called.
197 Returns @true if the server okays it, @false otherwise.
198 */
199 bool StartAdvise(const wxString& item);
200
201 /**
202 Called by the client application to ask if an advise loop can be stopped.
203 Causes the server connection's OnStopAdvise() member to be called.
204 Returns @true if the server okays it, @false otherwise.
205 */
206 bool StopAdvise(const wxString& item);
207
208 /**
209 Returns true if the format is one of the text formats.
210
211 The text formats are wxIPC_TEXT, wxIPC_UNICODETEXT and wxIPC_UTF8TEXT.
212 */
213 static bool IsTextFormat(wxIPCFormat format);
214
215 /**
216 Returns the data in any of the text formats as string.
217
218 @param data
219 The raw data pointer as used with any of the other methods of this
220 class.
221 @param size
222 The size of the data buffer pointed to by @a data.
223 @param format
224 The format of the data. It must be a text one, i.e. such that
225 IsTextFormat() returns @true for it.
226 @return
227 The string representation of the data. If the format is not text,
228 an assertion failure is triggered and empty string is returned.
229 */
230 static wxString
231 GetTextFromData(const void *data, size_t size, wxIPCFormat format);
232 };
233
234
235
236 /**
237 @class wxClient
238
239 A wxClient object represents the client part of a client-server
240 DDE-like (Dynamic Data Exchange) conversation.
241 The actual DDE-based implementation using wxDDEClient is available on Windows
242 only, but a platform-independent, socket-based version of this API is available
243 using wxTCPClient, which has the same API.
244
245 To create a client which can communicate with a suitable server, you need to
246 derive a class from wxConnection and another from wxClient.
247 The custom wxConnection class will intercept communications in a 'conversation'
248 with a server, and the custom wxClient is required so that a user-overridden
249 wxClient::OnMakeConnection member can return a wxConnection of the required
250 class, when a connection is made.
251
252 Look at the IPC sample and the @ref overview_ipc for an example of how to do this.
253
254 @library{wxbase}
255 @category{ipc}
256
257 @see wxServer, wxConnection, @ref overview_ipc
258 */
259 class wxClient : public wxObject
260 {
261 public:
262 /**
263 Constructs a client object.
264 */
265 wxClient();
266
267 /**
268 Tries to make a connection with a server by host (machine name
269 under UNIX - use 'localhost' for same machine; ignored when using
270 native DDE in Windows), service name and topic string.
271
272 If the server allows a connection, a wxConnection object will be returned.
273 The type of wxConnection returned can be altered by overriding the
274 OnMakeConnection() member to return your own derived connection object.
275
276 Under Unix, the service name may be either an integer port
277 identifier in which case an Internet domain socket will be used
278 for the communications, or a valid file name (which shouldn't
279 exist and will be deleted afterwards) in which case a Unix domain
280 socket is created.
281
282 @note Using Internet domain sockets is extremely insecure for IPC as
283 there is absolutely no access control for them, use Unix domain
284 sockets whenever possible!
285 */
286 wxConnectionBase* MakeConnection(const wxString& host,
287 const wxString& service,
288 const wxString& topic);
289
290 /**
291 Called by MakeConnection(), by default this simply returns a new wxConnection
292 object. Override this method to return a wxConnection descendant customised
293 for the application.
294
295 The advantage of deriving your own connection class is that it will enable
296 you to intercept messages initiated by the server, such as wxConnection::OnAdvise.
297 You may also want to store application-specific data in instances of
298 the new class.
299 */
300 wxConnectionBase* OnMakeConnection();
301
302 /**
303 Returns @true if this is a valid host name, @false otherwise.
304 This always returns @true under MS Windows.
305 */
306 bool ValidHost(const wxString& host);
307 };
308
309
310
311 /**
312 @class wxServer
313
314 A wxServer object represents the server part of a client-server DDE-like
315 (Dynamic Data Exchange) conversation. The actual DDE-based implementation
316 using wxDDEServer is available on Windows only, but a platform-independent,
317 socket-based version of this API is available using wxTCPServer, which has
318 the same API.
319
320 To create a server which can communicate with a suitable client, you need to
321 derive a class from wxConnection and another from wxServer.
322 The custom wxConnection class will intercept communications in a 'conversation'
323 with a client, and the custom wxServer is required so that a user-overridden
324 wxServer::OnAcceptConnection member can return a wxConnection of the required
325 class, when a connection is made.
326 Look at the IPC sample and the @ref overview_ipc for an example of how to do this.
327
328 @library{wxbase}
329 @category{ipc}
330
331 @see wxClient, wxConnection, IPC, @ref overview_ipc
332 */
333 class wxServer
334 {
335 public:
336 /**
337 Constructs a server object.
338 */
339 wxServer();
340
341 /**
342 Registers the server using the given service name.
343 Under Unix, the service name may be either an integer port identifier in
344 which case an Internet domain socket will be used for the communications,
345 or a valid file name (which shouldn't exist and will be deleted afterwards)
346 in which case a Unix domain socket is created.
347
348 @false is returned if the call failed (for example, the port number is
349 already in use).
350 */
351 bool Create(const wxString& service);
352
353 /**
354 When a client calls @b MakeConnection, the server receives the
355 message and this member is called. The application should derive a
356 member to intercept this message and return a connection object of
357 either the standard wxConnection type, or (more likely) of a
358 user-derived type.
359
360 If the topic is @b STDIO, the application may wish to refuse the
361 connection. Under UNIX, when a server is created the OnAcceptConnection()
362 message is always sent for standard input and output, but in the context
363 of DDE messages it doesn't make a lot of sense.
364 */
365 virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
366 };
367