// Purpose: interface of wxConnection
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@class wxConnection
- @wxheader{ipc.h}
-
- A wxConnection object represents the connection between a client
- and a server. It is created by making a connection using a
- wxClient object, or by the acceptance of a
- connection by a wxServer object. The
- bulk of a DDE-like (Dynamic Data Exchange) conversation is
- controlled by calling members in a @b wxConnection object or
- by overriding its members. The actual DDE-based implementation
- using wxDDEConnection is available on Windows only, but a
- platform-independent, socket-based version of this API is
+
+ A wxConnection object represents the connection between a client and a server.
+ It is created by making a connection using a wxClient object, or by the acceptance
+ of a connection by a wxServer object.
+
+ The bulk of a DDE-like (Dynamic Data Exchange) conversation is controlled by
+ calling members in a @b wxConnection object or by overriding its members.
+ The actual DDE-based implementation using wxDDEConnection is available on
+ Windows only, but a platform-independent, socket-based version of this API is
available using wxTCPConnection, which has the same API.
- An application should normally derive a new connection class from
- wxConnection, in order to override the communication event
- handlers to do something interesting.
+ An application should normally derive a new connection class from wxConnection,
+ in order to override the communication event handlers to do something interesting.
@library{wxbase}
- @category{FIXME}
+ @category{ipc}
- @see wxClient, wxServer, @ref overview_ipcoverview "Interprocess communications
- overview"
+ @see wxClient, wxServer, @ref overview_ipc
*/
class wxConnection : public wxObject
{
public:
//@{
/**
- Constructs a connection object. If no user-defined connection
- object is to be derived from wxConnection, then the constructor
- should not be called directly, since the default connection
- object will be provided on requesting (or accepting) a
- connection. However, if the user defines his or her own derived
- connection object, the wxServer::OnAcceptConnection
- and/or wxClient::OnMakeConnection
+ Constructs a connection object.
+
+ If no user-defined connection object is to be derived from wxConnection,
+ then the constructor should not be called directly, since the default connection
+ object will be provided on requesting (or accepting) a connection.
+
+ However, if the user defines his or her own derived connection object,
+ the wxServer::OnAcceptConnection and/or wxClient::OnMakeConnection
members should be replaced by functions which construct the new
connection object.
+
If the arguments of the wxConnection constructor are void then
the wxConnection object manages its own connection buffer,
allocating memory as needed. A programmer-supplied buffer cannot
be increased if necessary, and the program will assert if it is
- not large enough. The programmer-supplied buffer is included
- mainly for backwards compatibility.
+ not large enough.
+
+ The programmer-supplied buffer is included mainly for backwards compatibility.
*/
wxConnection();
wxConnection(void* buffer, size_t size);
/**
Called by the server application to advise the client of a change
in the data associated with the given item. Causes the client
- connection's OnAdvise() member
- to be called. Returns @true if successful.
+ connection's OnAdvise() member to be called.
+
+ @return @true if successful.
*/
bool Advise(const wxString& item, const void* data, size_t size,
wxIPCFormat format = wxIPC_PRIVATE);
/**
Called by the client or server application to disconnect from the
- other program; it causes the OnDisconnect()
- message to be sent to the corresponding connection object in the
- other program. Returns @true if successful or already disconnected.
- The application that calls @b Disconnect must explicitly delete
+ other program; it causes the OnDisconnect() message to be sent to the
+ corresponding connection object in the other program.
+
+ Returns @true if successful or already disconnected.
+ The application that calls Disconnect() must explicitly delete
its side of the connection.
*/
bool Disconnect();
//@{
/**
- Called by the client application to execute a command on the
- server. Can also be used to transfer arbitrary data to the server
- (similar to Poke() in
- that respect). Causes the server connection's OnExec()
+ Called by the client application to execute a command on the server.
+ Can also be used to transfer arbitrary data to the server (similar to
+ Poke() in that respect). Causes the server connection's OnExec()
member to be called. Returns @true if successful.
*/
bool Execute(const void* data, size_t size,
//@}
/**
- Message sent to the client application when the server notifies
- it of a change in the data associated with the given item, using
- Advise().
+ Message sent to the client application when the server notifies it of a
+ change in the data associated with the given item, using Advise().
*/
virtual bool OnAdvise(const wxString& topic,
const wxString& item,
/**
Message sent to the client or server application when the other
- application notifies it to end the connection. The default
- behaviour is to delete the connection object and return @true, so
- applications should generally override @b OnDisconnect
- (finally calling the inherited method as well) so that they know
- the connection object is no longer available.
+ application notifies it to end the connection.
+
+ The default behaviour is to delete the connection object and return @true,
+ so applications should generally override OnDisconnect() (finally calling
+ the inherited method as well) so that they know the connection object is
+ no longer available.
*/
virtual bool OnDisconnect();
/**
Message sent to the server application when the client notifies
it to execute the given data, using Execute().
+
Note that there is no item associated with this message.
*/
virtual bool OnExec(const wxString& topic, const wxString& data);
wxIPCFormat format);
/**
- Message sent to the server application when the client calls
- Request(). The
- server's OnRequest() method
- should respond by returning a character string, or @NULL to
- indicate no data, and setting *size. The character string must of
- course persist after the call returns.
+ Message sent to the server application when the client calls Request().
+ The server's OnRequest() method should respond by returning a character
+ string, or @NULL to indicate no data, and setting *size.
+
+ The character string must of course persist after the call returns.
*/
virtual const void* OnRequest(const wxString& topic,
const wxString& item,
/**
Message sent to the server application by the client, when the client
- wishes to start an 'advise loop' for the given topic and item. The
- server can refuse to participate by returning @false.
+ wishes to start an 'advise loop' for the given topic and item.
+ The server can refuse to participate by returning @false.
*/
virtual bool OnStartAdvise(const wxString& topic,
const wxString& item);
/**
Message sent to the server application by the client, when the client
- wishes to stop an 'advise loop' for the given topic and item. The
- server can refuse to stop the advise loop by returning @false, although
+ wishes to stop an 'advise loop' for the given topic and item.
+ The server can refuse to stop the advise loop by returning @false, although
this doesn't have much meaning in practice.
*/
virtual bool OnStopAdvise(const wxString& topic,
//@{
/**
Called by the client application to poke data into the server.
- Can be used to transfer arbitrary data to the server. Causes the
- server connection's OnPoke() member to
- be called. If size is -1 the size is computed from the string
- length of data.
+ Can be used to transfer arbitrary data to the server.
+ Causes the server connection's OnPoke() member to be called.
+ If size is -1 the size is computed from the string length of data.
+
Returns @true if successful.
*/
bool Poke(const wxString& item, const void* data, size_t size,
/**
Called by the client application to request data from the server.
- Causes the server connection's OnRequest()
- member to be called. Size may be @NULL or a pointer to a variable
- to receive the size of the requested item.
- Returns a character string (actually a pointer to the
- connection's buffer) if successful, @NULL otherwise. This buffer
- does not need to be deleted.
+ Causes the server connection's OnRequest() member to be called.
+ Size may be @NULL or a pointer to a variable to receive the size of the
+ requested item.
+
+ Returns a character string (actually a pointer to the connection's buffer)
+ if successful, @NULL otherwise. This buffer does not need to be deleted.
*/
const void* Request(const wxString& item, size_t* size,
wxIPCFormat format = wxIPC_TEXT);
/**
- Called by the client application to ask if an advise loop can be
- started with the server. Causes the server connection's
- OnStartAdvise()
- member to be called. Returns @true if the server okays it, @false
- otherwise.
+ Called by the client application to ask if an advise loop can be started
+ with the server. Causes the server connection's OnStartAdvise()
+ member to be called.
+ Returns @true if the server okays it, @false otherwise.
*/
bool StartAdvise(const wxString& item);
/**
- Called by the client application to ask if an advise loop can be
- stopped. Causes the server connection's OnStopAdvise()
- member to be called. Returns @true if the server okays it, @false
- otherwise.
+ Called by the client application to ask if an advise loop can be stopped.
+ Causes the server connection's OnStopAdvise() member to be called.
+ Returns @true if the server okays it, @false otherwise.
*/
bool StopAdvise(const wxString& item);
+
+ /**
+ Returns true if the format is one of the text formats.
+
+ The text formats are wxIPC_TEXT, wxIPC_UNICODETEXT and wxIPC_UTF8TEXT.
+ */
+ static bool IsTextFormat(wxIPCFormat format);
+
+ /**
+ Returns the data in any of the text formats as string.
+
+ @param data
+ The raw data pointer as used with any of the other methods of this
+ class.
+ @param size
+ The size of the data buffer pointed to by @a data.
+ @param format
+ The format of the data. It must be a text one, i.e. such that
+ IsTextFormat() returns @true for it.
+ @return
+ The string representation of the data. If the format is not text,
+ an assertion failure is triggered and empty string is returned.
+ */
+ static wxString
+ GetTextFromData(const void *data, size_t size, wxIPCFormat format);
};
/**
@class wxClient
- @wxheader{ipc.h}
A wxClient object represents the client part of a client-server
- DDE-like (Dynamic Data Exchange) conversation. The actual
- DDE-based implementation using wxDDEClient is available on Windows
- only, but a platform-independent, socket-based version of this
- API is available using wxTCPClient, which has the same API.
-
- To create a client which can communicate with a suitable server,
- you need to derive a class from wxConnection and another from
- wxClient. The custom wxConnection class will intercept
- communications in a 'conversation' with a server, and the custom
- wxClient is required so that a user-overridden
- wxClient::OnMakeConnection
- member can return a wxConnection of the required class, when a
- connection is made. Look at the IPC sample and the
- @ref overview_ipcoverview "Interprocess communications overview" for
- an example of how to do this.
+ DDE-like (Dynamic Data Exchange) conversation.
+ The actual DDE-based implementation using wxDDEClient is available on Windows
+ only, but a platform-independent, socket-based version of this API is available
+ using wxTCPClient, which has the same API.
+
+ To create a client which can communicate with a suitable server, you need to
+ derive a class from wxConnection and another from wxClient.
+ The custom wxConnection class will intercept communications in a 'conversation'
+ with a server, and the custom wxClient is required so that a user-overridden
+ wxClient::OnMakeConnection member can return a wxConnection of the required
+ class, when a connection is made.
+
+ Look at the IPC sample and the @ref overview_ipc for an example of how to do this.
@library{wxbase}
- @category{FIXME}
+ @category{ipc}
- @see wxServer, wxConnection, @ref overview_ipcoverview "Interprocess
- communications overview"
+ @see wxServer, wxConnection, @ref overview_ipc
*/
class wxClient : public wxObject
{
/**
Tries to make a connection with a server by host (machine name
under UNIX - use 'localhost' for same machine; ignored when using
- native DDE in Windows), service name and topic string. If the
- server allows a connection, a wxConnection object will be
- returned. The type of wxConnection returned can be altered by
- overriding the
- OnMakeConnection()
- member to return your own derived connection object.
+ native DDE in Windows), service name and topic string.
+
+ If the server allows a connection, a wxConnection object will be returned.
+ The type of wxConnection returned can be altered by overriding the
+ OnMakeConnection() member to return your own derived connection object.
+
Under Unix, the service name may be either an integer port
identifier in which case an Internet domain socket will be used
for the communications, or a valid file name (which shouldn't
exist and will be deleted afterwards) in which case a Unix domain
socket is created.
- @b SECURITY NOTE: Using Internet domain sockets if extremely
- insecure for IPC as there is absolutely no access control for
- them, use Unix domain sockets whenever possible!
+
+ @note Using Internet domain sockets is extremely insecure for IPC as
+ there is absolutely no access control for them, use Unix domain
+ sockets whenever possible!
*/
wxConnectionBase* MakeConnection(const wxString& host,
const wxString& service,
const wxString& topic);
/**
- Called by MakeConnection(), by
- default this simply returns a new wxConnection object. Override
- this method to return a wxConnection descendant customised for the
- application.
- The advantage of deriving your own connection class is that it
- will enable you to intercept messages initiated by the server,
- such as wxConnection::OnAdvise. You
- may also want to store application-specific data in instances of
+ Called by MakeConnection(), by default this simply returns a new wxConnection
+ object. Override this method to return a wxConnection descendant customised
+ for the application.
+
+ The advantage of deriving your own connection class is that it will enable
+ you to intercept messages initiated by the server, such as wxConnection::OnAdvise.
+ You may also want to store application-specific data in instances of
the new class.
*/
wxConnectionBase* OnMakeConnection();
/**
- Returns @true if this is a valid host name, @false otherwise. This always
- returns @true under MS Windows.
+ Returns @true if this is a valid host name, @false otherwise.
+ This always returns @true under MS Windows.
*/
bool ValidHost(const wxString& host);
};
/**
@class wxServer
- @wxheader{ipc.h}
-
- A wxServer object represents the server part of a client-server
- DDE-like (Dynamic Data Exchange) conversation. The actual
- DDE-based implementation using wxDDEServer is available on Windows
- only, but a platform-independent, socket-based version of this
- API is available using wxTCPServer, which has the same API.
-
- To create a server which can communicate with a suitable client,
- you need to derive a class from wxConnection and another from
- wxServer. The custom wxConnection class will intercept
- communications in a 'conversation' with a client, and the custom
- wxServer is required so that a user-overridden wxServer::OnAcceptConnection
- member can return a wxConnection of the required class, when a
- connection is made. Look at the IPC sample and the @ref overview_ipcoverview
- "Interprocess communications overview" for
- an example of how to do this.
+
+ A wxServer object represents the server part of a client-server DDE-like
+ (Dynamic Data Exchange) conversation. The actual DDE-based implementation
+ using wxDDEServer is available on Windows only, but a platform-independent,
+ socket-based version of this API is available using wxTCPServer, which has
+ the same API.
+
+ To create a server which can communicate with a suitable client, you need to
+ derive a class from wxConnection and another from wxServer.
+ The custom wxConnection class will intercept communications in a 'conversation'
+ with a client, and the custom wxServer is required so that a user-overridden
+ wxServer::OnAcceptConnection member can return a wxConnection of the required
+ class, when a connection is made.
+ Look at the IPC sample and the @ref overview_ipc for an example of how to do this.
@library{wxbase}
- @category{FIXME}
+ @category{ipc}
- @see wxClient, wxConnection, IPC, overview()
+ @see wxClient, wxConnection, IPC, @ref overview_ipc
*/
class wxServer
{
wxServer();
/**
- Registers the server using the given service name. Under Unix,
- the service name may be either an integer port identifier in
- which case an Internet domain socket will be used for the
- communications, or a valid file name (which shouldn't exist and
- will be deleted afterwards) in which case a Unix domain socket is
- created. @false is returned if the call failed (for example, the
- port number is already in use).
+ Registers the server using the given service name.
+ Under Unix, the service name may be either an integer port identifier in
+ which case an Internet domain socket will be used for the communications,
+ or a valid file name (which shouldn't exist and will be deleted afterwards)
+ in which case a Unix domain socket is created.
+
+ @false is returned if the call failed (for example, the port number is
+ already in use).
*/
bool Create(const wxString& service);
member to intercept this message and return a connection object of
either the standard wxConnection type, or (more likely) of a
user-derived type.
+
If the topic is @b STDIO, the application may wish to refuse the
- connection. Under UNIX, when a server is created the
- OnAcceptConnection message is always sent for standard input and
- output, but in the context of DDE messages it doesn't make a lot
- of sense.
+ connection. Under UNIX, when a server is created the OnAcceptConnection()
+ message is always sent for standard input and output, but in the context
+ of DDE messages it doesn't make a lot of sense.
*/
virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
};
projects / wxWidgets.git / blobdiff