home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / b129_1 / OLESpec next >
Text File  |  1993-12-02  |  9KB  |  239 lines
  1. > OLESpec
  2.  
  3.  ---------------------------------------------------------------------------
  4.  
  5.  Originator - Mike
  6.  Purpose    - Specification of generic 'OLE' interface and mechanisms
  7.  Version    - 1.00
  8.  Started    - 14th August 1993
  9.  Completed  -
  10.  Changes    -
  11.  
  12.  ---------------------------------------------------------------------------
  13.  
  14. Overview
  15. ========
  16.  
  17.  OLE or object linking and embedding allows an application to share
  18. data with a secondary or server application which can edit that
  19. data and return it. This allows compliant applications to gain
  20. features provided by specific graphics or text servers without having
  21. to reimplement those features again.
  22.  This documentation defines the message passing protocols necessary for
  23. this kind of data sharing.
  24.  
  25. Client/Server applications
  26.  
  27.  
  28. The client
  29. ==========
  30.  
  31.  A client application (such as Impression) may wish to edit data it is
  32. capable of loading and rendering (such as drawfiles). There are twp options
  33. open for such an application. Either it can provide facilities to edit these
  34. files itself, or use an already resident editor by sharing the file with it.
  35. It seems sensible and easier to choose the second option, in which case
  36. the client needs to ask a 'compliant' server to engadge in a two way data
  37. sharing session. It does so by the use of a OLEServer$<UniqueName> system
  38. variable which the server provides.
  39.  
  40.  
  41. The server
  42. ==========
  43.  
  44.  Any application which prvides its own file type and is capable of editing
  45. such files may set itself up to be an OLE server. To do so it needs to create
  46. a system variable, outlining the file type it can edit. This should be done
  47. in the applications boot file so it is present for use by a client whenever
  48. the application is seen by the filer.
  49.  
  50.  The syntax of this variable is as follows
  51.  
  52.  Variable name  = OLEServer$Type_XXX
  53.  Variable value = -N <UniqueName> -R <run><Run$Path>
  54.  
  55.  X          = 0..9 | A..F
  56.  AlphaChar  = 0..9 | A..Z | a..z
  57.  UniqueName = [1..16]*<AlphaChar>
  58.  run        = 'run ' or '/'
  59.  
  60.  Spaces must be used as separaters.
  61.  
  62.  a typical example is
  63.  
  64.    OLEServer$Type_AFF -N OLESupport -R /Desktop_OLESupport
  65.  
  66.  
  67.  Tokens
  68.  ------
  69.  
  70. -N : N=Name
  71.  
  72.      This token specifies a unique name to be passed to the server in
  73.      an OpenSession message. This message is broadcast so it is up to
  74.      the server who recognises the name to respond. This string can
  75.      be up to 16 characters long. When passed in messages it should be
  76.      specified as a 16byte string with all unused bytes zero'd.
  77.      ie FNpad("UniqueName",16) or similar. Note the server name should
  78.      be modeled on the application name such as 'OLESupport' used by
  79.      the support module.
  80.  
  81. -R : R=Run
  82.      This token allows a potential client to Wimp_StartTask the server.
  83.      It must provide a run$path string which uniquely locates the
  84.      server. This could be an expanded pathname or more usually
  85.      a system variable. It should be preceded with a run command so the
  86.      whole string can be passed straight to Wimp_StartTask.
  87.      eg 'run <Draw$Dir>'.
  88.         '/<Draw$Dir>' etc
  89.  
  90.  
  91.  
  92. Creating an OLE session
  93. =======================
  94.  
  95.  An OLE session should be opened by an application which cannot itself
  96. edit a particular data format and wishes to share the data with a client
  97. in order to do so.
  98.  
  99. A clients point of view
  100. =======================
  101.  
  102. (1) The client should check to see if an OLEServer$Type_XXX variable
  103.     exists for its file type.
  104.     (If it cannot find such a variable, then the client may wish to
  105.     use the OLESupport module which simulates the response of a client
  106.     for particular file types. See OLESupDoc for information on how to
  107.     use this module task).
  108.  
  109. (2) Having found a server, the client should save its data to disc and
  110.     send a OpenSession message as a broadcast to the server, using the
  111.     unique name specified in the server$type variable. If the server is
  112.     already running it will respond with an acknowledge. If there is no
  113.     acknowledgement then the client should start the server up using the
  114.     -R token and again broadcast the OpenSession message.
  115.     The server will respond to this with a Message_OLEOpenSessionAck to
  116.     inform the client a session is truely open. If again no
  117.     acknowledgement is returned then the client should delete any swap
  118.     files it created and tidy up.
  119.  
  120.     Message_OLEOpenSession (&80E21)
  121.     -------------------------------
  122.  
  123.     On entry - R0 = User message recorded (18)
  124.              - R1 = ^Block
  125.                  +0 = length of block
  126.                  +4 = task handle of sender
  127.                  +8 = my ref
  128.                 +12 = 0
  129.                 +16 = message number
  130.                 +20
  131.                 +24
  132.                 +28
  133.                 +32 = 16 byte unique name padded with zeros
  134.                 +36 = window handle of display holding file
  135.                 +40 = x offset of data in window
  136.                 +44 = y offset of data in window
  137.                 +48 = format number
  138.                  format = 0 or 1 (edit file)
  139.                   +52 = Session number
  140.                   +56 = file type
  141.                   +60 = full pathname of data, zero terminated
  142.                 format = 2 (redit file)
  143.                   +52 = Session number
  144.                 format > 2 (reserved for future expansion)
  145.  
  146.  
  147.     If a client knows it already has a link to a server, it should not
  148.     attempt to send a format 0 open session message. It can send a format
  149.     2 message which will inform a server that the user has tried to perform
  150.     an OLE action on the same data a second time. This gives those
  151.     applications which allow documents to be closed, but not lost from memory
  152.     (eg ArtWorks) a chance to reopen an edit window on the data. Obviously
  153.     it is up to the client to decide what to do here when it receives a
  154.     format 2 message.
  155.     Format 0 messages should be sent initially. If a task is running, which
  156.     recognises the message it will reply correctly. If the client receives the
  157.     same message back (format 0) it should attempt to start the server task up.
  158.     (specified in the OLEServer$ variable). It should then set the format
  159.     to 1 and send the same message off again to the task. If it receives a
  160.     format 1 message back unacknowledged it knows the server has died in some
  161.     way and it should remove the swap file.
  162.  
  163.  
  164.     Message_OLEOpenSessionAck (&80E22)
  165.     ----------------------------------
  166.  
  167.     return same block as OpenSession but copy my_ref to your_ref
  168.  
  169.  
  170. (3) Whenever the server saves data back to file, it should send a changed
  171.     message to the client (using the task handle passed in OLEOpenSession).
  172.     This message format is as follows
  173.  
  174.     Message_OLEFileChanged (&80E1E)
  175.     -------------------------------
  176.  
  177.     On entry - R0 = User message (17)
  178.              - R1 = ^Block
  179.                  +0 = length of block
  180.                  +4 = task handle of sender
  181.                  +8 = my ref
  182.                 +12 = 0
  183.                 +16 = message number
  184.                 +20 = format number
  185.                   format = 0 then
  186.                    +24 = Session number
  187.                    +28 = full pathname of data, zero terminated
  188.                   format = 1 then
  189.                    +24 = Session number 
  190.                          ie pathname still same as that sent by
  191.                          Message_OLEOpenSession
  192.                          (format used by OLESupport)
  193.                   format > 1 then
  194.                    +24... reserved for future extensions
  195.  
  196.     Note, the server should not feel it owns the file and thus should not
  197.     attempt to delete the file during emergencies. If the server corrupts
  198.     the file, the client should be capable of working out that the file
  199.     format has been compromised, when it receives an OLEFileChanged.
  200.  
  201. (4) Whenever the server throws data away, through user action it should
  202.     send a message back to the client informing it that the session has
  203.     been terminated.
  204.  
  205.     Message_OLECloseSession (&80E23)
  206.     --------------------------------
  207.  
  208.     On entry - R0 = User message (17)
  209.              - R1 = ^Block
  210.                  +0 = length of block
  211.                  +4 = task handle of sender
  212.                  +8 = my ref
  213.                 +12 = 0
  214.                 +16 = message number
  215.                 +20 = format number
  216.                   format = 0 then
  217.                     +24 = Session number (-1 means all sessions are closing)
  218.                   format > 0 reserved for future extensions
  219.              - R2 = destin task or 0 for broadcast
  220.  
  221.     Note, the client can send this message to a client or broadcast it to
  222.     all clients when sessions are being closed from the clients end. (ie
  223.     the user is closing the application down or removing one of its
  224.     documents).
  225.  
  226.  
  227. Session numbers & task handles
  228. ==============================
  229.  
  230.  To provide context for OLE sessions a session number and task handle should
  231. be kept by the client and server for each session opened. Session numbers can
  232. be allocated by the client task in a way which makes them unique for the run
  233. time of the program. The client should also keep a copy of the servers task
  234. handle which it will receive via Message_OLEOpenSessionAck. This way it can
  235. tell the server whenever it closes down.
  236.  The same can be said for a server. It needs to communicate file changes and
  237. session closures to a client.
  238.  
  239.