@wxheader{dde.h}
A wxDDEConnection object represents the connection between a client and a
- server. It can be created by making a connection using a
- wxDDEClient object, or by the acceptance of a connection by a
- wxDDEServer object. The bulk of a DDE (Dynamic Data Exchange)
- conversation is controlled by
- calling members in a @b wxDDEConnection object or by overriding its
- members.
+ server. It can be created by making a connection using a wxDDEClient
+ object, or by the acceptance of a connection by a wxDDEServer object. The
+ bulk of a DDE (Dynamic Data Exchange) conversation is controlled by calling
+ members in a wxDDEConnection object or by overriding its members.
An application should normally derive a new connection class from
- wxDDEConnection, in order to override the communication event handlers
- to do something interesting.
+ wxDDEConnection, in order to override the communication event handlers to
+ do something interesting.
- This DDE-based implementation is available on Windows only,
- but a platform-independent, socket-based version
- of this API is available using wxTCPConnection.
+ This DDE-based implementation is available on Windows only, but a
+ platform-independent, socket-based version of this API is available using
+ wxTCPConnection.
@library{wxbase}
- @category{FIXME}
+ @category{ipc}
- @see wxDDEClient, wxDDEServer, @ref overview_ipcoverview "Interprocess
- communications overview"
+ @see wxConnectionBase, wxDDEClient, wxDDEServer, @ref overview_ipc
*/
-class wxDDEConnection : public wxObject
+class wxDDEConnection : public wxConnectionBase
{
public:
- //@{
/**
Constructs a connection object. If no user-defined connection object is
to be derived from wxDDEConnection, 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 wxDDEServer::OnAcceptConnection
- and/or wxDDEClient::OnMakeConnection members should be replaced by
- functions which construct the new connection object. If the arguments of
- the wxDDEConnection constructor are void, then a default buffer is
- associated with the connection. Otherwise, the programmer must provide a
- a buffer and size of the buffer for the connection object to use in
- transactions.
+ 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
+ wxDDEServer::OnAcceptConnection() and/or
+ wxDDEClient::OnMakeConnection() members should be replaced by functions
+ which construct the new connection object.
+
+ A default buffer will be associated with this connection.
*/
wxDDEConnection();
+ /**
+ Constructs a connection object. If no user-defined connection object is
+ to be derived from wxDDEConnection, 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
+ wxDDEServer::OnAcceptConnection() and/or
+ wxDDEClient::OnMakeConnection() members should be replaced by functions
+ which construct the new connection object.
+
+ @param buffer
+ Buffer for this connection object to use in transactions.
+ @param size
+ Size of the buffer given.
+ */
wxDDEConnection(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.
+ the data associated with the given item. Causes the client 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. The default behaviour of @b OnDisconnect is to delete the
- connection, but the calling application must explicitly delete its
- side of the connection having called @b Disconnect. Returns @true if
- successful.
+ program; it causes the OnDisconnect() message to be sent to the
+ corresponding connection object in the other program. The default
+ behaviour of OnDisconnect() is to delete the connection, but the
+ calling application must explicitly delete its side of the connection
+ having called Disconnect().
+
+ @return @true if successful.
*/
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 OnExecute() member to be
- called. Returns @true if successful.
+ 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 OnExecute()
+ member to be called.
+
+ @return @true if successful.
*/
bool Execute(const void* data, size_t size,
wxIPCFormat format = wxIPC_PRIVATE);
Message sent to the client application when the server notifies it of a
change in the data associated with the given item.
*/
- virtual bool OnAdvise(const wxString& topic,
- const wxString& item,
- const void* data,
- size_t size,
- wxIPCFormat format);
+ virtual bool OnAdvise(const wxString& topic, const wxString& item,
+ const void* data, size_t size, wxIPCFormat format);
/**
Message sent to the client or server application when the other
this message.
*/
virtual bool OnExecute(const wxString& topic, const void* data,
- size_t size,
- wxIPCFormat format);
+ size_t size, wxIPCFormat format);
/**
Message sent to the server application when the client notifies it to
accept the given data.
*/
virtual bool OnPoke(const wxString& topic, const wxString& item,
- const void* data,
- size_t size,
- wxIPCFormat format);
+ const void* data, size_t size, wxIPCFormat format);
/**
- Message sent to the server application when the client
- calls Request(). The server
- should respond by returning a character string from @b OnRequest,
- or @NULL to indicate no data.
+ Message sent to the server application when the client calls Request().
+ The server should respond by returning a character string from
+ OnRequest(), or @NULL to indicate no data.
*/
virtual const void* OnRequest(const wxString& topic,
- const wxString& item,
- size_t* size,
+ const wxString& item, size_t* size,
wxIPCFormat format);
/**
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
+ 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);
+ 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
+ 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,
- const wxString& item);
+ virtual bool OnStopAdvise(const wxString& topic, const wxString& item);
//@{
/**
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. Returns @true if successful.
+ connection's OnPoke() member to be called.
+
+ @return @true if successful.
*/
bool Poke(const wxString& item, const void* data, size_t size,
wxIPCFormat format = wxIPC_PRIVATE);
//@}
/**
- Called by the client application to request data from the server. Causes
- the server connection's OnRequest() member to be called. Returns a
- character string (actually a pointer to the connection's buffer) if
- successful, @NULL otherwise.
+ Called by the client application to request data from the server.
+ Causes the server connection's OnRequest() member to be called.
+
+ @return A character string (actually a pointer to the connection's
+ buffer) if successful, @NULL otherwise.
*/
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.
+
+ @return @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.
+ stopped. Causes the server connection's OnStopAdvise() member to be
+ called.
+
+ @return @true if the server okays it, @false otherwise.
*/
bool StopAdvise(const wxString& item);
};
A wxDDEClient object represents the client part of a client-server DDE
(Dynamic Data Exchange) conversation.
- To create a client which can communicate with a suitable server,
- you need to derive a class from wxDDEConnection and another from wxDDEClient.
- The custom wxDDEConnection class will intercept communications in
- a 'conversation' with a server, and the custom wxDDEServer is required
- so that a user-overridden wxDDEClient::OnMakeConnection member can return
- a wxDDEConnection of the required class, when a connection is made.
+ To create a client which can communicate with a suitable server, you need
+ to derive a class from wxDDEConnection and another from wxDDEClient. The
+ custom wxDDEConnection class will intercept communications in a
+ "conversation" with a server, and the custom wxDDEServer is required so
+ that a user-overridden OnMakeConnection() member can return a
+ wxDDEConnection of the required class, when a connection is made.
- This DDE-based implementation is
- available on Windows only, but a platform-independent, socket-based version
- of this API is available using wxTCPClient.
+ This DDE-based implementation is available on Windows only, but a
+ platform-independent, socket-based version of this API is available using
+ wxTCPClient.
@library{wxbase}
- @category{FIXME}
+ @category{ipc}
- @see wxDDEServer, wxDDEConnection, @ref overview_ipcoverview "Interprocess
- communications overview"
+ @see wxDDEServer, wxDDEConnection, @ref overview_ipc
*/
class wxDDEClient : public wxObject
{
wxDDEClient();
/**
- Tries to make a connection with a server specified by the host
- (machine name under UNIX, ignored under Windows), service name (must
- contain an integer port number under UNIX), and topic string. If the
- server allows a connection, a wxDDEConnection object will be returned.
- The type of wxDDEConnection returned can be altered by overriding
- the OnMakeConnection() member to return your own
- derived connection object.
+ Tries to make a connection with a server specified by the host (machine
+ name under UNIX, ignored under Windows), service name (must contain an
+ integer port number under UNIX), and topic string. If the server allows
+ a connection, a wxDDEConnection object will be returned.
+
+ The type of wxDDEConnection returned can be altered by overriding the
+ OnMakeConnection() member to return your own derived connection object.
*/
wxConnectionBase* MakeConnection(const wxString& host,
const wxString& service,
/**
The type of wxDDEConnection returned from a MakeConnection() call can
- be altered by deriving the @b OnMakeConnection member to return your
- own derived connection object. By default, a wxDDEConnection
- object is returned.
+ be altered by deriving the OnMakeConnection() member to return your own
+ derived connection object. By default, a wxDDEConnection object is
+ returned.
+
The advantage of deriving your own connection class is that it will
- enable you to intercept messages initiated by the server, such
- as wxDDEConnection::OnAdvise. You may also want to
- store application-specific data in instances of the new class.
+ enable you to intercept messages initiated by the server, such as
+ wxDDEConnection::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);
};
A wxDDEServer object represents the server part of a client-server DDE
(Dynamic Data Exchange) conversation.
- This DDE-based implementation is
- available on Windows only, but a platform-independent, socket-based version
- of this API is available using wxTCPServer.
+ This DDE-based implementation is available on Windows only, but a
+ platform-independent, socket-based version of this API is available using
+ wxTCPServer.
@library{wxbase}
- @category{FIXME}
+ @category{ipc}
- @see wxDDEClient, wxDDEConnection, @ref overview_ipcoverview "IPC overview"
+ @see wxDDEClient, wxDDEConnection, @ref overview_ipc
*/
class wxDDEServer
{
/**
Registers the server using the given service name. Under UNIX, the
string must contain an integer id which is used as an Internet port
- number. @false is returned if the call failed (for example, the port
+ number. @false is returned if the call failed (for example, if the port
number is already in use).
*/
bool Create(const wxString& service);
/**
- When a client calls @b MakeConnection, the server receives the
- message and this member is called. The application should derive a
+ When a client calls wxDDEClient::MakeConnection(), the server receives
+ the message and this member is called. The application should derive a
member to intercept this message and return a connection object of
- either the standard wxDDEConnection type, or of a user-derived type. If the
- topic is "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.
+ either the standard wxDDEConnection type, or of a user-derived type.
+
+ If the @a topic is "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.
*/
virtual wxConnectionBase* OnAcceptConnection(const wxString& topic);
};
projects / wxWidgets.git / blobdiff