Introduction and Overview
Freeway is a narrow software layer which maintains information about the location of objects on a network, in a decentralised fashion.
Objects are classified according to Freeway Type. At the Freeway level the attributes of an object are its name, location, an optional descriptor and an optional authentication value. All other characteristics are undefined.
Freeway itself only knows about the IP location of objects on the network. It is not concerned with how those objects may be accessed, or with any specific access control mechanisms. These areas are handled by higher-level type-specific application software, as needed. Each type will have a 'controlling' application.
Freeway types are created by Acorn as required : third parties may request a type via the usual defined channel for allocation requests. Each type has a unique identifier : for example, if there is a need for software to enable 'Bach partitas' to be shared across a network, then an available Freeway type number will be allocated by Acorn - e.g. 97=BachPartitas - and then the controlling application will be written to 'share' Bach partitas - whatever that means.
Technical Details
Type number
This is a 16-bit integer identifying a Freeway type. The following type numbers are allocated to Acorn Access+. (Informal names with no significance in software will also be allocated, for easier human reference)
| Type | Informal name |
|---|---|
| 1 | Discs |
| 2 | Printers |
| 5 | Hosts |
In Acorn Access, ShareFS is the controlling application for types Discs and Hosts, and !Printers is the controlling application for type Printers.
Object name
This is the name of an object.
An object name is unique within the set of objects of the same type within a site. Object names are terminated by a control character (and will return a terminator of zero on output), case independent, alphanumeric strings, created by users or application software. Maximum length is 64 bytes, including the terminator.
Object descriptor
This provides extra information about the object.
Its format is undefined at this level - it has significance to higher-level application software. Object descriptors are arrays of bytes of any value, maximum length 255.
In Acorn Access+ the descriptor for type Discs indicates whether a disc is shared protected or unprotected, or as a CDROM or subdirectory, and visible or invisible to other desktop users.
The descriptor for type Printers is a 'Printer Type' string.
The descriptor for type Hosts is null.
Object authentication value
Objects are either authenticated or unauthenticated. Authenticated objects require an authentication value to be provided before their attributes are made visible. An authentication value is a 32 bit integer. The authentication value of zero is reserved and should not be used.
Refresh interval
The Freeway software in each computer will periodically re-notify other computers about unauthenticated objects which are held by the local machine, so that they know that the objects continue to be accessible. This permits, for example, other machines to know when a computer holding Freeway objects has been powered down. The renotification period is called the "refresh interval", and is determined by the Freeway software and is typically 30 seconds.
Service calls
| R1 | = | service call number | ||||||
| R2 | = | flags :
| ||||||
| R1 | preserved | |
This service is issued when the Freeway module starts up. You may not call any Freeway SWIs during this service. If you wish to register with the module you should use a transient callback to do so.
| R1 | = | service call number | ||||||
| R2 | = | flags :
| ||||||
| R1 | preserved | |
This service is issued when the Freeway module is killed or shuts down for any other reason. You may not call any Freeway SWIs during this service.
UpCalls
| R0 | = | UpCall number | ||||||||||
| R1 | = | Reason code :
| ||||||||||
| R2 | = | type number | ||||||||||
| R3 | = | pointer to object name, 0 terminated | ||||||||||
| R4 | = | length of object descriptor | ||||||||||
| R5 | = | pointer to object descriptor | ||||||||||
| R6 | = | IP address of device which holds or held this object |
| R0 - R6 | preserved | |
This call warns controlling applications that the named object has been added, removed or changed. It is also issued when Freeway has detected that the information held about a locally held object is unreliable, (as a result of possible temporary name duplication, for example) and has removed it unilaterally. It is issued on callback, and the contents of the supplied name and descriptor buffers are guaranteed not to change provided they are read from within the application's UpCall handler.
SWI calls
| R0 | = | flags :
| |||||||||||||||
| R1 | = | type number | |||||||||||||||
| R2 | = | authentication value if R0 bit 1 is set, otherwise undefined | |||||||||||||||
| R3 | = | pointer to type 'name' if R0 bit 2 is set, otherwise undefined | |||||||||||||||
| R0 - R3 | preserved | |
This SWI enables a controlling application to register interest in authenticated or unauthenticated objects of a particular Freeway type with the local Freeway software, and also to give a 'name' to that type (this name is of no significance to the software, it's just for the convenience of the human user). Freeway will hold information arriving from the network about a remote object only if one or more registrations of interest have been made locally in that object's type. If the object is authenticated then at least one of those registrations must have included an authentication value which matches the object's own. An error is returned if insufficient free memory exists.
| R0 | = | flags :
| ||||||||||||
| R1 | = | type number | ||||||||||||
| R2 | = | pointer to object name, 0 terminated | ||||||||||||
| R3 | = | length of object descriptor | ||||||||||||
| R4 | = | pointer to object descriptor, or 0 for null descriptor, or when R0 bit 0 is set | ||||||||||||
| R5 | = | object authentication value if R0 bit 1 is set, otherwise undefined | ||||||||||||
| R0 - R5 | preserved | |
This SWI adds or removes a locally held object of a given type. If the object is unauthenticated then other computers are notified immediately, otherwise notification is withheld until a remote computer requests it. An error is returned if the type number is not known (i.e. if Freeway_Register has not been called with this type number), or if an object is added and a remote object of the given name and type already exists, or if an object is removed and no local object of the given name and type is currently held, or if no memory exists to store information about the object.
If R0 bit 0 is clear and the object named is already held as a local object, the object's descriptor and authentication value are updated if they differ from those passed to the SWI.
N.B.: Controlling applications should be prepared to receive upcall UpCall_Freeway, reason code object deleted, referring to any object previously added successfully via SWI Freeway_Write. This is to cover the possibility of Freeway deciding at any time that the information held about an object is unreliable and so deciding to remove it unilaterally, for any reason, e.g. if a remote object is created with the same name as a local object.
| R0 | = | flags :
| |||||||||
| R1 | = | type number | |||||||||
| R2 | = | pointer to object name, 0 terminated | |||||||||
| R3 | = | length of buffer for object descriptor | |||||||||
| R4 | = | pointer to buffer for object descriptor, or 0 to read descriptor length | |||||||||
| R5 | = | object authentication value if R0 bit 0 is set, otherwise undefined | |||||||||
| R0 - R2 | preserved | |
| R3 | = | length of held object descriptor |
| R4 | preserved | |
| R5 | = | IP address of computer which holds the object |
This SWI reads information about the attributes of an object. The type number and object name must be provided. The SWI returns the IP address of the holder, and optionally the descriptor. The length of a held object descriptor may be read by setting R4=0 on entry. However in this case there is no guarantee that the object attributes will not have changed, or that the object will still exist, if the SWI is called again some time later with the same object name. An error is returned if the type number is unknown, or the object name is unknown, or if a supplied authentication value does not match the object's own authentication value, or if a supplied object descriptor buffer is too short; in this case the actual length is returned in R3.
| R0 | = | flags :
| |||||||||
| R1 | = | type number | |||||||||
| R2 | = | length of buffer for object name | |||||||||
| R3 | = | pointer to buffer for object name, or 0 to read length of name | |||||||||
| R4 | = | length of buffer for object descriptor | |||||||||
| R5 | = | pointer to buffer for object descriptor, or 0 to read descriptor length | |||||||||
| R6 | undefined | ||||||||||
| R7 | = | enumeration context (0 to start) | |||||||||
| R8 | = | object authentication value if R0 bit 0 is set, otherwise undefined | |||||||||
| R0 | preserved | |
| R1 | preserved | |
| R2 | = | length of held object name, including terminator |
| R3 | preserved | |
| R4 | = | length of held object descriptor |
| R5 | preserved | |
| R6 | = | IP address of computer which holds the object |
| R7 | = | next enumeration context, or -1 if no more |
| R8 | preserved | |
This SWI allows a controlling application to enumerate currently held authenticated or unauthenticated objects of a given type, obtaining their names, location IP addresses, and descriptors if present. If an authentication value is provided then only those objects whose actual authentication value matches the supplied value are enumerated. If no authentication value is supplied then only unauthenticated objects are enumerated. The length of the held object name or descriptor may be read without filling in buffers by setting R3=0 or R5=0 respectively, on entry. However in this case there is no guarantee that the object attributes will not have changed, or that the object will still exist, if the SWI is called again some time later with the same enumeration reference.
If R7 is returned -1 then there were no further known objects of that type - the object name buffer will not have been filled in, and R6 is undefined.
An error is returned if the type number is unknown, or if a supplied name or descriptor buffer is too short. In the latter cases the actual name and descriptor lengths are returned in R2 and R4.
This SWI call is for internal use only. You must not use it in your own code.
This SWI call is for internal use only. You must not use it in your own code.
*Commands
This command is used to show the names and holder IP addresses of all unauthenticated objects of all types currently known about by this machine. Local objects are indicated via a leading asterisk.