AUTHOR

    Dietmar Eilert
    Mies-v-d-Rohe-Str.31, 52074 Aachen, Germany
    Phone: +49-(0)179-5987061 German/English
    E-Mail: Dietmar.Eilert@post.rwth-aachen.de
    E-Mail: dietmar_eilert@yahoo.de (alternative address)
    WWW:    http://members.tripod.com/golded
    Mirror: http://members.xoom.com/golded

COPYRIGHT

    All  executables  and  the  library  in  this  package   (remote.library,
    remoteopen, remoteconfig) are freely distributable public domain software
    and may be included with other software. All other  files  (source  code,
    install  script,  documentation,  etc.) are copyrighted by the author and
    may not be included with other software.

INSTALLATION

    Doubleclick at the installer script icon.

DESCRIPTION

    RA is a shared library to open  files  in  remote  applications  (e.g.  a
    browser)  without  knowledge of the executable name, its location on disk
    or its ARexx  port.  Example  usage:  add  a  go-online  button  to  your
    application  and  use  this  library  to run the browser and to show your
    homepage. With less than five lines of code.

    The  package  includes  freely  distributable  library  frontends  (shell
    commands)  for  use  in  installer  scripts  so that software authors can
    directly register their programs as default application  for  appropriate
    application classes.

EXAMPLE

    This example demonstrates how simple usage of this libary is -  it  opens
    the specified url (STRPTR) in a web browser:

    if (RemoteBase = OpenLibrary("remote.library", 37)) {

        int error = RemoteOpen("BROWSER", NULL, url, REMOTE_OPEN_ASYNC);

        CloseLibrary(RemoteBase);
    }

    RA uses a database of application descriptions  to  find  information  on
    applications  stored  on the user's computer. A small default database is
    shipped with this  package.  It  includes  preconfigured  information  on
    common  Amiga  applications. New application descriptions can be added to
    the database with the remoteconfig program (the idea behind  remoteconfig
    is  that  future installation scripts will directly register applications
    with  RA).  The  library  will  use  the  database  to  find  the  listed
    applications  on  the  user's  computer.  This process is called database
    validation. It involves scanning all local drives.  Once  validated,  all
    applications  detected  during  validation  can  be  accessed through the
    library functions on a class basis: programmers won't deal with  specific
    applications  but  with  application  classes like BROWSER or EDITOR. The
    library  will  then  resolve  your  requests  and  internally  select  an
    application (with preference given to running applications).

THE USER FILES

    RA includes two command files for shell usage and for usage in  installer
    scripts  (you  are  encouraged  to  ship these files with your software):
    remoteconfig and remoteopen. Place these files in your "c:" folder if you
    plan to use them often.

    1. bin/remoteopen

    remoteopen is used to run registered applications and to  open  files  in
    registered  applications.  The  command  template (syntax) is: remoteopen
    CLASS/A,FILE/K,APP/K. CLASS/A is the application  class.  FILE/K  is  the
    file  you  would  like  to  open. And APP/K is the name of your preferred
    application for this job (if you  have  any  preference).  The  following
    example will open an URL in the web browser:

         remoteopen BROWSER file="http://www.clearlight.com/~dietmar".

    2. bin/remoteconfig

    remoteconfig is used to validate and to  configure  the  RA  database  of
    applications.   The   command   template   (syntax)  of  remoteconfig  is
    remoteconfig  ADD/K,DEL/K,VALIDATE/S,FOLDER/K,DEEP/S.  ADD/K   adds   the
    specified  configuration string to the database. The configuration string
    must end with an LF code (further format details can be found below;  see
    "database  format").  DEL/K deletes the specified application(s) from the
    database. You may use wildcards to delete multiple applications. Finally,
    VALIDATE/S  starts  the  database  validation process, ie. a disk scan to
    locate applications on your drives. DEEP/S and FOLDER/K may  be  used  to
    refine  the  validation  process:  RA  defaults  to use a smart searching
    strategy to keep the time required for a disk scan as  low  as  possible.
    However,  RA  may  fail  to detect all applications in smart mode. DEEP/S
    will force RA to use slow conventional searching  instead.  The  FOLDER/K
    parameter  can  be  used  to set the starting point for the drive scan to
    further minimize validation time (why waste time on searching all  drives
    if you install your software in "software:" ?). Examples:

        remoteconfig validate

        remoteconfig validate folder="c:"

        remoteconfig add="class=BROWSER name=AWeb exe=aweb *n"

        remoteconfig del="#?aweb#?"

