REM > OLESuppDoc --------------------------------------------------------------------------- Aurthor - Mike Purpose - Watches files during an OLE session (OLE = Object Linking and Embedding) Version - 0.14 Started - 08/08/93 Completed - Changes - --------------------------------------------------------------------------- Introduction ============ The OLESupport module provides a file watching facility which can be used to simulate and OLE session. For details on OLE sessions refer to OLEDoc. A client may not find an OLEServer$ variable for its particular file type. Applications such as Acorn Draw and Paint which do not support OLE will obviously not provide such a system variable. A client may wish to still OLE to such applications. It can do so by using swis provided by this support module. Originally if an application wished to use the OLE support module it needed to do so explicitly. The following is an explanation of how it used to work and still can. To OLE an application should save its data to disc and broadcast a recorded DataOpen message as the file does when a file is run. If this message is returned by the wimp, the client should then run the file. To put a watch on the file it should start the OLESupport module up with a Wimp_StartTask and call OLE_LinkFile. Whenever the file is saved to by a server (such as Draw) the client will receive a Message_OLEFileChanged as normal with a session number indicating the file which changes. Right, now all the client needs to do is call a single swi providing the file type of the file it wishes to OLE. (See SWI OLE_SimulateSession) The OLESupport module will then invent a system variable for the file type of the form OLEServer$Type_XXX -N OLESupport -R /Desktop_OLESupport The client can then reuse its normal message passing and variable scanning code for that file type. The application it will start up is the OLESupport module task. When this module recives a Message_OLEOpenSession, it will respond as normal with an acknowladgement. It will however also send a data open message using information passed in OpenSession to get the 'real' but 'none compliant' application to load the data. If this fails it will attempt to run the file. Having created a link, the module will then keep track of the file through up calls and inform the client everytime the real server saves to the file with an OLEFileChanged message. Clients of this form obviously cannot be expected to behave in a predictable mannor. With a data open message being passed to the client, it will now think it owns the file and can dispose of it at any time. It is a good idea then not to hand on data which you wish to keep. Create a directory in WimpScrap called OLEfiles and save the data as a temporary file there. (Note, currently Impression will create a .OLEfiles directory and store ImpOLE### numbered files in it) SWI's provided by this module are ================================= SWI OLE_Version (&47B00) ------------------------ On entry - On exit - R0 = Major revision number = 0 R1 = Minor revision number = 13 R2 = Task handle (0 if task not running) Errors - Always returns VC if swi known Returns the version number of this module. This is a useful swi for checking to see if the module is loaded. If XSWI_OLEVersion returns an error then an application should call "Wimp_StartTask",".OLESupport" to start the link and embed manager. Calling this when the manager is already running will cause it to be reinitialised and loose any linked files. The major and minor revision numbers are taken from the modules version (0.15 at time of writing) SWI OLE_LinkFile (&47B01) ------------------------- On entry - R0 = ^Object name - R1 = Task handle - R2 = Session number (24bit unsigned) On exit - Errors - VS if an error occured, R0 = ^error block Adds a file to the 'watch list'. R0 points to an object name, this will be passed through OS_GSTrans so sytem variable based paths can be used. R1 holds the tasks handle. Whenever a 'watched' file changes, this task will be sent a message informing it of the change. R2 is the tasks unique session number for this file. It will be returned to the task in FileChanged messages SWI OLE_DeLinkFile (&47B02) --------------------------- On entry - R0 = 0 or 1 = 0 then R1 = ^Object name = 1 then R1 = Task handle R2 = Session number On exit - Errors - VS if an error occured, R0=^error block Remove the link on the file specified by R1. ie don't continue to watch this file. An error is returned if the file described has not previously been linked. If a task dies before it calls DeLinkFile, all files the task has linked will automatically be removed for it. SWI OLE_FileStatus (&47B03) --------------------------- On entry - R0 = 0 or 1 = 0 then R1 = ^Object name = 1 then R1 = Task handle R2 = Session number On exit - VC then R1 = Status = 0 then unchanged = 1 then file has been altered = 2 then file has been deleted Errors - VS if an error occured, R0=^error block Returns the status of a particular linked file. SWI OLE_Invalidate (&47B04) --------------------------- On entry - On exit - Removes all linked files from OLE's table. SWI OLE_SimulateSession (&47B05) -------------------------------- On entry - R0 = file type On exit - This swi will create an OLEServer$ variable for the file type provided. It allows normal OLE protocols to be used by a client and simulates the actions required from a compliant application. It should thus be used only for file types whose editing applications are known to be none compliant with the protocols specified in OLESpec. ie a client should check that no OLEServer$Type_XXX variable exists already before calling this swi. Applications controling file types such as: Draw Paint ArtWork PDream are currently none compliant. Applications will automatically become compliant as servers by providing OLEServer$Type_XXX variables for their particular file types. A client will then pick the up necessary variable during the first variable scan and thus not call OLE_SimulateSession.