X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/15b6757b26a0277472a4f6b071b52050abd922da..1d156af3247c862e51a7c62f569a3fd302052a42:/docs/doxygen/overviews/ipc.h diff --git a/docs/doxygen/overviews/ipc.h b/docs/doxygen/overviews/ipc.h index 2fd2a44fe1..3948cc5319 100644 --- a/docs/doxygen/overviews/ipc.h +++ b/docs/doxygen/overviews/ipc.h @@ -1,224 +1,219 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: ipc +// Name: ipc.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// -/*! - - @page ipc_overview Interprocess communication overview - - Classes: #wxServer, - #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: - - - #wxSocketEvent, - #wxSocketBase, - #wxSocketClient, - #wxSocketServer: classes for the low-level TCP/IP API. - #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. - 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: - - - wxClient. This represents the client application, and is used - only within a client program. - 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. - - - 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. - @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: - - - 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. - Derive a class from wxServer, overriding OnAcceptConnection - to accept or reject a connection on the basis of the topic - argument. This member must create and return an instance of the - derived connection class if the connection is accepted. - Create an instance of your server object and call Create to - activate it, giving it a service name. - - - To create a working client, the programmer must: - - - 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. - Derive a class from wxClient, overriding OnMakeConnection to - create and return an instance of the derived connection class. - Create an instance of your client object. - 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. - 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 - deallocated by the application). - @b Poke: The client sends a data string associated with an item - string directly to the server. This succeeds or fails. - @b Advise: The client asks to be advised of any change in data - 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. - - - 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 - - See the sample programs @e server and @e client in the IPC - samples directory. Run the server, then the client. This demonstrates - using the Execute, Request, and Poke commands from the client, together - with an Advise loop: selecting an item in the server list box causes - that item to be highlighted in the client list box. - - @section ddedetails More DDE details - - A wxClient object initiates the client part of a client-server - 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 - class MyConnection: public wxConnection { - public: - MyConnection(void)::wxConnection() {} - ~MyConnection(void) { } - bool OnAdvise(const wxString& topic, const wxString& item, char *data, int size, wxIPCFormat format) - { wxMessageBox(topic, data); } - }; - - class MyClient: public wxClient { - public: - 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"); - return @NULL; - } - connection-StartAdvise("Item"); - @endcode - - */ - - +/** + +@page overview_ipc Interprocess Communication + +Classes: wxServer, wxConnection, wxClient + +@li @ref overview_ipc_datatransfer +@li @ref overview_ipc_examples +@li @ref overview_ipc_dde + + +
+ + +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: + +@li wxSocketEvent, wxSocketBase, wxSocketClient, wxSocketServer - Classes for + the low-level TCP/IP API. +@li 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. + +Notice that by including @c @ you may define convenient synonyms for +the IPC classes: wxServer for either wxDDEServer or wxTCPServer depending on +whether DDE-based or socket-based implementation is used and the same thing for +wxClient and 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 wxWidgets, 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: + +@li wxClient - This represents the client application, and is used only within + a client program. +@li wxServer - This represents the server application, and is used only within + a server program. +@li 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. + +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. + +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: + +@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. +@li Derive a class from wxServer, overriding OnAcceptConnection to accept or + reject a connection on the basis of the topic argument. This member must + create and return an instance of the derived connection class if the + connection is accepted. +@li Create an instance of your server object and call Create to activate it, + 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. + + +@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. + +@li 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. +@li 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 + deallocated by the application). +@li Poke: The client sends a data string associated with an item string + directly to the server. This succeeds or fails. +@li Advise: The client asks to be advised of any change in data + 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. + +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 overview_ipc_examples Examples + +See the sample programs @e server and @e client in the IPC samples directory. +Run the server, then the client. This demonstrates using the Execute, Request, +and Poke commands from the client, together with an Advise loop: selecting an +item in the server list box causes that item to be highlighted in the client +list box. + + +@section overview_ipc_dde More DDE Details + +A wxClient object initiates the client part of a client-server 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 +class MyConnection: public wxConnection +{ +public: + MyConnection(void)::wxConnection() { } + ~MyConnection(void) { } + + bool OnAdvise(const wxString& topic, const wxString& item, char *data, + int size, wxIPCFormat format) + { + wxMessageBox(topic, data); + } +}; + +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 + +*/ +