THE LIBRARY

    A description of the  library  interface  for  programmers  who  wish  to
    interface  to  the library directly without using remoteopen/remoteconfig
    can be found in the autodoc file  "developer/library/autodoc/remote.doc".
    The following library functions are available:

        remote.library/RemoteInit
        remote.library/RemoteAdd
        remote.library/RemoteRemove
        remote.library/RemoteOpen
        remote.library/RemoteValidate

DATABASE FORMAT

    The database usually is kept in the file "s:remote.ini" (or optionally in
    the file the environment variable "remote.cfg" is pointing to). It can be
    viewed and modified with any text editor. The  average  user  will  never
    have  to deal with this file while software authors should understand the
    database format so that they can register their own applications  in  the
    database (the remoteconfig command uses the same format). This is how the
    database file might look like on your computer:

    ; remote.library configuration file (wildcards supported in VERSION/K,PORT/K,INSTALLPATH/K)
    CLASS="BROWSER" NAME="IBrowse" VERSION="" INSTALLPATH="#?/ibrowse/" EXE="ibrowse" MINSIZE=100000 STACK=8192 ASSIGN="" PORT="IBROWSE" OPEN="*"%s*"" OPENRX="GOTOURL *"%s*""
    CLASS="BROWSER" NAME="AWeb DEMO" VERSION="#?DEMO#?" INSTALLPATH="#?/aweb#?" EXE="aweb" MINSIZE=100000 STACK=16384 ASSIGN="AWEB:" PORT="" OPEN="*"%s*"" OPENRX=""
    CLASS="BROWSER" NAME="AWeb" VERSION="~(#?DEMO#?)" INSTALLPATH="#?/aweb#?" EXE="aweb" MINSIZE=100000 STACK=16384 ASSIGN="AWEB:" PORT="AWEB.#?" OPEN="*"%s*"" OPENRX="OPEN *"%s*""
    CLASS="BROWSER" NAME="Mindwalker" VERSION="" INSTALLPATH="" EXE="mindwaker" MINSIZE=100000 STACK=32768 ASSIGN="" PORT="MINDWALKER" OPEN="*"%s*"" OPENRX="OPENURL *"%s*""
    CLASS="BROWSER" NAME="Voyager NG" VERSION="" INSTALLPATH="#?/voyager/" EXE="v" MINSIZE=100000 STACK=65536 ASSIGN="" PORT="VOYAGER" OPEN="*"%s*"" OPENRX="OPENURL *"%s*""

    There is exactly one entry (line) for  each  application.  It  lists  the
    application  class,  the  application  name and a few other details which
    will be used by the library to locate and access the applications.  Order
    in  this  file  is  important: RA will scan the database file from top to
    bottom when looking for applications. The syntax you  use  in  this  file
    will  have  to conform with AmigaDOS rules. For example, string arguments
    must be given in quotation marks if they contain spaces. Quotation  marks
    in  strings can be inserted as *". Linefeeds can be inserted as *n. Below
    is a description of all options:

CLASS

    The application class. While you can freely choose any string you like  I
    would suggest that you only use class names from the list below (and that
    you register new names with the RA author to have them included here).

        EDITOR         Editor for ASCII files
        WORDPROCESSOR  Editor for RTF
        HTMLEDITOR     Editor for HTML
        MAILTO         E-Mail sender
        PLAYWAV        Player for WAV
        TCPSTACK       TCP stack
        VIEWGUIDE      Viewer for guides
        VIEWIMAGE      Viewer for images
        SPOOLER        Spooler for ASCII files
        BROWSER        WWW browser

NAME

    A symbolic application name; can be chosen freely.

VERSION

    Version requirement: This pattern is  pattern-matched  with  the  version
    string  found  in files during database validation to improve reliability
    of executable identification

INSTALLPATH

    Path requirement (root directory): This pattern is  pattern-matched  with
    the  path  to  files during database validation to improve reliability of
    executable identification.

EXE

    The executable name.

MINSIZE

    The executable size given here is  used  during  database  validation  to
    improve  validation  reliability: files smaller than MINSIZE are ignored.
    Consider that compression may be used on some systems: the MINSIZE  value
    should  not  exceed  50%  of  the  real  file  size  so  that  compressed
    executables can still be identified.

STACK

    The minimum stack required to run the program.

ASSIGN

    Some applications require that a new assign  to  the  root  directory  is
    created  during  installation. You can specify the assign in the database
    to help RA improve reliability of executable identification.

PORT

    ARexx port name of the application (may contain wildcards).

OPEN

    The argument template for passing a file name to the application when  it
    is started (if RA can't find running applications).

OPENRX

    The argument template for passing a file name to the application's  ARexx
    port (if RA can find running applications).
