home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #1 / Amiga Plus CD - 2000 - No. 1.iso / Tools / Text / Edit / GoldED-Demo / Bonus / RA / developer / doc / Manual
Encoding:
Text File  |  1999-12-03  |  9.6 KB  |  216 lines
  1. AUTHOR
  2.  
  3.     Dietmar Eilert
  4.     Mies-v-d-Rohe-Str.31, 52074 Aachen, Germany
  5.     Phone: +49-(0)179-5987061 German/English
  6.     E-Mail: Dietmar.Eilert@post.rwth-aachen.de
  7.     E-Mail: dietmar_eilert@yahoo.de (alternative address)
  8.     WWW:    http://members.tripod.com/golded
  9.     Mirror: http://members.xoom.com/golded
  10.  
  11. COPYRIGHT
  12.  
  13.     All  executables  and  the  library  in  this  package   (remote.library,
  14.     remoteopen, remoteconfig) are freely distributable public domain software
  15.     and may be included with other software. All other  files  (source  code,
  16.     install  script,  documentation,  etc.) are copyrighted by the author and
  17.     may not be included with other software.
  18.  
  19. INSTALLATION
  20.  
  21.     Doubleclick at the installer script icon.
  22.  
  23. DESCRIPTION
  24.  
  25.     RA is a shared library to open  files  in  remote  applications  (e.g.  a
  26.     browser)  without  knowledge of the executable name, its location on disk
  27.     or its ARexx  port.  Example  usage:  add  a  go-online  button  to  your
  28.     application  and  use  this  library  to run the browser and to show your
  29.     homepage. With less than five lines of code.
  30.  
  31.     The  package  includes  freely  distributable  library  frontends  (shell
  32.     commands)  for  use  in  installer  scripts  so that software authors can
  33.     directly register their programs as default application  for  appropriate
  34.     application classes.
  35.  
  36. EXAMPLE
  37.  
  38.     This example demonstrates how simple usage of this libary is -  it  opens
  39.     the specified url (STRPTR) in a web browser:
  40.  
  41.     if (RemoteBase = OpenLibrary("remote.library", 37)) {
  42.  
  43.         int error = RemoteOpen("BROWSER", NULL, url, REMOTE_OPEN_ASYNC);
  44.  
  45.         CloseLibrary(RemoteBase);
  46.     }
  47.  
  48.     RA uses a database of application descriptions  to  find  information  on
  49.     applications  stored  on the user's computer. A small default database is
  50.     shipped with this  package.  It  includes  preconfigured  information  on
  51.     common  Amiga  applications. New application descriptions can be added to
  52.     the database with the remoteconfig program (the idea behind  remoteconfig
  53.     is  that  future installation scripts will directly register applications
  54.     with  RA).  The  library  will  use  the  database  to  find  the  listed
  55.     applications  on  the  user's  computer.  This process is called database
  56.     validation. It involves scanning all local drives.  Once  validated,  all
  57.     applications  detected  during  validation  can  be  accessed through the
  58.     library functions on a class basis: programmers won't deal with  specific
  59.     applications  but  with  application  classes like BROWSER or EDITOR. The
  60.     library  will  then  resolve  your  requests  and  internally  select  an
  61.     application (with preference given to running applications).
  62.  
  63. THE USER FILES
  64.  
  65.     RA includes two command files for shell usage and for usage in  installer
  66.     scripts  (you  are  encouraged  to  ship these files with your software):
  67.     remoteconfig and remoteopen. Place these files in your "c:" folder if you
  68.     plan to use them often.
  69.  
  70.     1. bin/remoteopen
  71.  
  72.     remoteopen is used to run registered applications and to  open  files  in
  73.     registered  applications.  The  command  template (syntax) is: remoteopen
  74.     CLASS/A,FILE/K,APP/K. CLASS/A is the application  class.  FILE/K  is  the
  75.     file  you  would  like  to  open. And APP/K is the name of your preferred
  76.     application for this job (if you  have  any  preference).  The  following
  77.     example will open an URL in the web browser:
  78.  
  79.          remoteopen BROWSER file="http://www.clearlight.com/~dietmar".
  80.  
  81.     2. bin/remoteconfig
  82.  
  83.     remoteconfig is used to validate and to  configure  the  RA  database  of
  84.     applications.   The   command   template   (syntax)  of  remoteconfig  is
  85.     remoteconfig  ADD/K,DEL/K,VALIDATE/S,FOLDER/K,DEEP/S.  ADD/K   adds   the
  86.     specified  configuration string to the database. The configuration string
  87.     must end with an LF code (further format details can be found below;  see
  88.     "database  format").  DEL/K deletes the specified application(s) from the
  89.     database. You may use wildcards to delete multiple applications. Finally,
  90.     VALIDATE/S  starts  the  database  validation process, ie. a disk scan to
  91.     locate applications on your drives. DEEP/S and FOLDER/K may  be  used  to
  92.     refine  the  validation  process:  RA  defaults  to use a smart searching
  93.     strategy to keep the time required for a disk scan as  low  as  possible.
  94.     However,  RA  may  fail  to detect all applications in smart mode. DEEP/S
  95.     will force RA to use slow conventional searching  instead.  The  FOLDER/K
  96.     parameter  can  be  used  to set the starting point for the drive scan to
  97.     further minimize validation time (why waste time on searching all  drives
  98.     if you install your software in "software:" ?). Examples:
  99.  
  100.         remoteconfig validate
  101.  
  102.         remoteconfig validate folder="c:"
  103.  
  104.         remoteconfig add="class=BROWSER name=AWeb exe=aweb *n"
  105.  
  106.         remoteconfig del="#?aweb#?"
  107.  
  108. THE LIBRARY
  109.  
  110.     A description of the  library  interface  for  programmers  who  wish  to
  111.     interface  to  the library directly without using remoteopen/remoteconfig
  112.     can be found in the autodoc file  "developer/library/autodoc/remote.doc".
  113.     The following library functions are available:
  114.  
  115.         remote.library/RemoteInit
  116.         remote.library/RemoteAdd
  117.         remote.library/RemoteRemove
  118.         remote.library/RemoteOpen
  119.         remote.library/RemoteValidate
  120.  
  121. DATABASE FORMAT
  122.  
  123.     The database usually is kept in the file "s:remote.ini" (or optionally in
  124.     the file the environment variable "remote.cfg" is pointing to). It can be
  125.     viewed and modified with any text editor. The  average  user  will  never
  126.     have  to deal with this file while software authors should understand the
  127.     database format so that they can register their own applications  in  the
  128.     database (the remoteconfig command uses the same format). This is how the
  129.     database file might look like on your computer:
  130.  
  131.     ; remote.library configuration file (wildcards supported in VERSION/K,PORT/K,INSTALLPATH/K)
  132.     CLASS="BROWSER" NAME="IBrowse" VERSION="" INSTALLPATH="#?/ibrowse/" EXE="ibrowse" MINSIZE=100000 STACK=8192 ASSIGN="" PORT="IBROWSE" OPEN="*"%s*"" OPENRX="GOTOURL *"%s*""
  133.     CLASS="BROWSER" NAME="AWeb DEMO" VERSION="#?DEMO#?" INSTALLPATH="#?/aweb#?" EXE="aweb" MINSIZE=100000 STACK=16384 ASSIGN="AWEB:" PORT="" OPEN="*"%s*"" OPENRX=""
  134.     CLASS="BROWSER" NAME="AWeb" VERSION="~(#?DEMO#?)" INSTALLPATH="#?/aweb#?" EXE="aweb" MINSIZE=100000 STACK=16384 ASSIGN="AWEB:" PORT="AWEB.#?" OPEN="*"%s*"" OPENRX="OPEN *"%s*""
  135.     CLASS="BROWSER" NAME="Mindwalker" VERSION="" INSTALLPATH="" EXE="mindwaker" MINSIZE=100000 STACK=32768 ASSIGN="" PORT="MINDWALKER" OPEN="*"%s*"" OPENRX="OPENURL *"%s*""
  136.     CLASS="BROWSER" NAME="Voyager NG" VERSION="" INSTALLPATH="#?/voyager/" EXE="v" MINSIZE=100000 STACK=65536 ASSIGN="" PORT="VOYAGER" OPEN="*"%s*"" OPENRX="OPENURL *"%s*""
  137.  
  138.     There is exactly one entry (line) for  each  application.  It  lists  the
  139.     application  class,  the  application  name and a few other details which
  140.     will be used by the library to locate and access the applications.  Order
  141.     in  this  file  is  important: RA will scan the database file from top to
  142.     bottom when looking for applications. The syntax you  use  in  this  file
  143.     will  have  to conform with AmigaDOS rules. For example, string arguments
  144.     must be given in quotation marks if they contain spaces. Quotation  marks
  145.     in  strings can be inserted as *". Linefeeds can be inserted as *n. Below
  146.     is a description of all options:
  147.  
  148. CLASS
  149.  
  150.     The application class. While you can freely choose any string you like  I
  151.     would suggest that you only use class names from the list below (and that
  152.     you register new names with the RA author to have them included here).
  153.  
  154.         EDITOR         Editor for ASCII files
  155.         WORDPROCESSOR  Editor for RTF
  156.         HTMLEDITOR     Editor for HTML
  157.         MAILTO         E-Mail sender
  158.         PLAYWAV        Player for WAV
  159.         TCPSTACK       TCP stack
  160.         VIEWGUIDE      Viewer for guides
  161.         VIEWIMAGE      Viewer for images
  162.         SPOOLER        Spooler for ASCII files
  163.         BROWSER        WWW browser
  164.  
  165. NAME
  166.  
  167.     A symbolic application name; can be chosen freely.
  168.  
  169. VERSION
  170.  
  171.     Version requirement: This pattern is  pattern-matched  with  the  version
  172.     string  found  in files during database validation to improve reliability
  173.     of executable identification
  174.  
  175. INSTALLPATH
  176.  
  177.     Path requirement (root directory): This pattern is  pattern-matched  with
  178.     the  path  to  files during database validation to improve reliability of
  179.     executable identification.
  180.  
  181. EXE
  182.  
  183.     The executable name.
  184.  
  185. MINSIZE
  186.  
  187.     The executable size given here is  used  during  database  validation  to
  188.     improve  validation  reliability: files smaller than MINSIZE are ignored.
  189.     Consider that compression may be used on some systems: the MINSIZE  value
  190.     should  not  exceed  50%  of  the  real  file  size  so  that  compressed
  191.     executables can still be identified.
  192.  
  193. STACK
  194.  
  195.     The minimum stack required to run the program.
  196.  
  197. ASSIGN
  198.  
  199.     Some applications require that a new assign  to  the  root  directory  is
  200.     created  during  installation. You can specify the assign in the database
  201.     to help RA improve reliability of executable identification.
  202.  
  203. PORT
  204.  
  205.     ARexx port name of the application (may contain wildcards).
  206.  
  207. OPEN
  208.  
  209.     The argument template for passing a file name to the application when  it
  210.     is started (if RA can't find running applications).
  211.  
  212. OPENRX
  213.  
  214.     The argument template for passing a file name to the application's  ARexx
  215.     port (if RA can find running applications).
  216.