--------------------------------------------------------------------------
NthServer - a utility for serving up MIDI and iGesture events to clients.
--------------------------------------------------------------------------

This software is covered by the open-source license shown at the
bottom of this file.

Introduction
------------
This directory contains a server for an XML-based event interface
to MIDI and Fingerworks iGesture pads.  Currently, this can be used
by a plugin to the Onyx open-source video mixing software, which
can be found at http://www.onyx-vj.com

Everything you need to run the server is provided in this directory.
It currently runs only on Windows.


Quick Start
------------
To run the server, just execute "server.bat" in this directory.
Run it in a separate DOS window, and leave it running.

By default, the server will only be listening for iGesture pad events.
If you want to open a MIDI input device, add arguments to server.bat,
like this:

	server midiin:Cooper

This would open any MIDI input whose name contains "Cooper".
The value can be a regular expression, so if you want to
open all MIDI inputs, use midiin:.* .  However, note
that currently there are problems when the server tries to open
inputs that are already opened by other programs, or inputs that
aren't actually connected.  So, try to open only valid MIDI inputs.

File Reading and Writing
------------------------
The server is also capable of allow reading and writing of files.
This is disabled by default, but you can enable it by setting rootdir,
like this:

	server rootdir:c:\whatever\path\you\want

Reading and writing of files will be relative to that directory, and
an effort is made to disallow writing outside of that path, by disallowing
the writing of any file with a normalized path that doesn't contain
the rootdir as a prefix.

Command-line Parameters:
------------------------

Each command-line parameter is a keyword, a ":", and a value.
Here's the complete list.

	midiin:{regular-expression-for-MIDI-Inputs-to-open}

		Any MIDI input matching this regular expression
		will be opened.

	midiout:{regular-expression-for-MIDI-Outputs-to-open}

		Any MIDI output matching this regular expression
		will be opened.

	rootdir:{path-of-root-directory-for-file-IO}

		The path under which file I/O will be allowed.

	midievents:{regular-expression-for-MIDI-Inputs}

		This one allows you to control which MIDI inputs
		cause events to be reported, so that you can
		do forwarding of MIDI (see midiforward) independent
		of the events that the server reports.

	midiforward:{MIDI-Input-expression}>{MIDI-Output-expression}

		This one allows you to forward MIDI inputs to
		MIDI outputs, so that you can have NthServer be
		the only thing that is reading MIDI, and have it
		forward things to particular MIDI outputs.
		Typical use of this is with MIDI Yoke on Windows,
		to route things from NthServer to a soft synth.

	fingerforward:{MIDI-Output-to-forward-finger-events-to}

		This is not generally useful, but it's a hook
		that allows you to send finger events as
		MIDI system exclusives to a particular MIDI port.
		To make use of it, you need an unusually smart
		MIDI processor on the other side.


Utility Scripts
---------------

You can look at server.bat to see the actual arguments to the
program - one of which is the port on which the server listens.
The default is 1383.

To stop the server, execute "shutdown.bat" in another window.
A message will be sent to the server and it will shutdown in a few seconds.
If there are a lot of MIDI inputs open, it can take longer.

To see if the server is running properly, execute "monitor.bat"
in another window.  Then cause some MIDI input or drag your fingers
on the iGesture pad.  You should see XML messages produced by
the monitor.  Press control-C to terminate the monitor.

Bugs
----

If MIDI inputs or outputs are already open by another process,
and NthServer tries to open them, you'll get errors, and you may
also get flakey behaviour.  Try to set the midiin and midiout 
parameters so that you only open exactly what you need.


Any questions, email Tim Thompson - tjt@nosuch.com

/** 
 * Copyright (c) 2007, Tim Thompson
 * All rights reserved.	
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 * 
 * -  Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 
 * -  Redistributions in binary form must reproduce the above copyright notice, 
 *    this list of conditions and the following disclaimer in the documentation 
 *    and/or other materials provided with the distribution.
 * 
 * -  Neither the name of Tim Thompson, nosuch.com, nor the names of
 *    any contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

