home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 4 / AUCD4.iso / acorn / documents / api / freeway < prev   
Encoding:
Text File  |  1996-12-12  |  12.1 KB  |  308 lines
  1. The Acorn Freeway Module
  2. ------------------------
  3. Freeway is a narrow software layer which maintains information about the
  4. location of objects on a network, in a decentralised fashion.
  5.  
  6. Objects are classified according to Freeway Type. At the Freeway level the
  7. attributes of an object are its name, location, an optional descriptor and
  8. an optional authentication value. All other characteristics are undefined.
  9.  
  10. Freeway itself only knows about the IP location of objects on the network.
  11. It is not concerned with how those objects may be accessed, or with any
  12. specific access control mechanisms. These areas are handled by higher-level
  13. type-specific application software, as needed. Each type will have a
  14. 'controlling' application.
  15.  
  16. Freeway types are created by Acorn as required : third parties may request a
  17. type via the usual defined channel for allocation requests. Each type has a
  18. unique identifier : for example, if there is a need for software to enable
  19. 'Bach partitas' to be shared across a network, then an available Freeway
  20. type number will be allocated by Acorn - e.g. 97=BachPartitas - and then the
  21. controlling application will be written to 'share' Bach partitas - whatever
  22. that means.
  23.  
  24. Identifiers
  25. -----------
  26. Type number
  27. -----------
  28. This is a 16-bit integer identifying a Freeway type.  The following type
  29. numbers are allocated to Acorn Access+.  (Informal names with no
  30. significance in software will also be allocated, for easier human reference)
  31.  
  32.         1 = Discs
  33.         2 = Printers
  34.         5 = Hosts
  35.  
  36. In Acorn Access, ShareFS is the controlling application for types Discs and
  37. Hosts, and !Printers is the controlling application for type Printers.
  38.  
  39. Object name
  40. -----------
  41. This is the name of an object.
  42.  
  43. An object name is unique within the set of objects of the same type within a
  44. site. Object names are terminated by a control character (and will return a
  45. terminator of zero on output), case independent, alphanumeric strings,
  46. created by users or application software. Maximum length is 64 bytes,
  47. including the terminator.
  48.  
  49. Object descriptor
  50. -----------------
  51. This provides extra information about the object.
  52.  
  53. Its format is undefined at this level - it has significance to higher-level
  54. application software. Object descriptors are arrays of bytes of any value,
  55. maximum length 255.
  56.  
  57. In Acorn Access+ the descriptor for type Discs indicates whether a disc is
  58. shared protected or unprotected, or as a CDROM or subdirectory, and visible
  59. or invisible to other desktop users.
  60.  
  61. The descriptor for type Printers is a 'Printer Type' string.
  62.  
  63. The descriptor for type Hosts is null.
  64.  
  65. Object authentication value
  66. ---------------------------
  67. Objects are either authenticated or unauthenticated.  Authenticated objects
  68. require an authentication value to be provided before their attributes are
  69. made visible.  An authentication value is a 32 bit integer. The
  70. authentication value of zero is reserved and should not be used.
  71.  
  72. Refresh interval
  73. ----------------
  74. The Freeway software in each computer will periodically re-notify other
  75. computers about unauthenticated objects which are held by the local machine,
  76. so that they know that the objects continue to be accessible. This permits,
  77. for example,  other machines to know when a computer holding Freeway objects
  78. has been powered down. The  renotification period is called the "refresh
  79. interval", and is determined by the Freeway software and is typically 30
  80. seconds.
  81.  
  82.  
  83. Freeway SWIs
  84. ------------
  85. Unless noted otherwise, no Freeway SWIs are reentrant, nor is their effect
  86. on the interrupt status defined.
  87.  
  88. Freeway_Register (SWI &47a80)
  89. Register or deregister interest in objects of a given Freeway type.
  90.  
  91. On entry:
  92. R0 =    flags:  bit     meaning
  93.                 0       0 - register interest
  94.                         1 - deregister interest
  95.                 1       0 - interested in unauthenticated objects
  96.                         1 - interested in authenticated objects
  97.                 2       0 - R3 not valid
  98.                         1 - R3 => type 'name' (<=15 characters, 0
  99.                         terminated)
  100.                 3-31    reserved - must be set to 0
  101. R1 =    type number
  102. R2 =    authentication value if R0 bit 1 is set, otherwise undefined
  103. R3 =    pointer to type 'name' if R0 bit 2 is set, otherwise undefined
  104.  
  105. On exit:
  106. All registers preserved
  107.  
  108. This SWI enables a controlling application to register interest in
  109. authenticated or unauthenticated objects of a particular Freeway type with
  110. the local Freeway software, and also to give a 'name' to that type (this
  111. name is of no significance to the software, it's just for the convenience of
  112. the human user). Freeway will hold information arriving from the network
  113. about a remote object only if one or more registrations of interest have
  114. been made locally in that object's type.  If the object is authenticated
  115. then at least one of those registrations must have included an
  116. authentication value which matches the object's own. An  error is returned
  117. if insufficient free memory exists.
  118.  
  119. Freeway_Write (SWI &47a81)
  120. Add or remove an object of a given type.
  121.  
  122. On entry:
  123. R0 =    flags:  bit     meaning
  124.                 0       0 - add object
  125.                         1 - remove object
  126.                 1       1 - object is authenticated
  127.                 2-31    reserved - must be set to 0
  128. R1 =    Freeway type number
  129. R2 =    pointer to object name, 0 terminated
  130. R3 =    length of object descriptor
  131. R4 =    pointer to object descriptor, or 0 for null descriptor or when R0
  132.         bit 0 is set
  133. R5 =    object authentication value if R0 bit 1 is set, otherwise undefined
  134.  
  135. On exit:
  136. All registers preserved
  137.  
  138. This SWI adds or removes a locally held object of a given type. If the
  139. object is unauthenticated then other computers are notified immediately,
  140. otherwise notification is withheld until a remote computer requests it.  An
  141. error is returned if the type number is not known (i.e. if Freeway_Register
  142. has not been called with this type number), or if an object is added and a
  143. remote object of the given name and type already exists, or if an object is
  144. removed and no local object of the given name and type is currently held, or
  145. if no memory exists to store information about the object.
  146.  
  147. If R0 bit 0 is set and the object named is already held as a local object,
  148. the object's descriptor and authentication value are updated if they differ
  149. from those passed to the SWI.
  150.  
  151. N.B.:   Controlling applications should be prepared to receive upcall
  152. UpCall_Freeway, reason code object deleted (see Section 2.5), referring to
  153. any object previously added successfully via SWI Freeway_Write. This is to
  154. cover the possibility of Freeway deciding at any time that the information
  155. held about an object is unreliable and so deciding to remove it
  156. unilaterally, for any reason, e.g. if a remote object is created with the
  157. same name as a local object.
  158.  
  159. Freeway_Read (SWI &47a82)
  160. Read attributes of an object.
  161.  
  162. On entry:
  163. R0 =    flags:  bit      meaning
  164.                 0       1 = authentication value provided
  165.                 1-31    reserved - must be set to 0
  166. R1 =    Freeway type number
  167. R2 =    pointer to object name, 0 terminated
  168. R3 =    length of buffer for object descriptor
  169. R4 =    pointer to buffer for object descriptor, or 0
  170. R5 =    authentication value if present, otherwise undefined
  171.  
  172. On exit:
  173. R0 - R2 preserved
  174. R3 =    length of held object descriptor
  175. R4      preserved
  176. R5 =    IP address of computer which holds the object
  177.  
  178. This SWI reads information about the attributes of an object. The type
  179. number and object name must be provided. The SWI returns the IP address of
  180. the holder, and optionally the descriptor. The length of a held object
  181. descriptor may be read by setting R4=0 on entry. However in this case there
  182. is no guarantee that the object attributes will not have changed, or that
  183. the object will still exist, if the SWI is called again some time later with
  184. the same object name.  An error is returned if the type number is unknown,
  185. or the object name is unknown, or if a supplied authentication value does
  186. not match the object's own authentication value, or if a supplied object
  187. descriptor buffer is too short;  in this case the actual length is returned
  188. in R3.
  189.  
  190. Freeway_Enumerate (SWI &47a83)
  191. Enumerate objects of a given type.
  192.  
  193. On entry:
  194. R0 =    flags:  bit     meaning
  195.                 0       0 = enumerate unauthenticated objects only
  196.                         1 = enumerate authenticated objects only
  197.                 1-31    reserved - must be set to 0
  198. R1 =    Freeway type number
  199. R2 =    length of buffer for object name
  200. R3 =    pointer to buffer for object name, or 0
  201. R4 =    length of buffer for object descriptor
  202. R5 =    pointer to buffer for object descriptor, or 0
  203. R6 =    0 or undefined
  204. R7 =    enumeration reference (0 to start)
  205. R8 =    authentication value if R0 bit 0 is set, otherwise undefined
  206.  
  207. On exit:        
  208. R0 - R1 preserved
  209. R2 =    length of held object name, including 0 terminator
  210. R3      preserved
  211. R4 =    length of held object descriptor
  212. R5      preserved
  213. R6 =    IP address of computer which holds the object
  214. R7 =    next enumeration reference, or -1 to indicate end reached
  215. R8 =    preserved
  216.  
  217. This SWI allows a controlling application to enumerate currently held
  218. authenticated or unauthenticated objects of a given type, obtaining their
  219. names, location IP addresses, and descriptors if present.  If an
  220. authentication value is provided then only those objects whose actual
  221. authentication value matches the supplied value are enumerated. If no
  222. authentication value is supplied then only unauthenticated objects are
  223. enumerated. The length of the held object name or descriptor may be read
  224. without filling in buffers by setting R3=0 or R5=0 respectively, on entry.
  225. However in this case there is no guarantee that the object attributes will
  226. not have changed, or that the object will still exist, if the SWI is called
  227. again some time later with the same enumeration reference.
  228.  
  229. If R7 is returned -1 then there were no further known objects of that type 
  230. - the object name buffer will not have been filled in, and R6 is undefined.
  231.  
  232. An error is returned if the type number is unknown, or if a supplied name or
  233. descriptor buffer is too short. In the latter cases the actual name and
  234. descriptor lengths are returned in R2 and R4.
  235.  
  236. Freeway_Serial
  237. This SWI is for Acorn internal use only.
  238.  
  239. Freeway Service calls
  240. ---------------------
  241. (Note that no Freeway SWIs may be called when these service calls are
  242. received)
  243.  
  244. Service_FreewayStarting (Service Call &95)
  245. Freeway is starting up.
  246.  
  247. On entry:
  248. R1 =    &95     (reason code)
  249. R2 =    flags:  bit     meaning
  250.                 0-31    reserved - must be set to 0
  251.  
  252. On exit:
  253. R1      preserved to pass on (must not be claimed)
  254.  
  255. Service_FreewayTerminating (Service Call &96)
  256. Freeway is terminating.
  257.  
  258. On entry:
  259. R1 =    &96     (reason code)
  260. R2 =    flags:  bit     meaning
  261.                 0-31    reserved - must be set to 0
  262.  
  263. On exit:
  264. R1      preserved to pass on (must not be claimed)
  265.  
  266.  
  267. Freeway UpCall
  268. --------------
  269. UpCall_Freeway (UpCall 12)
  270. Warns that an object has been added or changed, removed (by the holder), or
  271. deleted (by Freeway).
  272.  
  273. On entry:
  274. R0 =    &12     (reason code)
  275. R1 =    Freeway reason code
  276.         0 = object added
  277.         1= object removed
  278.         2 = object attributes have changed
  279.         3 = local object deleted by Freeway
  280. R2 =    object type
  281. R3 =    pointer to object name
  282. R4 =    length of object descriptor
  283. R5 =    pointer to object descriptor
  284. R6 =    IP address of device which holds or held this object.
  285.  
  286. On exit:
  287. Registers preserved
  288.  
  289. This call warns controlling applications that the named object has been
  290. added, removed or changed. It is also issued when Freeway has detected that
  291. the information held about a locally held object is unreliable, (as a result
  292. of possible temporary name duplication, for example) and has removed it
  293. unilaterally.  It is issued on callback, and the contents of the supplied
  294. name and descriptor buffers are guaranteed not to change provided they are
  295. read from within the application's UpCall handler.
  296.  
  297. Freeway CLI command
  298. -------------------
  299. *FWShow
  300. Show currently known unauthenticated objects.
  301.  
  302. Syntax:         *FWShow
  303. Use:            *FWShow         shows the names and holder IP addresses of
  304. all unauthenticated  objects of all types currently known about by this
  305. machine. Local objects are indicated via a leading asterisk.
  306.  
  307.  
  308.