More doxygen topic overview cleanup.
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52206 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
@@ -1,5 +1,5 @@
|
|||||||
/////////////////////////////////////////////////////////////////////////////
|
/////////////////////////////////////////////////////////////////////////////
|
||||||
// Name: ipc
|
// Name: ipc.h
|
||||||
// Purpose: topic overview
|
// Purpose: topic overview
|
||||||
// Author: wxWidgets team
|
// Author: wxWidgets team
|
||||||
// RCS-ID: $Id$
|
// RCS-ID: $Id$
|
||||||
@@ -8,217 +8,204 @@
|
|||||||
|
|
||||||
/*!
|
/*!
|
||||||
|
|
||||||
@page ipc_overview Interprocess communication overview
|
@page overview_ipc Interprocess Communication Overview
|
||||||
|
|
||||||
Classes: #wxServer,
|
Classes: wxServer, wxConnection, wxClient
|
||||||
#wxConnection,
|
|
||||||
#wxClient
|
|
||||||
wxWidgets has a number of different classes to help with
|
|
||||||
interprocess communication and network programming. This section
|
|
||||||
only discusses one family of classes -- the DDE-like protocol --
|
|
||||||
but here's a list of other useful classes:
|
|
||||||
|
|
||||||
|
wxWidgets has a number of different classes to help with interprocess
|
||||||
|
communication and network programming. This section only discusses one family
|
||||||
|
of classes -- the DDE-like protocol -- but here's a list of other useful
|
||||||
|
classes:
|
||||||
|
|
||||||
#wxSocketEvent,
|
@li wxSocketEvent, wxSocketBase, wxSocketClient, wxSocketServer - Classes for
|
||||||
#wxSocketBase,
|
the low-level TCP/IP API.
|
||||||
#wxSocketClient,
|
@li wxProtocol, wxURL, wxFTP, wxHTTP - Classes for programming popular
|
||||||
#wxSocketServer: classes for the low-level TCP/IP API.
|
Internet protocols.
|
||||||
#wxProtocol, #wxURL, #wxFTP, #wxHTTP: classes
|
|
||||||
for programming popular Internet protocols.
|
|
||||||
|
|
||||||
|
wxWidgets' DDE-like protocol is a high-level protocol based on Windows DDE.
|
||||||
|
There are two implementations of this DDE-like protocol: one using real DDE
|
||||||
|
running on Windows only, and another using TCP/IP (sockets) that runs on most
|
||||||
|
platforms. Since the API and virtually all of the behaviour is the same apart
|
||||||
|
from the names of the classes, you should find it easy to switch between the
|
||||||
|
two implementations.
|
||||||
|
|
||||||
wxWidgets' DDE-like protocol is a high-level protocol based on
|
Notice that by including @c @<wx/ipc.h@> you may define convenient synonyms for
|
||||||
Windows DDE. There are two implementations of this DDE-like
|
the IPC classes: wxServer for either wxDDEServer or wxTCPServer depending on
|
||||||
protocol: one using real DDE running on Windows only, and another
|
whether DDE-based or socket-based implementation is used and the same thing for
|
||||||
using TCP/IP (sockets) that runs on most platforms. Since the API
|
wxClient and wxConnection.
|
||||||
and virtually all of the behaviour is the same apart from the
|
|
||||||
names of the classes, you should find it easy to switch between
|
|
||||||
the two implementations.
|
|
||||||
Notice that by including @c wx/ipc.h you may define
|
|
||||||
convenient synonyms for the IPC classes: @c wxServer for either
|
|
||||||
@c wxDDEServer or @c wxTCPServer depending on whether
|
|
||||||
DDE-based or socket-based implementation is used and the same
|
|
||||||
thing for @c wxClient and @c wxConnection.
|
|
||||||
By default, the DDE implementation is used under Windows. DDE works
|
|
||||||
within one computer only. If you want to use IPC between
|
|
||||||
different workstations you should define @c wxUSE_DDE_FOR_IPC as 0 before including this header -- this
|
|
||||||
will force using TCP/IP implementation even under Windows.
|
|
||||||
The following description refers to wx... but remember that the
|
|
||||||
equivalent wxTCP... and wxDDE... classes can be used in much the
|
|
||||||
same way.
|
|
||||||
Three classes are central to the DDE-like API:
|
|
||||||
|
|
||||||
|
By default, the DDE implementation is used under Windows. DDE works within one
|
||||||
|
computer only. If you want to use IPC between different workstations you should
|
||||||
|
define @c wxUSE_DDE_FOR_IPC as 0 before including this header -- this will
|
||||||
|
force using TCP/IP implementation even under Windows.
|
||||||
|
|
||||||
wxClient. This represents the client application, and is used
|
The following description refers to wxWidgets, but remember that the equivalent
|
||||||
only within a client program.
|
wxTCP* and wxDDE* classes can be used in much the same way.
|
||||||
wxServer. This represents the server application, and is used
|
|
||||||
only within a server program.
|
|
||||||
wxConnection. This represents the connection from the
|
|
||||||
client to the server - both the client and the server use an
|
|
||||||
instance of this class, one per connection. Most DDE transactions
|
|
||||||
operate on this object.
|
|
||||||
|
|
||||||
|
Three classes are central to the DDE-like API:
|
||||||
|
|
||||||
Messages between applications are usually identified by three
|
@li wxClient - This represents the client application, and is used only within
|
||||||
variables: connection object, topic name and item name. A data
|
a client program.
|
||||||
string is a fourth element of some messages. To create a
|
@li wxServer - This represents the server application, and is used only within
|
||||||
connection (a conversation in Windows parlance), the client
|
a server program.
|
||||||
application uses wxClient::MakeConnection to send a message to the
|
@li wxConnection - This represents the connection from the client to the
|
||||||
server object, with a string service name to identify the server
|
server. Both the client and the server use an instance of this class, one
|
||||||
and a topic name to identify the topic for the duration of the
|
per connection. Most DDE transactions operate on this object.
|
||||||
connection. 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 is extremely insecure for
|
|
||||||
IPC as there is absolutely no access control for them, use Unix domain sockets
|
|
||||||
whenever possible!
|
|
||||||
The server then responds and either vetoes the connection or
|
|
||||||
allows it. If allowed, both the server and client objects create
|
|
||||||
wxConnection objects which persist until the connection is
|
|
||||||
closed. The connection object is then used for sending and
|
|
||||||
receiving subsequent messages between client and server -
|
|
||||||
overriding virtual functions in your class derived from
|
|
||||||
wxConnection allows you to handle the DDE messages.
|
|
||||||
To create a working server, the programmer must:
|
|
||||||
|
|
||||||
|
Messages between applications are usually identified by three variables:
|
||||||
|
connection object, topic name and item name. A data string is a fourth element
|
||||||
|
of some messages. To create a connection (a conversation in Windows parlance),
|
||||||
|
the client application uses wxClient::MakeConnection to send a message to the
|
||||||
|
server object, with a string service name to identify the server and a topic
|
||||||
|
name to identify the topic for the duration of the connection. 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.
|
||||||
|
|
||||||
Derive a class from wxConnection, providing handlers for various messages sent to the server
|
<b>SECURITY NOTE:</b> Using Internet domain sockets is extremely insecure for
|
||||||
side of a wxConnection (e.g. OnExecute, OnRequest, OnPoke). Only
|
IPC as there is absolutely no access control for them, use Unix domain sockets
|
||||||
the handlers actually required by the application need to be
|
whenever possible!
|
||||||
|
|
||||||
|
The server then responds and either vetoes the connection or allows it. If
|
||||||
|
allowed, both the server and client objects create wxConnection objects which
|
||||||
|
persist until the connection is closed. The connection object is then used for
|
||||||
|
sending and receiving subsequent messages between client and server -
|
||||||
|
overriding virtual functions in your class derived from wxConnection allows you
|
||||||
|
to handle the DDE messages.
|
||||||
|
|
||||||
|
To create a working server, the programmer must:
|
||||||
|
|
||||||
|
@li Derive a class from wxConnection, providing handlers for various messages
|
||||||
|
sent to the server side of a wxConnection (e.g. OnExecute, OnRequest,
|
||||||
|
OnPoke). Only the handlers actually required by the application need to be
|
||||||
overridden.
|
overridden.
|
||||||
Derive a class from wxServer, overriding OnAcceptConnection
|
@li Derive a class from wxServer, overriding OnAcceptConnection to accept or
|
||||||
to accept or reject a connection on the basis of the topic
|
reject a connection on the basis of the topic argument. This member must
|
||||||
argument. This member must create and return an instance of the
|
create and return an instance of the derived connection class if the
|
||||||
derived connection class if the connection is accepted.
|
connection is accepted.
|
||||||
Create an instance of your server object and call Create to
|
@li Create an instance of your server object and call Create to activate it,
|
||||||
activate it, giving it a service name.
|
giving it a service name.
|
||||||
|
|
||||||
|
To create a working client, the programmer must:
|
||||||
|
|
||||||
|
@li Derive a class from wxConnection, providing handlers for various messages
|
||||||
|
sent to the client side of a wxConnection (e.g. OnAdvise). Only the
|
||||||
|
handlers actually required by the application need to be overridden.
|
||||||
|
@li Derive a class from wxClient, overriding OnMakeConnection to create and
|
||||||
|
return an instance of the derived connection class.
|
||||||
|
@li Create an instance of your client object.
|
||||||
|
@li When appropriate, create a new connection using wxClient::MakeConnection,
|
||||||
|
with arguments host name (processed in Unix only, use 'localhost' for local
|
||||||
|
computer), service name, and topic name for this connection. The client
|
||||||
|
object will call OnMakeConnection to create a connection object of the
|
||||||
|
derived class if the connection is successful.
|
||||||
|
@li Use the wxConnection member functions to send messages to the server.
|
||||||
|
|
||||||
|
|
||||||
To create a working client, the programmer must:
|
@section overview_ipc_datatransfer Data Transfer
|
||||||
|
|
||||||
|
These are the ways that data can be transferred from one application to
|
||||||
|
another. These are methods of wxConnection.
|
||||||
|
|
||||||
Derive a class from wxConnection, providing handlers for various
|
@li <b>Execute:</b> the client calls the server with a data string representing
|
||||||
messages sent to the client side of a wxConnection (e.g.
|
a command to be executed. This succeeds or fails, depending on the server's
|
||||||
OnAdvise). Only the handlers actually required by the application
|
willingness to answer. If the client wants to find the result of the
|
||||||
need to be overridden.
|
Execute command other than success or failure, it has to explicitly call
|
||||||
Derive a class from wxClient, overriding OnMakeConnection to
|
Request.
|
||||||
create and return an instance of the derived connection class.
|
@li <b>Request:</b> the client asks the server for a particular data string
|
||||||
Create an instance of your client object.
|
associated with a given item string. If the server is unwilling to reply,
|
||||||
When appropriate, create a new connection using
|
the return value is @NULL. Otherwise, the return value is a string
|
||||||
wxClient::MakeConnection,
|
|
||||||
with arguments host name (processed in Unix only, use 'localhost'
|
|
||||||
for local computer), service name, and topic name for this
|
|
||||||
connection. The client object will call
|
|
||||||
#OnMakeConnection to create
|
|
||||||
a connection object of the derived class if the connection is
|
|
||||||
successful.
|
|
||||||
Use the wxConnection member functions to send messages to the server.
|
|
||||||
|
|
||||||
|
|
||||||
@ref datatransfer_overview
|
|
||||||
#Examples
|
|
||||||
@ref ddedetails_overview
|
|
||||||
|
|
||||||
|
|
||||||
@section datatransfer Data transfer
|
|
||||||
|
|
||||||
These are the ways that data can be transferred from one
|
|
||||||
application to another. These are methods of wxConnection.
|
|
||||||
|
|
||||||
|
|
||||||
@b Execute: the client calls the server with a data string representing
|
|
||||||
a command to be executed. This succeeds or fails, depending on the
|
|
||||||
server's willingness to answer. If the client wants to find the result
|
|
||||||
of the Execute command other than success or failure, it has to explicitly
|
|
||||||
call Request.
|
|
||||||
@b Request: the client asks the server for a particular data string
|
|
||||||
associated with a given item string. If the server is unwilling to
|
|
||||||
reply, the return value is @NULL. Otherwise, the return value is a string
|
|
||||||
(actually a pointer to the connection buffer, so it should not be
|
(actually a pointer to the connection buffer, so it should not be
|
||||||
deallocated by the application).
|
deallocated by the application).
|
||||||
@b Poke: The client sends a data string associated with an item
|
@li <b>Poke:</b> The client sends a data string associated with an item string
|
||||||
string directly to the server. This succeeds or fails.
|
directly to the server. This succeeds or fails.
|
||||||
@b Advise: The client asks to be advised of any change in data
|
@li <b>Advise:</b> The client asks to be advised of any change in data
|
||||||
associated with a particular item. If the server agrees, the server will
|
associated with a particular item. If the server agrees, the server will
|
||||||
send an OnAdvise message to the client along with the item and data.
|
send an OnAdvise message to the client along with the item and data.
|
||||||
|
|
||||||
|
The default data type is wxCF_TEXT (ASCII text), and the default data size is
|
||||||
|
the length of the null-terminated string. Windows-specific data types could
|
||||||
|
also be used on the PC.
|
||||||
|
|
||||||
The default data type is wxCF_TEXT (ASCII text), and the default data
|
|
||||||
size is the length of the null-terminated string. Windows-specific data
|
|
||||||
types could also be used on the PC.
|
|
||||||
|
|
||||||
@section ipcexamples Examples
|
@section overview_ipc_examples Examples
|
||||||
|
|
||||||
See the sample programs @e server and @e client in the IPC
|
See the sample programs @e server and @e client in the IPC samples directory.
|
||||||
samples directory. Run the server, then the client. This demonstrates
|
Run the server, then the client. This demonstrates using the Execute, Request,
|
||||||
using the Execute, Request, and Poke commands from the client, together
|
and Poke commands from the client, together with an Advise loop: selecting an
|
||||||
with an Advise loop: selecting an item in the server list box causes
|
item in the server list box causes that item to be highlighted in the client
|
||||||
that item to be highlighted in the client list box.
|
list box.
|
||||||
|
|
||||||
@section ddedetails More DDE details
|
|
||||||
|
|
||||||
A wxClient object initiates the client part of a client-server
|
@section overview_ipc_dde More DDE Details
|
||||||
DDE-like (Dynamic Data Exchange) conversation (available in both
|
|
||||||
Windows and Unix).
|
|
||||||
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 receive
|
|
||||||
communications in a 'conversation' with a server. and the custom
|
|
||||||
wxServer is required so that a user-overridden
|
|
||||||
wxClient::OnMakeConnection
|
|
||||||
member can return a wxConnection of the required class, when a
|
|
||||||
connection is made.
|
|
||||||
For example:
|
|
||||||
|
|
||||||
@code
|
A wxClient object initiates the client part of a client-server DDE-like
|
||||||
class MyConnection: public wxConnection {
|
(Dynamic Data Exchange) conversation (available in both Windows and Unix).
|
||||||
public:
|
|
||||||
MyConnection(void)::wxConnection() {}
|
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 receive communications in a 'conversation' with a
|
||||||
|
server. and the custom wxServer is required so that a user-overridden
|
||||||
|
wxClient::OnMakeConnection member can return a wxConnection of the required
|
||||||
|
class, when a connection is made.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
@code
|
||||||
|
class MyConnection: public wxConnection
|
||||||
|
{
|
||||||
|
public:
|
||||||
|
MyConnection(void)::wxConnection() { }
|
||||||
~MyConnection(void) { }
|
~MyConnection(void) { }
|
||||||
bool OnAdvise(const wxString& topic, const wxString& item, char *data, int size, wxIPCFormat format)
|
|
||||||
{ wxMessageBox(topic, data); }
|
|
||||||
};
|
|
||||||
|
|
||||||
class MyClient: public wxClient {
|
bool OnAdvise(const wxString& topic, const wxString& item, char *data,
|
||||||
public:
|
int size, wxIPCFormat format)
|
||||||
MyClient(void) {}
|
|
||||||
wxConnectionBase *OnMakeConnection(void) { return new MyConnection; }
|
|
||||||
};
|
|
||||||
@endcode
|
|
||||||
|
|
||||||
Here, @b MyConnection will respond to
|
|
||||||
#OnAdvise messages sent by the
|
|
||||||
server by displaying a message box.
|
|
||||||
When the client application starts, it must create an instance of
|
|
||||||
the derived wxClient. In the following, command line arguments
|
|
||||||
are used to pass the host name (the name of the machine the
|
|
||||||
server is running on) and the server name (identifying the server
|
|
||||||
process). Calling
|
|
||||||
wxClient::MakeConnection
|
|
||||||
implicitly creates an instance of @b MyConnection if the
|
|
||||||
request for a connection is accepted, and the client then
|
|
||||||
requests an @e Advise loop from the server (an Advise loop is
|
|
||||||
where the server calls the client when data has changed).
|
|
||||||
|
|
||||||
@code
|
|
||||||
wxString server = "4242";
|
|
||||||
wxString hostName;
|
|
||||||
wxGetHostName(hostName);
|
|
||||||
|
|
||||||
// Create a new client
|
|
||||||
MyClient *client = new MyClient;
|
|
||||||
connection = (MyConnection *)client-MakeConnection(hostName, server, "IPC TEST");
|
|
||||||
|
|
||||||
if (!connection)
|
|
||||||
{
|
{
|
||||||
wxMessageBox("Failed to make connection to server", "Client Demo Error");
|
wxMessageBox(topic, data);
|
||||||
return @NULL;
|
|
||||||
}
|
}
|
||||||
connection-StartAdvise("Item");
|
};
|
||||||
@endcode
|
|
||||||
|
|
||||||
*/
|
class MyClient: public wxClient
|
||||||
|
{
|
||||||
|
public:
|
||||||
|
MyClient(void) { }
|
||||||
|
|
||||||
|
wxConnectionBase* OnMakeConnection(void)
|
||||||
|
{
|
||||||
|
return new MyConnection;
|
||||||
|
}
|
||||||
|
};
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
Here, @e MyConnection will respond to OnAdvise messages sent by the server by
|
||||||
|
displaying a message box.
|
||||||
|
|
||||||
|
When the client application starts, it must create an instance of the derived
|
||||||
|
wxClient. In the following, command line arguments are used to pass the host
|
||||||
|
name (the name of the machine the server is running on) and the server name
|
||||||
|
(identifying the server process). Calling wxClient::MakeConnection implicitly
|
||||||
|
creates an instance of @e MyConnection if the request for a connection is
|
||||||
|
accepted, and the client then requests an @e Advise loop from the server (an
|
||||||
|
Advise loop is where the server calls the client when data has changed).
|
||||||
|
|
||||||
|
@code
|
||||||
|
wxString server = "4242";
|
||||||
|
wxString hostName;
|
||||||
|
wxGetHostName(hostName);
|
||||||
|
|
||||||
|
// Create a new client
|
||||||
|
MyClient *client = new MyClient;
|
||||||
|
connection = (MyConnection *)client->MakeConnection(hostName, server, "IPC TEST");
|
||||||
|
|
||||||
|
if (!connection)
|
||||||
|
{
|
||||||
|
wxMessageBox("Failed to make connection to server", "Client Demo Error");
|
||||||
|
return NULL;
|
||||||
|
}
|
||||||
|
|
||||||
|
connection->StartAdvise("Item");
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
*/
|
||||||
|
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
/////////////////////////////////////////////////////////////////////////////
|
/////////////////////////////////////////////////////////////////////////////
|
||||||
// Name: listctrl
|
// Name: listctrl.h
|
||||||
// Purpose: topic overview
|
// Purpose: topic overview
|
||||||
// Author: wxWidgets team
|
// Author: wxWidgets team
|
||||||
// RCS-ID: $Id$
|
// RCS-ID: $Id$
|
||||||
@@ -8,11 +8,11 @@
|
|||||||
|
|
||||||
/*!
|
/*!
|
||||||
|
|
||||||
@page listctrl_overview wxListCtrl overview
|
@page overview_listctrl wxListCtrl Overview
|
||||||
|
|
||||||
Classes: #wxListCtrl, #wxImageList
|
Classes: wxListCtrl, wxImageList
|
||||||
Sorry, this topic has yet to be written.
|
|
||||||
|
|
||||||
*/
|
Sorry, this topic hasn't been written yet.
|
||||||
|
|
||||||
|
*/
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user