Interprocess communication overview

wxCLIP function groups: Server, Connection, Client.

wxCOOL classes: wxServer, wxConnection, wxClient.

The following describes how wxCLIPS implements DDE. The following three classes are central.

1. Client. This represents the client application, and is used only within a client program.
2. Server. This represents the server application, and is used only within a server program.
3. Connection. This represents the connection from the current client or server to the other application (server or client), and can be used in both server and client programs. 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 sends the message client-make-connection to the client 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 must contain an integer port identifier.

The server then responds and either vetos the connection or allows it. If allowed, a connection object is created which persists until the connection is closed. The connection object is then used for subsequent messages between client and server.

To create a working server, the programmer must:

1. Create a server object, giving it a service name.
2. Register the callback OnAcceptConnection for accepting or rejecting a connection, on the basis of the topic argument.
3. Create a Connection object.
4. Provide callbacks for various messages that are sent to the server side of a Connection.

To create a working client, the programmer must:

1. Create a client object.
2. Create a connection object using client-make-connection.
3. Provide callbacks for various messages that are sent to the client side of a Connection.
4. Use the Connection functions to send messages to the server.

Data transfer
Connection overview
Examples

Data transfer

These are the ways that data can be transferred from one application to another.

• 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.
• 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).
• Poke: The client sends a data string associated with an item string directly to the server. This succeeds or fails.
• 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.

Connection overview

Interprocess communication overview

A connection object has no creation function, since it is implicitly created when a connection is requested (one object at each side of the connection).

A connection object id is used for initiating DDE commands and requests using functions such as connection-execute, and it also has event handlers associated with it to respond to commands from the other side of the connection.

The callbacks you can define for a connection (using window-add-callback) are as follows.

OnAdvise

Called when an OnAdvise message is received by the client in response to a server-side connection-advise call. The function should take arguments: connection id, OnAdvise, topic string, item name string, data string. The function should return 1 if successful, 0 otherwise. The data string is what the server is passing to the client.

OnExecute

Called when an OnExecute message is received by the server in response to a client-side connection-execute call. The function should take arguments: connection id, OnExecute, topic string, dummy item, data string. The function should return 1 if successful, 0 otherwise.

OnPoke

Called when an OnPoke message is received by the server in response to a client-side connection-poke call. The function should take arguments: connection id, OnPoke, topic string, item name, data string. The function should return 1 if successful, 0 otherwise.

OnRequest

Called when an OnRequest message is received by the server in response to a client-side connection-request call. The function should take arguments: connection id, OnRequest, topic string, item name, data string. The function should return the data being requested, or the empty string if none. otherwise.

OnStartAdvise

Called when an OnStartAdvise message is received by the server in response to a client-side connection-start-advise call. The function should take arguments: connection id, OnStartAdvise, topic string, item name, dummy data. The function should return 1 if successful, 0 otherwise.

OnStopAdvise

Called when an OnStopAdvise message is received by the server in response to a client-side connection-start-advise call. The function should take arguments: connection id, OnStopAdvise, topic string, item name, dummy data. The function should return 1 if successful, 0 otherwise.

Examples

See the sample programs ddeserv.clp, ddeclien.clp in the examples directory. Run the server, then the client (you'll have to copy wxclips.exe to wxclips2.exe to run two copies simulataneously).

The sample ddetest.clp shows a simple example of accessing the Program Manager using DDE (Windows only).

;;; Demo of DDE functions: chatting to PROGMAN
;;;

(defglobal ?*progman-server* = 0)
(defglobal ?*progman-server-name* = "PROGMAN")
(defglobal ?*progman-host-name* = "none")
(defglobal ?*progman-topic-name* = "PROGMAN")
(defglobal ?*progman-client* = 0)
(defglobal ?*progman-connection* = 0)

;;; Convert a multifield list of strings to one string
(deffunction many-strings-to-one ($?strings)
  (bind ?counter 1)
  (bind ?string "")
  (while (<= ?counter (length $?strings)) do
    (bind ?string (str-cat ?string (nth ?counter $?strings)))
    (bind ?counter (+ ?counter 1))
  )
  (return ?string)
)

(deffunction progman-demo ()
 ;; Get a group name from the user
 (bind ?new-group-name (get-text-from-user "New PROGMAN group name"))
 (if (neq ?new-group-name "") then
  ;; Form create group command
  (bind ?command (many-strings-to-one (mv-append "[CreateGroup(" ?new-group-name ")]")))

  ;; Construct a client object
  (bind ?*progman-client* (client-create))

  ;; Construct a connection object
  (bind ?*progman-connection* (client-make-connection
              ?*progman-client* ?*progman-host-name*
              ?*progman-server-name* ?*progman-topic-name*))

  ;; Execute a command to create a group
  (bind ?exe (connection-execute ?*progman-connection* ?command))

  ;; Request a list of groups
  (bind ?req (connection-request ?*progman-connection* "PROGMAN"))
  (format t "%nProgram Manager Groups:%n")
  (format t "%s%n%n" ?req)

  ;; Disconnect
  (connection-disconnect ?*progman-connection*)
 )
)

;;; Automatically called when running application from command line
;;; e.g. wxclips -start -clips ddetest.clp
;;; Also runnable from the Application: Run application.
(deffunction app-on-init ()
  (progman-demo)
)