Platform

Win32, x64

Purpose

To send a message to an application that uses %rm.

Syntax

 INTEGER FUNCTION SEND_TEXT_MESSAGE@( CLASS_NAME,
+ MESSAGE, REPLY)
 CHARACTER(*) CLASS_NAME,MESSAGE,REPLY 

Description

This function sends a text string of up to 255 characters to a window with the given class name. The recipient window will normally use the %nc (Class Name) format to give its class a specific name. The recipient will also use the %rm (External Message Handler) format (which takes one call-back argument) to supply a call-back function to handle the message. The call-back function can call CLEARWIN_STRING@('MESSAGE_TEXT') to obtain the message. To send a reply, the call-back function should call REPLY_TO_TEXT_MESSAGE@. Since the message and reply can be up to 255 characters long, they can hold considerable amounts of information.

Notes

a)  Every message requires by its very nature a context switch from the transmitter application to the receiver. Under Win32 this is quite slow therefore large amounts of information are best transmitted in a file, sending just a short message to transmit the file name. Bearing in mind that file accesses are normally cached, this method can be quite efficient.

b)  One use for inter-process communication is particularly common under Win32. It is possible to start several copies of a Win32 application. Often the user does not really want several independent copies of your application running simultaneously. Suppose, for example that a MDI editor MYEDIT is already running and the user issues the command:

MYEDIT filename

What is probably required is to open the file in the editor that is already running. To achieve this it is first necessary to uniquely identify the main window of your application. This is done using the %nc (Class Name) format to give the window a distinctive class name. The window should also use the %rm (External Message Handler) format to supply a routine to handle messages. Before the main window is created the program should call SEND_TEXT_MESSAGE@ to send the name of the file to another copy of the editor if one is running. If this function returns 1 for success the current program can be terminated in the knowledge that the file has been transmitted to another active version of the application.

Return value

Returns 1 for success, otherwise zero if no window with the given class name was found.