Figure 22-0

Display 22-0

SwatDisplay 22-0

Table 22-0
22PCCom Library

Revision:   

The PCCom library provides a simple way to allow a geode to provide and 
monitor a PCCom connection. If you are familiar with the SDK, you probably 
think of pccom as a tool which allows the target machine to receive 
commands from the host machine. While the target machine runs the pccom 
tool, the host machine can upload and download files and otherwise 
manipulate the target machine.

The PCCom library allows a geode to start up a PCCom thread monitoring a 
serial port for purposes other than debugging. For instance, it allows the 
GEOS machine to receive files sent over a serial line by another machine 
running pcsend or another program using pccom's file transfer protocol. This 
allows file transfers and other pccom operations to go on in the background 
while the user continues to interact with GEOS.

If you're not familiar with the pccom tool, you should probably read the 
pccom section of "Using Tools," Chapter 10 of the Tools Book-perhaps not 
the whole section, but at least enough to understand basic usage.

	22.1	PCCom Library Abilities

Your geode needn't do much to support PCCom. The PCCom library acts as a 
passive pccom machine-it will only accept orders from a remote machine. 

All you need to do to support PCCom is start up a PCCom process, ideally 
freeing it when done. Geodes using the PCCom library have the option of 
receiving notification when pccom would display text.

	22.2	What To Do

PCCOMINIT(), PCCOMEXIT(), PCCOMABORT()

When you are ready to start monitoring a serial port for pccom-style 
communications, call PCCOMINIT(). This routine is an entry point for the 
library, accessible via ProcGetLibraryEntry() as the first entry point in the 
library, and it may also be called as a normal routine. PCCOMINIT() starts up 
a new thread which will monitor the passed serial port. If it cannot make the 
connection, it will return an error.

When you are done with PCCom, call PCCOMEXIT(), invocable as a library 
entry point or as a normal routine, which closes down the monitor thread and 
frees the serial port for other uses. After calling this routine, you must call 
PCCOMINIT() again if you wish to re-establish the pccom connection.

You may call the PCCOMABORT() routine at any time; this routine aborts any 
pccom file transfer that may be in progress, but leaves the PCCom connection 
intact.

	22.3	Staying Informed

The sections above tell you everything you need to let your geode interact 
with pccom. It is possible to do more: your geode can receive notification 
whenever the pccom tool would display some text. The pccom tool displays 
text to show the user what's going on. Text signals the successful or 
unsuccessful completion of certain operations; a spinning baton shows that a 
file transfer is in progress. Your geode can also find out if the machine on the 
other side of the pccom link has quit pccom.

When calling PCCOMINIT(), your geode can specify an object which should 
receive notification when pccom has text to display or senses that the other 
side of the pccom link has quit. If an object is so specified, it will receive 
notification messages at these times. You must also set the 
PCComInitFlags argument to PCCOMINIT() such that the appropriate 
kinds of notification will be sent; there is one flag which asks for display text 
notification and another flag which asks for notification when the other side 
of the pccom connection exits.

Notification will come in the form of MSG_META_NOTIFY or 
MSG_META_NOTIFY_WITH_DATA_BLOCK. There are three possible forms of 
notification:

MSG_META_NOTIFY:GWNT_PCCOM_DISPLAY_CHAR
If the passed notification type is 
GWNT_PCCOM_DISPLAY_CHAR, then the notification's data 
word contains a character that pccom would display.

MSG_META_NOTIFY_WITH_DATA_BLOCK:GWNT_PCCOM_DISPLAY_STRING
If the passed notification type is 
GWNT_PCCOM_DISPLAY_STRING, then the data in the 
notification's data block is a string of characters.

MSG_META_NOTIFY:GWNT_PCCOM_EXIT_PCCOM
If the passed notification type is GWNT_PCCOM_EXIT_PCCOM, 
then the pccom process on the other side of the pccom 
connection has exited; the notification's data word contains a 
PCComReturnType indicating the success the other side had 
in exiting. The other side of the connection signals that it is 
exiting by sending an EX escape code over the pccom 
connection. A data value of PCCRT_NO_ERROR is a sign of a 
successful exit; other return values might signal that the exit 
was the result of an error.
