                   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://freshmeat.net/projects/endeavour2

              Copyright (C) 1997-2009 WolfPack Entertainment


	This document describes the Endeavour Mark II Interprocess
	System (Endeavour 2 InterPS) for programmers.


=====
ABOUT

	The Endeavour 2 InterPS system allows other programs to
	communicate with Endeavour 2.

	Such communications include notifying Endeavour 2 about VFS
	object changes (added, modified, removed, etc), drive mounting,
	and many other things that would affect Endeavour's listing
	so that Endeavour 2 displays the most up to date information.

	Programs can also instruct Endeavour 2 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.

	For a full list on what the Endeavour 2 InterPS system can do,
	see section CAPABILITIES.


============
CAPABILITIES

	The Endeavour 2 InterPS system capabilities are organized in
	two major categories:

	1. Notifying Endeavour 2 about something disk-related.

	2. Instructing Endeavour 2 to take an action or perform an
	   operation.


	Notifying capabilities:

	VFS (Virtual File System) object addition, modification,
	and removal (see edv_notify.c).

	Endeavour 2 recycled object addition, modification,
        and removal (see edv_notify.c).

	Endeavour 2 configuration modified (see edv_notify.c)


	Instructing capabilties:

	Map/create a new Endeavour 2 window (see edv_help.c and
	edv_window.c).

	Append a History Event to Endeavour 2's History List (see
	edv_history.c).

	Install or update an Endeavour 2 MIME Type (see
	edv_mime_type_install.c).


	For a list of low-level InterPS modules see section
	INTERNAL MODULES.


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

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

	For each user there may be only one core process of Endeavour 2
	running at any given time. The core process is the first
	process of Endeavour 2 runned by the user. Subsequent
	executions of Endeavour 2 may produce intermediate (non-core)
	processes of Endeavour 2 whos' jobs are only to send InterPS
	command(s) to the core process of Endeavour 2.

	The process ID of the core process of Endeavour 2, when
	running is stored in the destination value of the InterPS
	lock link:

		$HOME/.endeavour2/lock

	The above location maybe changed by the environment variable
	EDVINTERPSLOCK.


	InterPS commands are stored as strings in separate files, one
	file for each InterPS command, in the InterPS directory:

		$HOME/.endeavour2/interps/

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

	When the core Endeavour 2 process receives a SIGUSR1 signal it
	checks for and process any InterPS commands it finds in the
	InterPS directory. The core Endeavour 2 process will then
	delete each InterPS command file after its command has been
	read (but not nessisarly processed).

	For a official complete list of all Endeavour 2 InterPS
	command formats, see section COMMAND FORMATS.

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

	Programs that wish to use the Endeavour 2 InterPS system
	should link to the Endeavour 2 API library:

		/usr/lib/libEndeavour 2.so

	An example to compile and link a program to the Endeavour 2 API
	library would be:

		# cc 1.c `glib-config --cflags --libs` `Endeavour 2-config --cflags --libs`

	Note that the Endeavour 2 API library requires that your
	program also link to GLib (but not GTK or GDK).


	The program's source code must #include the header file:

		/usr/lib/endeavour2/include/endeavour2.h

	An example would be:

		#include <endeavour2.h>


	To learn how to write programs that use the Endeavour 2 API
	Library look at the source files found in:

		$TOPLEVEL/endeavour2/lib/demos/

	And also look at the header files found in:

		/usr/lib/endeavour2/include/


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

	Modules that contain code for the Endeavour 2 program and the
	Endeavour 2 API library to use the Endeavour 2 InterPS system
	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

	You should not use or link to these modules directly when
	you are wruting your own programs, isntead, you should
	use the Endeavour 2 API library.

	Only the Endeavour 2 program and the Endeavour 2 API library
	themselves need to use the functions from the above modules.


===============
COMMAND FORMATS

	This is the official list of all InterPS command formats. All
	command formats are in the form of strings and follow the
	basic format of:

	<command_name> [argument(s)...]

	The <command_name> specifies the command's name. All command
	strings must contain a command name.

	The [argument(s)...] specifies the argument(s) for the
	command in question. Double quotes (") may be used around
	arguments in case they have spaces.


	Display Help - Instructs Endeavour 2 to display help

	help <subject>

	The <subject> specifies a string describing the help topic.
	The default topic is "Contents".


	Append History Event - Instructs Endeavour 2 to append a
	new History Event to its History List.

	append_history <type> <time_start> <time_end> <status>
		<source> <target> <comments>

	The <type> specifies the history type, see declaration
	edv_history_type in edv_types.h.

	The <time_start> specifies the start time in seconds since
	EPOCH. A value of 0 means that the start time is unknown.

	The <time_end> specifies the start time in seconds since
	EPOCH. A value of 0 means that the end time is unknown.

	The <status> specifies the resulting status of the event,
	this value depends on the type of history event. In general
	the following status values are used:

		0	Success.
		-1	General error.
		-2	Invalid value.
		-3	Systems error (out of memory or disk space).
		-4	User aborted.
		-5	User responded with no.
		-6	Multiple calls to the same function while that
			function is still "busy" or infinite recursion.
		-7	Unsupported operation.
		-99	Try again.

	The <source> specifies an arbitary description of the source,
	such as a name or path to an object that is considered the
	"source".

	The <target> specifies an arbitary description of the target,
	such as a name or path to an object that is considered the
	"target".

	The <comments> specifies an arbitary description of the
	operation.


	Create/Map Window - Instructs Endeavour 2 to create or map
	a window.

	new_window <type> [path] [page/other] [geometry]

	The <type> specifies which window to map, see declaration
	edv_window_type in edv_types.h.

	The [path] specifies the path to the object to display when
	the window is created or mapped. Depending on the type of
	window, this argument may refer to a directory, file, or
	other type of object, it may also refer to nothing depending
	on the type of window.

	The [page/other] specifies the page or tab to display when
	the window is created or mapped. Depending on the type of
	window, this may refer to nothing.

	The [geometry] specifies a geometry string in the format of
	WxH+X+Y the WxH or +X+Y may be omitted. Example;
	800x600 would specify a width of 800 and a height of 600,
	+230+100 would specify an X and Y coordinate of 230 and 100
	(respectively) and 800x600+230+100 would specify a width of
	800, a height of 600, and an X and Y coordinate of 230 and 100.




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