Developer API

Penfriend W3 and Penfriend XP support communication with third party products for adding prediction to their operation, displaying words and generating keystrokes within that application. To see it in action, please download PredClient. This is only relevant to developers who can read and write C programs.

The design principle, which works across Win16 and Win32, uses Windows Messages and Global Atom strings to pass messages between applications. A standard message number and atom handle is defined, and then for each communication, the atom string is set to contain data and a message sent to indicate that it is ready. Details are included in the PredClient package which is free to download.

PredClient for Penfriend.msi (about 0.3Mb, for Win32).

There is a message sequence to establish communication between the two programs. Then, two tell Penfriend that another letter has been typed, you send it a message. It will send you a new list of predicted words to display. Each time a choice is made, you tell Penfriend so it can update its records. The list of predicted words can be requested at any time, too.

The list of predicted words will come as several messages because of the size limitations on Global Atom strings. Each group starts and ends with a special marker message, and in the middle there will be zero or more messages containing lists of words. Each word is given twice; as the word to display on screen to the user, and the letters which need to be typed in order to achieve that (possibly including backspaces).

INGREDIENTS

Penfriend server application, ie Penfriend for Windows v0.98 or higher A Penfriend client application which the user sees, and talks to the server Windows 3.1, Windows 95, or whatever that supports GlobalAtoms Two fresh GlobalAtoms with which to communicate strings. These are rare!

PREPARATION

The message number from RegisterWindowMessage("PenfriendShare") When the client starts, it should broadcast PFC_FINDSERVER (see below) Similarly, the server may broadcast PFS_FINDCLIENT.

To load Penfriend if it doesn't reply to PFC_FINDSERVER, execute the command in the registry key HKEY_CLASSES_ROOT\Lexicon_PF\Config\Server then try once more.

METHOD

This example is written in C.

MyAtom=GlobalAddAtom("w=666 n=\"Penfriend Client\" v=\"1.01\")
PostMessage(HWND_BROADCAST,PenfriendShareMessage,MyAtom,PFC_FINDSERVER);

Where each process also listens for such messages to process. (lParam: LSB-byte=command, byte1=sequence number, bytes2,3=reserved)

SERVING SUGGESTION

Clicker 3 for Windows 95 could display predictions in a grid window The Windows message used for all of this comes from RegisterWindowMessage() with the string held in PFS_MESSAGENAME

#define PFS_MESSAGENAME "PenfriendShare"

The command numbers and meanings are as follows. Those beginning PFC_ are sent by the client (you), and those beginning PFS_ are sent by the server (Penfriend).

Name Number Meaning
PFC_FINDSERVER 1 Request by client application for any running copy of Penfriend. Reply will contain window handle of server
PFC_CLIENTHERE 2 Reply to PFS_FINDCLIENT
PFC_START 3 Request prediction messages from server
PFC_STOP 4 Request server to stop transmission. window handle may change at client's choice
PFC_RESETSERVER 5 Requests server to start again, forgetting state.
PFC_CLIENTRESET 6 Informs server that client state has reset
PFC_EXITSERVER 7 Instructs server to quit
PFC_CLIENTEXIT 8 Informs server that client is dying. Server may quit if it was started by the client.
PFC_PREDREQ 0x10 Do not use.
PFC_SPELLREQ 0x11 Do not use.
PFC_KEYSTROKE 0x12 Informs server of keys being pressed
PFC_CHOICE 0x13 Informs server of choice from list. Penfriend's lexicon will be updated.
PFC_COMMAND 0x14 Instructs server to execute a menu-command, possibly displaying a dialogue box or taking other action. The command number is the same as in Penfriend's resources.
PFC_ACTION 0x15 Instructs server to execute internal command

PFS_FINDCLIENT 0x41 inform: broadcast seeking partner for good times, GSOH
PFS_SERVERHERE 0x42 reply to PFC_FINDSERVER
PFS_SERVERBUSY 0x43 instruct: server cannot receive instructions
PFS_SERVERREADY 0x44 instruct: server can receive instructions
PFS_SERVERRESET 0x45 inform: server has reset itself spontaneously
PFS_SERVEREXIT 0x46 instruct: ending conversation
PFS_SERVERERROR 0x47 inform: server cannot comply due to fault
PFS_STARTPREDS 0x51 inform: beginning of a new list of predictions. This is the business! Even if there are no words on the list, there will still be PFS_STARTPREDS and PFS_ENDPREDS.
PFS_STARTSPELLS 0x52 Do not use.
PFS_PREDICTIONS 0x53 inform: more entries from list of predictions
PFS_SPELLINGS 0x54 Do not use.
PFS_ENDPREDS 0x55 inform: end of prediction list
PFS_ENDSPELLS 0x56 Do not use.

For PostMessage(), the following parameters are passed:
hWnd = HWND_BROADCAST if partner is unknown, otherwise handle as given earlier
message = result of RegisterWindowMessage(PFS_MESSAGENAME)
wParam = (UINT)atom containing more detailed text string, from GlobalAddAtom
lParam = 3 parts:
Least Significant Byte of lParam = command, eg PFC_FINDSERVER
2nd byte of lParam = sequence number for PFS_PREDICTIONS etc: list pos of first item
top two bytes = reserved for future dodgy handles. must be 0.

Detail strings
GlobalAtom strings must be <= 256 bytes long, and probably need to be plain text.
Most messages will pass all information in one go, but some will take several iterations, and so use the sequence number in lParam.

PFC_FINDSERVER is broadcast to all windows by the client. The string contains:
w=%d n="%s" v=%d
w=%d means the window handle of the client program's window to send replies to.
n="%s" means a text string naming the client, in quotes.
v=%d means a string representing the PenfriendShare protocol version of the client
These parameters are separated by spaces.

PFC_KEYSTROKE is sent by the client when it knows that keys have been pressed.
k=( %d %d %d %d ) ... means the ASCII codes of the characters, separated by spaces and enclosed in brackets. Use decimal.

PFS_PREDICTIONS is sent by the server when it has new data to display. It may send more than one of this message, but will compress them if space allows "%s","%s" "%s","%s" "%s","%s" ... means pairs of display-type strings The display part should appear on screen. The 'type' part should be simulated as keystrokes if chosen. If the type part begins '(' instead of '"' then it is a sequence of decimal ASCII codes

PFC_COMMAND
c=%d w=%d
where c=%d means command number from menu resource of Penfriend and w=%d means the window to be treated as the parent, if any

The remaining commands should be obvious.