                   E N D E A V O U R   M A R K   I I

                 I N T E R P R O C E S S   S Y S T E M

           http://www.battlefieldlinux.com/wolfpack/Endeavour2/

              Copyright (C) 1997-2007 WolfPack Entertainment

                http://www.battlefieldlinux.com/wolfpack/


	This document describes the Endeavour Mark II Interprocess
	System (Endeavour2 InterPS).

=====
ABOUT

	The Endeavour2 InterPS system allows other applications to
	communicate with the Endeavour2 program.

	It allows other programs to notify Endeavour2 about disk object
	changes (added, modified, removed, etc), drive mounting,
	and many other things that would affect Endeavour's listing
	so that Endeavour2 displays the most up to date information.

	Other programs can also instruct Endeavour2 to map new windows,
	such as map a new File Browser or Image Browser. Even map the
	Properties dialog and display the properties for a particular
	object.


============
HOW IT WORKS

	The Endeavour2 InterPS system works by using UNIX signals to
	notify a currently running Endeavour2 process that one or more
	InterPS command(s) is/are awaiting to be processed.

	For each user there may be no more than one process of
	Endeavour2 running at any given time. This one process of
	Endeavour2 is refered to as the core Endeavour2 process. Its
	process ID is stored in the destination value of a link called
	the InterPS lock link which is located in:

		$HOME/.endeavour2/lock

	The above location maybe changed by the environment variable
	EDVINTERPSLOCK.

	The programs that are capable of sending InterPS commands (which
	include subsequent executions of Endeavour2 itself) must use the
	Endeavour2 API Library. This library has functions which create
	an interprocess command file in the user's local Endeavour2 data
	directory then sends the SIGUSR1 signal to the core Endeavour2
	process.

	The InterPS command file is created by the Endeavour2 API
	Library and is placed in the user's local Endeavour2 data 
	directory as a file:

		$HOME/.endeavour2/cmd

	The above location may be changed by the environment variable
	EDVINTERPSCMDFILE.

	The core Endeavour2 process will then receive the SIGUSR1 signal
	and read the InterPS command file, get the commands from the
	file, delete it, and then schedual a gtk_idle call to process
	the commands.

	Each command in the InterPS command file is stored as text with
	each command deliminated by newline ('\n') characters.


=============
HOW TO USE IT

	To make a program use the Endeavour2 InterPS system, just link
	it to the Endeavour2 API library found in:

		/usr/lib/endeavour2.so

	Using the header files found in:

		/usr/lib/endeavour2/include/

	The demos found in the source can be a tutorial source for 
	learning how to use the Endeavour2 API library:

		$TOPLEVEL/endeavour2/lib/demos/


================
INTERNAL MODULES

	Modules that contain code for the Endeavour2 program and the
	Endeavour2 API library to use the Endeavour2 InterPS system
	(not for other programs) are:

		$TOPLEVEL/endeavour2/edv_cb.c
		$TOPLEVEL/endeavour2/edv_cb.h
		$TOPLEVEL/endeavour2/edv_interps.c
		$TOPLEVEL/endeavour2/edv_interps.h
		$TOPLEVEL/endeavour2/edv_interps_op.c
		$TOPLEVEL/endeavour2/edv_interps_op.h

	Other programs do not need to use/link to these modules, instead
	they should use functions from the Endeavour2 API library.

	Only the Endeavour2 program and the Endeavour2 API library
	themselves need the functions from the above modules.


                                                      =================
                                                      ENDEAVOUR MARK II
