home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / program / k / olesupport / OLESuppDoc < prev    next >
Encoding:
Text File  |  1993-12-02  |  6.4 KB  |  180 lines
  1. REM > OLESuppDoc
  2.  
  3.  ---------------------------------------------------------------------------
  4.  
  5.  Aurthor   - Mike
  6.  Purpose   - Watches files during an OLE session
  7.              (OLE = Object Linking and Embedding)
  8.  Version   - 0.14
  9.  Started   - 08/08/93
  10.  Completed - 
  11.  Changes   -
  12.  
  13.  ---------------------------------------------------------------------------
  14.  
  15.  Introduction
  16.  ============
  17.  
  18.   The OLESupport module provides a file watching facility which can be used
  19.   to simulate and OLE session. For details on OLE sessions refer to OLEDoc.
  20.   A client may not find an OLEServer$<UniqueName> variable for its particular
  21.   file type. Applications such as Acorn Draw and Paint which do not support
  22.   OLE will obviously not provide such a system variable. A client may wish to
  23.   still OLE to such applications.
  24.   It can do so by using swis provided by this support module.
  25.  
  26.   Originally if an application wished to use the OLE support module it needed
  27.   to do so explicitly. The following is an explanation of how it used to work
  28.   and still can.
  29.  
  30.        To OLE an application should save its data to disc and broadcast a
  31.        recorded DataOpen message as the file does when a file is run. If this
  32.        message is returned by the wimp, the client should then run the file.
  33.        To put a watch on the file it should start the OLESupport module up with
  34.        a Wimp_StartTask and call OLE_LinkFile. Whenever the file is saved to by
  35.        a server (such as Draw) the client will receive a Message_OLEFileChanged
  36.        as normal with a session number indicating the file which changes.
  37.  
  38.   Right, now all the client needs to do is call a single swi providing the file
  39.   type of the file it wishes to OLE. (See SWI OLE_SimulateSession)
  40.   The OLESupport module will then invent a system variable for the file type
  41.   of the form
  42.  
  43.     OLEServer$Type_XXX -N OLESupport -R /Desktop_OLESupport
  44.  
  45.   The client can then reuse its normal message passing and variable scanning
  46.   code for that file type. The application it will start up is the OLESupport
  47.   module task. When this module recives a Message_OLEOpenSession, it will
  48.   respond as normal with an acknowladgement. It will however also send a
  49.   data open message using information passed in OpenSession to get the 'real'
  50.   but 'none compliant' application to load the data. If this fails it will attempt
  51.   to run the file.
  52.   Having created a link, the module will then keep track of the file through
  53.   up calls and inform the client everytime the real server saves to the file
  54.   with an OLEFileChanged message.
  55.   Clients of this form obviously cannot be expected to behave in a predictable
  56.   mannor. With a data open message being passed to the client, it will now think
  57.   it owns the file and can dispose of it at any time. It is a good idea then not
  58.   to hand on data which you wish to keep. Create a directory in WimpScrap called
  59.   OLEfiles and save the data as a temporary file there.
  60.   (Note, currently Impression will create a <Wimp$ScrapDir>.OLEfiles directory
  61.    and store ImpOLE### numbered files in it)
  62.  
  63.  
  64.  SWI's provided by this module are
  65.  =================================
  66.  
  67.  
  68.  SWI OLE_Version (&47B00)
  69.  ------------------------
  70.  
  71.  On entry -
  72.  On exit  - R0 = Major revision number  = 0
  73.             R1 = Minor revision number  = 13
  74.             R2 = Task handle (0 if task not running)
  75.  Errors   - Always returns VC if swi known
  76.  
  77.  Returns the version number of this module. This is a useful swi for
  78.  checking to see if the module is loaded. If XSWI_OLEVersion returns
  79.  an error then an application should call
  80.  "Wimp_StartTask","<Path$Dir>.OLESupport" to start the link and embed
  81.  manager.
  82.  Calling this when the manager is already running will cause it to be
  83.  reinitialised and loose any linked files.
  84.  The major and minor revision numbers are taken from the modules
  85.  version (0.15 at time of writing)
  86.  
  87.  SWI OLE_LinkFile (&47B01)
  88.  -------------------------
  89.  
  90.  On entry - R0 = ^Object name
  91.           - R1 =  Task handle
  92.           - R2 =  Session number (24bit unsigned)
  93.  On exit  -
  94.  Errors   - VS if an error occured, R0 = ^error block
  95.  
  96.  Adds a file to the 'watch list'. R0 points to an object name, this will
  97.  be passed through OS_GSTrans so sytem variable based paths can be used.
  98.  R1 holds the tasks handle. Whenever a 'watched' file changes, this task
  99.  will be sent a message informing it of the change.
  100.  R2 is the tasks unique session number for this file. It will be
  101.  returned to the task in FileChanged messages
  102.  
  103.  
  104.  SWI OLE_DeLinkFile (&47B02)
  105.  ---------------------------
  106.  
  107.  On entry - R0 = 0 or 1
  108.                = 0 then  R1 = ^Object name
  109.                = 1 then  R1 =  Task handle
  110.                          R2 =  Session number
  111.  On exit  -
  112.  Errors   - VS if an error occured, R0=^error block
  113.  
  114.  Remove the link on the file specified by R1. ie don't continue to watch
  115.  this file. An error is returned if the file described has not previously
  116.  been linked.
  117.  If a task dies before it calls DeLinkFile, all files the task has linked
  118.  will automatically be removed for it.
  119.  
  120.  
  121.  SWI OLE_FileStatus (&47B03)
  122.  ---------------------------
  123.  
  124.  On entry - R0 = 0 or 1
  125.                = 0 then  R1 = ^Object name
  126.                = 1 then  R1 =  Task handle
  127.                          R2 =  Session number
  128.  
  129.  On exit  - VC then R1 = Status
  130.             = 0 then unchanged
  131.             = 1 then file has been altered
  132.             = 2 then file has been deleted
  133.  
  134.  Errors   - VS if an error occured, R0=^error block
  135.  
  136.  Returns the status of a particular linked file.
  137.  
  138.  
  139.  SWI OLE_Invalidate (&47B04)
  140.  ---------------------------
  141.  
  142.  On entry -
  143.  On exit  -
  144.  
  145.  Removes all linked files from OLE's table.
  146.  
  147.  
  148.  
  149.  SWI OLE_SimulateSession (&47B05)
  150.  --------------------------------
  151.  
  152.  On entry - R0 = file type
  153.  On exit  -
  154.  
  155.  This swi will create an OLEServer$ variable for the file type provided.
  156.  It allows normal OLE protocols to be used by a client and simulates
  157.  the actions required from a compliant application.
  158.  It should thus be used only for file types whose editing applications
  159.  are known to be none compliant with the protocols specified in OLESpec.
  160.  ie a client should check that no OLEServer$Type_XXX variable exists
  161.  already before calling this swi.
  162.  
  163.  Applications controling file types such as:
  164.  
  165.   Draw
  166.   Paint
  167.   ArtWork
  168.   PDream
  169.  
  170.  are currently none compliant.
  171.  
  172.  Applications will automatically become compliant as servers by providing
  173.  OLEServer$Type_XXX variables for their particular file types.
  174.  A client will then pick the up necessary variable during the first
  175.  variable scan and thus not call OLE_SimulateSession.
  176.  
  177.  
  178.  
  179.  
  180.