| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: ipc.h |
| 3 | // Purpose: topic overview |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows license |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | |
| 11 | @page overview_ipc Interprocess Communication |
| 12 | |
| 13 | Classes: wxServer, wxConnection, wxClient |
| 14 | |
| 15 | @li @ref overview_ipc_datatransfer |
| 16 | @li @ref overview_ipc_examples |
| 17 | @li @ref overview_ipc_dde |
| 18 | |
| 19 | |
| 20 | <hr> |
| 21 | |
| 22 | |
| 23 | wxWidgets has a number of different classes to help with interprocess |
| 24 | communication and network programming. This section only discusses one family |
| 25 | of classes -- the DDE-like protocol -- but here's a list of other useful |
| 26 | classes: |
| 27 | |
| 28 | @li wxSocketEvent, wxSocketBase, wxSocketClient, wxSocketServer - Classes for |
| 29 | the low-level TCP/IP API. |
| 30 | @li wxProtocol, wxURL, wxFTP, wxHTTP - Classes for programming popular |
| 31 | Internet protocols. |
| 32 | |
| 33 | wxWidgets' DDE-like protocol is a high-level protocol based on Windows DDE. |
| 34 | There are two implementations of this DDE-like protocol: one using real DDE |
| 35 | running on Windows only, and another using TCP/IP (sockets) that runs on most |
| 36 | platforms. Since the API and virtually all of the behaviour is the same apart |
| 37 | from the names of the classes, you should find it easy to switch between the |
| 38 | two implementations. |
| 39 | |
| 40 | Notice that by including @c @<wx/ipc.h@> you may define convenient synonyms for |
| 41 | the IPC classes: wxServer for either wxDDEServer or wxTCPServer depending on |
| 42 | whether DDE-based or socket-based implementation is used and the same thing for |
| 43 | wxClient and wxConnection. |
| 44 | |
| 45 | By default, the DDE implementation is used under Windows. DDE works within one |
| 46 | computer only. If you want to use IPC between different workstations you should |
| 47 | define @c wxUSE_DDE_FOR_IPC as 0 before including this header -- this will |
| 48 | force using TCP/IP implementation even under Windows. |
| 49 | |
| 50 | The following description refers to wxWidgets, but remember that the equivalent |
| 51 | wxTCP* and wxDDE* classes can be used in much the same way. |
| 52 | |
| 53 | Three classes are central to the DDE-like API: |
| 54 | |
| 55 | @li wxClient - This represents the client application, and is used only within |
| 56 | a client program. |
| 57 | @li wxServer - This represents the server application, and is used only within |
| 58 | a server program. |
| 59 | @li wxConnection - This represents the connection from the client to the |
| 60 | server. Both the client and the server use an instance of this class, one |
| 61 | per connection. Most DDE transactions operate on this object. |
| 62 | |
| 63 | Messages between applications are usually identified by three variables: |
| 64 | connection object, topic name and item name. A data string is a fourth element |
| 65 | of some messages. To create a connection (a conversation in Windows parlance), |
| 66 | the client application uses wxClient::MakeConnection to send a message to the |
| 67 | server object, with a string service name to identify the server and a topic |
| 68 | name to identify the topic for the duration of the connection. Under Unix, the |
| 69 | service name may be either an integer port identifier in which case an Internet |
| 70 | domain socket will be used for the communications or a valid file name (which |
| 71 | shouldn't exist and will be deleted afterwards) in which case a Unix domain |
| 72 | socket is created. |
| 73 | |
| 74 | <b>SECURITY NOTE:</b> Using Internet domain sockets is extremely insecure for |
| 75 | IPC as there is absolutely no access control for them, use Unix domain sockets |
| 76 | whenever possible! |
| 77 | |
| 78 | The server then responds and either vetoes the connection or allows it. If |
| 79 | allowed, both the server and client objects create wxConnection objects which |
| 80 | persist until the connection is closed. The connection object is then used for |
| 81 | sending and receiving subsequent messages between client and server - |
| 82 | overriding virtual functions in your class derived from wxConnection allows you |
| 83 | to handle the DDE messages. |
| 84 | |
| 85 | To create a working server, the programmer must: |
| 86 | |
| 87 | @li Derive a class from wxConnection, providing handlers for various messages |
| 88 | sent to the server side of a wxConnection (e.g. OnExecute, OnRequest, |
| 89 | OnPoke). Only the handlers actually required by the application need to be |
| 90 | overridden. |
| 91 | @li Derive a class from wxServer, overriding OnAcceptConnection to accept or |
| 92 | reject a connection on the basis of the topic argument. This member must |
| 93 | create and return an instance of the derived connection class if the |
| 94 | connection is accepted. |
| 95 | @li Create an instance of your server object and call Create to activate it, |
| 96 | giving it a service name. |
| 97 | |
| 98 | To create a working client, the programmer must: |
| 99 | |
| 100 | @li Derive a class from wxConnection, providing handlers for various messages |
| 101 | sent to the client side of a wxConnection (e.g. OnAdvise). Only the |
| 102 | handlers actually required by the application need to be overridden. |
| 103 | @li Derive a class from wxClient, overriding OnMakeConnection to create and |
| 104 | return an instance of the derived connection class. |
| 105 | @li Create an instance of your client object. |
| 106 | @li When appropriate, create a new connection using wxClient::MakeConnection, |
| 107 | with arguments host name (processed in Unix only, use 'localhost' for local |
| 108 | computer), service name, and topic name for this connection. The client |
| 109 | object will call OnMakeConnection to create a connection object of the |
| 110 | derived class if the connection is successful. |
| 111 | @li Use the wxConnection member functions to send messages to the server. |
| 112 | |
| 113 | |
| 114 | @section overview_ipc_datatransfer Data Transfer |
| 115 | |
| 116 | These are the ways that data can be transferred from one application to |
| 117 | another. These are methods of wxConnection. |
| 118 | |
| 119 | @li <b>Execute:</b> the client calls the server with a data string representing |
| 120 | a command to be executed. This succeeds or fails, depending on the server's |
| 121 | willingness to answer. If the client wants to find the result of the |
| 122 | Execute command other than success or failure, it has to explicitly call |
| 123 | Request. |
| 124 | @li <b>Request:</b> the client asks the server for a particular data string |
| 125 | associated with a given item string. If the server is unwilling to reply, |
| 126 | the return value is @NULL. Otherwise, the return value is a string |
| 127 | (actually a pointer to the connection buffer, so it should not be |
| 128 | deallocated by the application). |
| 129 | @li <b>Poke:</b> The client sends a data string associated with an item string |
| 130 | directly to the server. This succeeds or fails. |
| 131 | @li <b>Advise:</b> The client asks to be advised of any change in data |
| 132 | associated with a particular item. If the server agrees, the server will |
| 133 | send an OnAdvise message to the client along with the item and data. |
| 134 | |
| 135 | The default data type is wxCF_TEXT (ASCII text), and the default data size is |
| 136 | the length of the null-terminated string. Windows-specific data types could |
| 137 | also be used on the PC. |
| 138 | |
| 139 | |
| 140 | @section overview_ipc_examples Examples |
| 141 | |
| 142 | See the sample programs @e server and @e client in the IPC samples directory. |
| 143 | Run the server, then the client. This demonstrates using the Execute, Request, |
| 144 | and Poke commands from the client, together with an Advise loop: selecting an |
| 145 | item in the server list box causes that item to be highlighted in the client |
| 146 | list box. |
| 147 | |
| 148 | |
| 149 | @section overview_ipc_dde More DDE Details |
| 150 | |
| 151 | A wxClient object initiates the client part of a client-server DDE-like |
| 152 | (Dynamic Data Exchange) conversation (available in both Windows and Unix). |
| 153 | |
| 154 | To create a client which can communicate with a suitable server, you need to |
| 155 | derive a class from wxConnection and another from wxClient. The custom |
| 156 | wxConnection class will receive communications in a 'conversation' with a |
| 157 | server. and the custom wxServer is required so that a user-overridden |
| 158 | wxClient::OnMakeConnection member can return a wxConnection of the required |
| 159 | class, when a connection is made. |
| 160 | |
| 161 | For example: |
| 162 | |
| 163 | @code |
| 164 | class MyConnection: public wxConnection |
| 165 | { |
| 166 | public: |
| 167 | MyConnection(void)::wxConnection() { } |
| 168 | ~MyConnection(void) { } |
| 169 | |
| 170 | bool OnAdvise(const wxString& topic, const wxString& item, char *data, |
| 171 | int size, wxIPCFormat format) |
| 172 | { |
| 173 | wxMessageBox(topic, data); |
| 174 | } |
| 175 | }; |
| 176 | |
| 177 | class MyClient: public wxClient |
| 178 | { |
| 179 | public: |
| 180 | MyClient(void) { } |
| 181 | |
| 182 | wxConnectionBase* OnMakeConnection(void) |
| 183 | { |
| 184 | return new MyConnection; |
| 185 | } |
| 186 | }; |
| 187 | @endcode |
| 188 | |
| 189 | Here, @e MyConnection will respond to OnAdvise messages sent by the server by |
| 190 | displaying a message box. |
| 191 | |
| 192 | When the client application starts, it must create an instance of the derived |
| 193 | wxClient. In the following, command line arguments are used to pass the host |
| 194 | name (the name of the machine the server is running on) and the server name |
| 195 | (identifying the server process). Calling wxClient::MakeConnection implicitly |
| 196 | creates an instance of @e MyConnection if the request for a connection is |
| 197 | accepted, and the client then requests an @e Advise loop from the server (an |
| 198 | Advise loop is where the server calls the client when data has changed). |
| 199 | |
| 200 | @code |
| 201 | wxString server = "4242"; |
| 202 | wxString hostName; |
| 203 | wxGetHostName(hostName); |
| 204 | |
| 205 | // Create a new client |
| 206 | MyClient *client = new MyClient; |
| 207 | connection = (MyConnection *)client->MakeConnection(hostName, server, "IPC TEST"); |
| 208 | |
| 209 | if (!connection) |
| 210 | { |
| 211 | wxMessageBox("Failed to make connection to server", "Client Demo Error"); |
| 212 | return NULL; |
| 213 | } |
| 214 | |
| 215 | connection->StartAdvise("Item"); |
| 216 | @endcode |
| 217 | |
| 218 | */ |
| 219 | |