Extended Attributes API Specification (Rev #4, changes)
Showing changes from revision #3 to #4:
Added | Removed | Changed
Warning: The current and/or previous revision contained markup errors which prevented proper diff analysis. A guess at markup correction has been made but the diff may not be a truly accurate reflection of the real changes.
<notextile>
ExtdAttrib
Introduction
ExtdAttrib distributes queries and changes on attributes. RISC OS standard file attributes are handled internally.RISC OS standard file attributes are handled
internally.
Each module which wants to provide additional attributes must register itself to this module. If a program requests attributes for a given file ExtdAttrib passes this attributes to the according module. These will fill the required attribute information into a attribute result list if they can. The information can be passed onwards to further modules if required.
If a program requests attributes for a given file ExtdAttrib passes this attributes to the according
module. These will fill the required attribute information into a attribute result list if they can.
The information can be passed onwards to further modules if required.
The space of memory for the attribute result list is provided in general by the calling application. application but can be also allocated by ExtdAttrib inside its own dynamic area. The calling application can determine whether its request shall be fulfilled directly or in a multitasking way if possible. At the latter the caller will obtain a query handle which can be requested again and again until all attributes have been evaluated. The required size of the memory can be determined also. Because in general space of result belongs to the caller which might be swapped out during determining the attributes the values have to be cached locally in the handlers until the module which provides the information is polled again by ExtdAttrib.
The calling application can determine if its request shall be fulfilled directly or in a multitasking
way if possible. At the latter the caller will obtain a query handle which can be required again
and again until all attributes have been evaluated. The required size of the memory can be determined
also. Because space of result belongs to the caller which might be swapped out during determining
the attributes the values have to be cached locally until the module which provides the information
is polled again by ExtdAttrib.
The calling application has also to pass on a list of attributes which it wants to obtain for a given file. Attributes are distinguished by tags. The attributes are obtained in the same order as given in the list which allows the calling program to fetch attributes which can be obtained without delay first and fetch attributes at the end whilst improving the obtained information continuously.
for a given file. Attributes are distinguished by tags. The attributes are obtained in the same
order is given inside the list which allows the calling program to fetch attributes which
can be obtained without delay first and fetch attributes at the end whilst improving the obtained
information continuously.
Attributes may be changeable and so ExtdAttrib provides a SWI with which an application can change changeable attributes of a given file. Even this operation can be performed in a multitasking way if desired.SWI with which an application
can change changeable attributes of a given file. Even this operation can be performed in a
multitasking way if desired.
What can you do with extended attributes?
The module overcomes some limitations of the OS. E.g. there are filing systems inside a multiuser network environment which are providing additional information about users which created or modified the files. The calling application (which is in general the filer) can evaluate this information on demand. Of course it must be prepared that not all attributes are available for all files.
a multiuser network environment which are providing additional information about users
which created or modified the files. The calling application (which is in general the filer)
can evaluate this information on demand. Of course it must be prepared that not all attributes
are available for all files.
Because ExtdAttrib provides handling of arbitrary attributes including sound and graphics it is easy to implement a thumbnail viewer with it. It also may provide graphical overlay information for the regular type icon which might eg. indicate which files are checked out from a file revisioning tool. You can also replace the icons for certain files however. Attributes can be used to filter files or to search for files. It is also possible to change attributes for some files like music files independently of the format.
it is easy to implement a thumbnail viewer with it. It also may provide graphical overlay
information for the regular type icon which might eg. indicate which files are checked out
from a file revisioning tool. You can also replace the icons for certain files however.
Attributes can be used to filter files or to search for files. It is also possible to
change attributes for some files like music files independently of the format.
Note this all this is not provided ExtdAttrib itself but may be provided by additional modules or calling programs.
additional modules or calling programs.
Displaying attributes
ExtdAttrib can be also used to provide Copyright and usage information for programs or certain files like music file which can be played only a limited number of times. Of course handlers and programs must use random numbers as parameters and encrypted results in case that a secure information shall be returned whether a program/file license is valid or not. Even this can be regarded as a file attribute of course there are other ways of implementation and may be better ones for the same task too.
Your application has to enumerate the available attributes first.
According to the reported attribute tags it has to decide whether
to handle an attribute or not. If it wants to handle an attribute it should put it into
a list of required attributes. These list of attributes must be fetched for every file for
which your application wants to report the attributes. This is done by calling the
SWIs ExtdAttrib 0-7. This operation might be performed
in a multitasking way if your application and the according attribute handlers are
performing this. If the result of this query informs your application that an attribute is
writable for the given file your application may provide a possibility to change the
value of the attribute. The change itself should be performed by the application by
calling on of the SWIs ExtdAttrib 16-23.
Using attributes in a client application
Your application has to enumerate the available attributes first by calling SWI ExtdAttrib 9. According to the reported attribute tags it has to decide whether to handle an attribute or not. If it wants to handle an attribute it should put it into a list of required attributes. These list of attributes must be fetched for every file for which your application wants to report the attributes. This is done by calling the SWIs ExtdAttrib 0-7. This operation might be performed in a multitasking way if your application and the according attribute handlers are supporting this. A multitasking query can be aborted by by calling SWI ExtdAttrib 8. You can choose to keep the result inside memory which is maintained by ExtdAttrib itself. In general you should not do so for this makes unnecessary usage of the unprotected public memory area. However if you are deciding to do so you need to tell ExtdAttrib when you are no longer using the result data by calling SWI ExtdAttrib 12. If the result of this query informs your application that an attribute is writable for the given file your application may provide a possibility to change the value of the attribute. The change itself should be performed by the application by calling the SWIs ExtdAttrib 16-23.
When copying, moving or deleting a file the according attribute information has to be kept uptodate. However nature of attributes is different. Some are included inside the file or maintained by the OS and other ones are stored inside a central DB. Some are retrieved only on demand from other kind of data (e.g. small pictures presenting the file content from the file itself). Sometimes it may not be sure that they must be copied e.g. think of files inside the folder of a versioning system. If you are creating a copy this doesn't necessary mean that you want to keep the copied files in the versioning process.
Concept needs to be discussed how to expand ExtdAttrib to allow copying/moving/deletion support.
Attributes
There is a descriptor for each attribute. It contains information about the type of the attribute, which determines how information is stored inside the query results and also provides some flags which tells you how an attribute is handled. Such a
which determines how information is stored inside the query results and also provides some flags
which tells you how an attribute is handled. Such a descriptor
| Byte Offset | Meaning | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Size of entry including the size information but without alignment. The size of the optional data can be calculated from this value. The begin of the next entry must be word aligned.
|
||||||||||||||||||||||||||||||||||||
| 4 | Attribute tag | ||||||||||||||||||||||||||||||||||||
| 8 | Type of attribute
|
||||||||||||||||||||||||||||||||||||
| 12 | Attribute flags
|
||||||||||||||||||||||||||||||||||||
| 16 | Begin of optional attribute specific |
You can obtain a certain attribute descriptor by calling theSWI ExtdAttrib 9. The same SWI is used to enumerate the
available attributes.
The following attribute tags have been specified in the moment. All other values are preserved.
All other values are preserved.
| Group | Attribute tag | Name | Attribute type | Format of additional output if not determined by the attribute type. | Format of additional input if not determined by the attribute type. | Remarks | |||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| &00000000 |
file attributes | 0 | |||||||||||||||||||||||||||||||||||||||
| &00000020 | Load Address | 1 | |||||||||||||||||||||||||||||||||||||||
| &00000021 | Execution Address | 1 | |||||||||||||||||||||||||||||||||||||||
| &00000022 | File type | 1 | |||||||||||||||||||||||||||||||||||||||
| &00000023 | Update time | 3 | |||||||||||||||||||||||||||||||||||||||
| &00000024 | File size | 2 | |||||||||||||||||||||||||||||||||||||||
| &00000025 | File size on disc | 2 | |||||||||||||||||||||||||||||||||||||||
| &00000026 | Icon big | 7 | |||||||||||||||||||||||||||||||||||||||
| &00000027 | Icon small | 7 | |||||||||||||||||||||||||||||||||||||||
| Names | &00000100 | File path | 4 | ||||||||||||||||||||||||||||||||||||||
| &00000101 | File name | 4 | |||||||||||||||||||||||||||||||||||||||
| Extended times | &00000111 | Creation time | 3 | ||||||||||||||||||||||||||||||||||||||
| &00000112 | Time of last access | 3 | |||||||||||||||||||||||||||||||||||||||
| User information | &00000120 | Creation user | 4 | ||||||||||||||||||||||||||||||||||||||
| &00000121 | Update user | 4 | |||||||||||||||||||||||||||||||||||||||
| &00000122 | User of last access | 4 | |||||||||||||||||||||||||||||||||||||||
| Misc Type info | &00000150 | File is for internal handling | 0 | To allow suppression of display of files used and maintained internally by the system | |||||||||||||||||||||||||||||||||||||
| Special indication | &00000180 | Name of sound indicating file type | 4 | ||||||||||||||||||||||||||||||||||||||
| Description | &00000200 | File short description | 4 | ||||||||||||||||||||||||||||||||||||||
| &00000201 | File search keywords | 4 | |||||||||||||||||||||||||||||||||||||||
| &00000300 | Title | 4 | |||||||||||||||||||||||||||||||||||||||
| &00000301 | 4 | ||||||||||||||||||||||||||||||||||||||||
| &00000302 | 4 | ||||||||||||||||||||||||||||||||||||||||
| &00000303 | |||||||||||||||||||||||||||||||||||||||||
The licenses tries to enumerate most of usual licenses for music, books, videos and programs. The field is for information only and not for blocking copying etc. Bits 0-15 are containing the number of parallel usably licenses for a unit e.g. a company or the allowed number of remaining usages. Unlimited usage is indicated by a value of &FFFF. A value of &0000 indicates unknown number. Bits 16-19 are containing a value which indicates kind of copying.
Bits 20-27 are containing a value which indicates kind of ownership.
|
|||||||||||||||||||||||||||||||||||||||||
|
User information (machine/user/local vary identification key) needs to be passed. Note that handlers may be complex including network synchronisation etc.. Can be used for software protection. Thinking about detailed concept is required. | ||||||||||||||||||||||||||||||||||||||||
| 4 | |||||||||||||||||||||||||||||||||||||||||
| 1 | |||||||||||||||||||||||||||||||||||||||||
| 1 | |||||||||||||||||||||||||||||||||||||||||
| 1 | |||||||||||||||||||||||||||||||||||||||||
| Icon flexible | 7 | Required size has to be set by caller | |||||||||||||||||||||||||||||||||||||||
| Backup | &00000700 | Date of last backup | 3 | ||||||||||||||||||||||||||||||||||||||
| &00000710 | Type of backup | 1 | |||||||||||||||||||||||||||||||||||||||
| &00000711 | Identifier of backup media | 4 | |||||||||||||||||||||||||||||||||||||||
| Graphics | &00000800 | Icon flexible | 7 | Required size has to be set by caller | |||||||||||||||||||||||||||||||||||||
| User range | &FFFFFFFF | Can be defined by the user as required | |||||||||||||||||||||||||||||||||||||||
| Internal usage | &FFFFFFFF | Indicates end of list |
How to handle write a handler for attributes
If you want to write an attribute handler please note the following considerations. An attribute may be fetched and maintained by several handlers. This can make sense e.g. think of a handler which keeps music titles inside a separate DB but a title can be also optionally stored inside the music file itself at certain music file formats. However it is likely that there are restrictions on the title length on both handlers. So it makes sense to pass on a fetch to both handlers and to store the longest information in the result. If an attribute is modified it makes sense to pass the modification to both handlers so that each handler can store the information as good as it can.
An attribute may be fetched and maintained by several handlers. This can make sense e.g.
think of a handler which keeps music titles inside a separate DB but a title can be also
optionally stored inside the music file itself at certain music file formats.
However it is likely that there are restrictions on the title length on both handlers.
So it makes sense to pass on a fetch to both handlers and to store the longest information
in the result. If an attribute is modified it makes sense to pass the modification to
both handlers so that each handler can store the information as good as it can.
It may be not easy to decide whether it is good to handle an existing attribute or whether to create a new one. Shall an icon generated by one handler modified directly by the second handler e.g. by pasting an overlay on it or shall an overlay provided. The second choice offers the possibility for the client to choose whether it wants to display the overlays or not and perhaps in case that there are several overlays in which order they shall be displayed. Attributes can be designed in some cases in such a way that they are of interest for a couple of programs. E.g. there may be several versioning tools but independently of the technical details the attributes may be the same. In general it would be glad if attributes are providing additional information that allow filer to handle attributes in a general way without having handling of every attribute hardcoded.
attribute or whether to create a new one. Shall an icon generated by one handler
modified directly by the second handler e.g. by pasting an overlay on it or
shall an overlay provided. The second choice offers the possibility for
the client to choose whether it wants to display the overlays or not and
perhaps in case that there are several overlays in which order they shall
be displayed. Attributes can be designed in some cases in such a way that
they are of interest for a couple of programs. E.g. there may be several
versioning tools but independently of the technical details the attributes
may be the same. In general it would be glad if attributes are providing
additional information that allow filer to handle attributes in a general
way without having handling of every attribute hardcoded.
Please contact … ... to obtain additional attribute tags.
When a handler is registered it is obtaining a subsequent tag number which is passed back to the handler as deregistration tag to allow a unique identification during the handler deregistration. Internally there are 16 Millions registrations possible until there will occur small problems within the handler priority handling. This shall be enough in practice for a solid operation.
back to the handler as deregistration tag to allow a unique identification
during the handler deregistration (internally there are 16 Millions tags
available until registration fails. This shall be enough in practice for
a solid operation).
A handler passes provides the information whether an operation is passed on in general or not inside the
general or not inside the
attribute descriptor . In real action the handler may behave different in certain special cases (that means that it prohibits a pass on whilst it reported that it is a pass on handler and vice versa) even in general it should behave as reported. A handler also passes a general priority information which affects all its attributes. Small values are meaning high priority and vice versa.
handler may behave different in certain special cases (that means that it prohibits
a pass on whilst it reported that it is a pass on handler and vice versa)
even in general it should behave as reported. A handler also passes
a general priority information which affects all its attributes.
Small values are meaning high priority and vice versa.
The handlers for an attribute are called in a certain order. The order is determined by sorting in such a way that handlers which are not passing operations on are called at the end of an operation. The next sort level is the priority information. The last sort level is the order of registration. Handlers which registered early are called at the end of an operation. The attributes which are handled by ExtAttrib internally are not passing on there results, have lowest priority level and are installed at first. So it is ensured that they are called at last.
The order is determined by sorting in such a way that handlers which are not passing
operations on are called at the end of an operation. The next sort level
is the priority information. The last sort level is the order of registration.
Handlers which registered early are called at the end of an operation.
The attributes which are handled by ExtAttrib internally are not passing
on there results, have lowest priority level and are installed at first.
So it is ensured that they are called at last.
A handler must be able to fetch or modify an attribute in a non multitasking way.
way. It may offer the possibility to fetch/modify an attribute in a multitasking way. This concept has been chosen to ensure that programs can operate in a non multitasking way.
way. This concept has been chosen to ensure that programs can operate in a non multitasking
way.
A handler modules isn’t isn't allowed to be relocated inside the RMA for there are absolute references.RMA for there
are absolute references.
Interfaces
ExtdAttrib_FetchAttribute
Fetches an attribute for a certain file.
On entry
R0 = Pointer to pollword (can be also used as identifier for the query).
R1 = Pointer to canonical file name.
R2 = Attribute tag.
R3 = Pointer to required attribute entry to obtain special request data.
R4 = Pointer to result entry for modification. May be 0 if only the required size has to be determined.
R5 = Pointer to data. This may be either free memory or the actual result. It can be 0 if there is no further memory or R4 is also 0 tobeobtaindetermined.maximal amount of memory.
R5R6 =PointerMaximaltosizedata.ofThismaybeeitherfree memory or the actual result.ItThecanlatterbedepends0whetherifresultthereisnolocated immediately before free memory (purged flag set) or not. In first case it includes the free memory whilst in latter case it covers only the actually used memory. If R5 is 0 this value will be be also 0.further memory or R4 is also 0 to obtain maximal amount of memory.R6 = Maximal size of free memory or the actual result. The latter depends whether result islocated immediately before free memory (purged flag set) or not. In first case it includesthe free memory whilst in latter case it covers only the actually used memory. If R5 is0 this value will be be also 0.
R7 = Information flags.Bit Meaning 0 1 indicates a new query, else it is a retry. 1 1 indicates that memory is purged which means that the result data is located in front of the free memory. of the free memory.2 1 indicates that the fetch shall be done in multitasking mode if possible.
On exit
R0 = Result of fetch
Value Meaning <0 Error code which occurred inside the handler and should be passed on to ExtAttribExtdattrib and the client.client.0 Noted for multitasking but not fulfilled yet. Try later again. 1 Result modified. Pass on. 2 Result modified. Don’tDon't pass on.3 Result not modified. Pass on. 4 Result not modified. Don’tDon't pass on.5 Want to modify. Purge up and retry. R7 = If result is 1 or 2 this must contain the amount of modified additional memory data.
Use
-
A handler examines whether it can deliver or update an attribute result for the given file. If the fetch can be done in multitasking way it must note pointer to pollword and the pointer to the canonical file name. It can rely on these pointers and their content until a query is finished or aborted. It can't rely on the other pointers, so it may have to note the attribute specific data of the required attribute entry internally. Of course it must queue the request internally. After doing so it has to return a code of 0 in R0.
If the fetch can be done in multitasking way it must note pointer to pollword and the pointerto the canonical file name. It can rely on these pointers and their content until a query isfinished or aborted. It can’t rely on the other pointers, so it may have to note the attributespecific data of the required attribute entry internally. Of course it must queue the requestinternally. After doing so it has to return a code of 0 in R0.After a result has been determined inside a multitasking way it must be buffered until the handler is requested again.
requestedinagain.ExtdAttrib_FetchAttribute for the attribute.The handler must not write the result into the result
entry or the result data memory whilst it is not requestedfor there may beparallel activities. After the handler has determined the result it has to set pollword to non zero.Therefore it should disable the interrupts, write the pollword word and reenable the interrupts.The pollword needs not to be set when the handler is in ExtdAttrib_FetchAttribute for theattribute.If a handler
can’tcan't find a result e.g. for the required attributedoesn’tdoesn't exists for the given file it shall leave everything unchanged and return a code 3 or 4 in R0. It shall also return code 3 or 4 in case that there is already a result but the handler doesn't want to modify it.given file it shall leave everything unchanged and return a code 3 or 4 in R0. It shall alsoreturn code 3 or 4 in case that there is already a result but the handler doesn’t want tomodify it.If a handler wants to modify the result of an attribute its behaviour depends on the kind of attribute and thereon whether there is already a result or not. In most cases it will be enough to set the values from offset 4 of the
the kind of attribute and thereon whether there is already a result or not. In most casesit will be enough to set the values from offset 4 of theresult entry onwards.Note that the handler has always (even for strings) has to return the exact size
of required data memory in R7 in case where offset 8 contains a offset to additional data.
At strings this must include the terminator. At the flags the handler must not change Bits 0 and
1 which are maintained by ExtdAttrib.After performing the update the handlermust return a code of 1 or 2 in R0. In case that the pointer to the result entryis 0 the handler can’t evaluate any existing result and can’t write its own result. Itsimply has to pass back the required amount of memory in R7 to allow determinationof result memory.If an attribute makes usage of additional result data this data has to be placed at that location which is given by R5. The length must no exceed the value given in R6 and may be limited by additional information as told inside
at that location which is given by R5. The length must no exceed the value givenin R6 and may be limited by additional information as told insidehas to be indicated by setting Bit 3 inside the flags ofresult entry . If the actual size is not big enough ExtdAttrib can be advised to rearrange the data in such a way that the additional result data for the actual attribute is located at the end of used memory. If this is the case or not will be indicated by the purged flag. If purged flag is 0 and more memory is required the handler can return a code of 4 to request a memory rearrangement after which ExtdAttrib will call the handler again with the purged flag set. The old entry can be overwritten and the additionally available memory can be used also. If there is still is not enough memory the handler shall use as much memory as available and makes sense (e.g. a string can be shortened but an icon of a specific size can't) and set Bit 4 inside the flags ofIf the actual size is not big enough ExtdAttrib can be advised to rearrange the datain such a way that the additional result data for the actual attribute is located at the endof used memory. If this is the case or not will be indicated by the purged flag.If purged flag is 0 and more memory is required the handler can return a code of4 to request a memory rearrangement after which ExtdAttrib will call thehandler again with the purged flag set. The old entry can be overwritten andthe additionally available memory can be used also. If there is still is not enoughmemory the handler shall use as much memory as available and makes sense (e.g. a stringcan be shortened but an icon of a specific size can’t) and setBit 4 inside the flags ofresult entry.
ExtdAttrib_Abort
Aborts a pending operation.
On entry
R0 = Pointer to pollword indicating the operation to abort.
R1 = Reason information. If 1 then pending modifications should be made.
On exit
Nothing returned.
Use
-
The handler removes any internal things related to a pending fetch or modification. The pending activity is identified by the pointer to pollword.
The pending activity is identified by the pointer to pollword.This call may be done as a result of a
SWISWI ExtdAttrib 9ExtdAttrib 9call. However it may be caused also by a RMKill of ExtdAttrib and it may occur in case of optimized modifications to force the handler to perform the delayed modifications.However it may be caused also by a RMKill of ExtdAttrib and it may occur in case of optimizedmodifications to force the handler to perform the delayed modifications.
ExtdAttrib_ModifyAttribute
Modifies an attribute for a certain file.
On entry
R0 = Pointer to pollword (can be also used as identfier for the query).
R1 = Pointer to canonical file name.
R2 = Attribute tag.
R3 = Pointer to modify attribute entry containing the modification data.
R7 = Information flags.Bit Meaning 0 1 indicates a new modification, else it is a retry. 1 Reserved 2 1 indicates that the modification shall be done in multitasking mode if possible.
On exit
R0 = Result of fetch
Value Meaning <0 Error code which occurred inside the handler and should be passed on to ExtAttrib and the client. client.0 Noted for multitasking but not fulfilled yet. Try later again. 1 Modified. Pass on. 2 Modified. Don’tDon't pass on.3 Not modified. Pass on. 4 Not modified. Don’tDon't pass on.5 Modified in an optimized way. Pass on. This sets a marker inside ExtdAttrib that something is still open for this modification on this handler and it must be called at the end of modification by that something is still open for this modification on this handler and itmust be called at the end of modification by6 Modified in an optimized way. Don’tDon't pass on.This sets a marker inside ExtdAttrib that something is still open for this modification on this handler and it must be called at the end of modification bythat something is still open for this modification on this handler and itmust be called at the end of modification by
Use
-
A handler examines whether it can modify an attribute for the given file. If the modification can be done in multitasking way it must note pointer to pollword and the pointer to the canonical file name. It can rely on these pointers and their content until a modification is finished or aborted. It can't rely on the other pointers, so it has to note the modification data of the required attribute entry internally. Of course it must queue the request internally. After doing so it has to return a code of 0 in R0.
If the modification can be done in multitasking way it must note pointer to pollword and the pointerto the canonical file name. It can rely on these pointers and their content until a modification isfinished or aborted. It can’t rely on the other pointers, so it has to note the modification dataof the required attribute entry internally. Of course it must queue the request internally.After doing so it has to return a code of 0 in R0.After a modification has been perfomed in a multitasking way the result must be noted until the handler is called again for the attribute. After the handler has performed the modification it has to set pollword to non zero. The pollword needs not to be set when the handler is in ExtdAttrib_ModifyAttribute for the attribute.
the handler is called again for the attribute. After the handler has performed the modification it has to setpollword to non zero. Therefore it should disable the interrupts, write the pollword word andreenable the interrupts. The pollword needs not to be set when the handler is inExtdAttrib_ModifyAttribute for the attribute.If a handler
can’tcan't perform the modification e.g. for the required attributedoesn’tdoesn't exists for the given file it shall return a code 3 or 4 in R0. In case that a handler performed the modification it shall return a code 1 or 2 in R0.given file it shall return a code 3 or 4 in R0. In case that a handler performed the modificationit shall return a code 1 or 2 in R0.A handler can collect a couple of modifications e.g. for the RISC OS standard attributes and modify them in one go at the end. However the handler doesn't know when the last attribute modification call happens. This may rely on the pass-on information of the other handlers too. Therefore it returns code 5 or 6 so that ExtAttrib knows that something must be done at the end and informs the handler by calling
RISCOS standard attributes andmodify them in one go at the end. However the handler doesn’t know when the last attributemodification call happens. This may rely on the pass-on information of the other handlers too.Therefore it returns code 5 or 6 so that ExtAttrib knows that something must be done at theend and informs the handler by callingExtdAttrib_Abort.
Service Calls
Service_ExtAttribStarting
(Service Call &)
On entry
On exit
Interrupt
Processor mode
Re-entrancy
Use
You must not claim this service call.
Service_ExtAttribStopping
(Service Call &)
On entry
On exit
Interrupt
Processor mode
Re-entrancy
Use
You must not claim this service call.
SWISWI Calls Calls
ExtdAttrib
( (SWI &)SWI &)
Performs various actions to obtain and modify file attributes.
On entry
R0 = reason code
Other registers depend on reason code
On exit
R0 preserved
Other registers depend on reason code
Interrupt
Interrupts are enabled.
Fast Interrupts areenabledenabled.But see the remarks under Re-entrancy.
Processor mode
Processor is in SVC mode
Re-entrancy
SWISWI is re-entrant but you should not make calls to it from interrupts for some common internal structures may be not valid if internal operations are interrupted. If required you shall put your interrupt into a callback to ensure integrity.is reentrant
Processor mode
Processor is in SVC mode
Use
-
The particular action of ExtdAttrib is given by the reason code in R0 as follows:
R0 Action Page 0 Fetches file attributes using File$Path non multitasking. SWISWI ExtdAttrib 0-7ExtdAttrib 0-71 Fetches file attributes using a separate path string non multitasking. SWISWI ExtdAttrib 0-7ExtdAttrib 0-72 Fetches file attributes using a path variable non multitasking. SWISWI ExtdAttrib 0-7ExtdAttrib 0-73 Fetches file attributes non multitasking. SWISWI ExtdAttrib 0-7ExtdAttrib 0-74 Fetches file attributes using File$Path multitasking. SWISWI ExtdAttrib 0-7ExtdAttrib 0-75 Fetches file attributes using a separate path string multitasking. SWISWI ExtdAttrib 0-7ExtdAttrib 0-76 Fetches file attributes using a path variable multitasking. SWISWI ExtdAttrib 0-7ExtdAttrib 0-77 Fetches file attributes multitasking. SWISWI ExtdAttrib 0-7ExtdAttrib 0-78 Aborts a pending operation in multitasking mode. SWISWI ExtdAttrib 8ExtdAttrib 89 Fetches information about a tag and enumerates the tags. SWISWI ExtdAttrib 9ExtdAttrib 910 Registers an attribute handler. SWISWI ExtdAttrib 10ExtdAttrib 1011 Deregisters an attribute handler. SWISWI ExtdAttrib 11ExtdAttrib 111612ModifiesFreesfilememoryattributeswhichusinghasFile$Pathbeennonautomaticallymultitasking.allocated by ExtdAttrib.SWISWI ExtdAttrib 12ExtdAttrib 16-231716Modifies file attributes using aFile$Pathseparatepathstringnon multitasking.SWISWI ExtdAttrib 16-23ExtdAttrib 16-231817Modifies file attributes using a separate path variablestring non multitasking.SWISWI ExtdAttrib 16-23ExtdAttrib 16-231918Modifies file attributes using a path variable non multitasking. SWISWI ExtdAttrib 16-23ExtdAttrib 16-232019Modifies file attributes usingnonFile$Pathmultitasking.SWISWI ExtdAttrib 16-23ExtdAttrib 16-232120Modifies file attributes using aFile$Pathseparatepathstringmultitasking.SWISWI ExtdAttrib 16-23ExtdAttrib 16-232221Modifies file attributes using a separate path variablestring multitasking.SWISWI ExtdAttrib 16-23ExtdAttrib 16-232322Modifies file attributes using a path variable multitasking. SWISWI ExtdAttrib 16-23ExtdAttrib 16-2323 Modifies file attributes multitasking. SWI ExtdAttrib 16-23
ExtdAttrib 0-7
( (SWI &)SWI &)
Fetches file attributes
On entry
R0 = 0 to 7
R1 = Pointer to object name.
R2 = Optional pointer to path string or path variable.
R3 = Pointer to attribute result memory block. If set to 0 and the maximal size of result memory is also set to 0 the maximal required size will be reported without generating the information.
R4 = Maximal size of attribute result memory block. Must be set to 0 if only the size should be fetched. Ifsetthe value is non 0 but the pointer to resulting memory block is 0 Extdattrib will claim themaximalrequiredsizememorywillinside its own dynamic area. The claimed memory won't bereportedlargerwithoutthan the value given in this register but may be smaller.
generatingwiththerequiredinformation.attributes.
R4R6 =MaximalAssignedsizequery handle, must be 0 at start ofattributearesultquery.memoryblock.
R5R7 = Pointer tolistpollwordwithevaluatedrequiredatattributes.start of a query else ignored. If 0 at start of a query the pollword is automatically assigned by ExtdAttrib. If it is non 0 the value is taken as pointer to the pollword.
R6R8 =AssignedReserved.queryMusthandle,mustbe0setattostart0.ofaquery.R7 = Pointer to pollword evaluated at start of a query else ignored.If 0 at start of a query the pollword is automatically assigned byExtdAttrib. If it is non 0 the value is taken as pointer to the pollword.
On exit
R0-R3, R5 preserved
R4 = size of used block when all attributes collected, else preserved.
R6 = 0 when all attributes collected elsepreserved.assigned query handle.
R6R7 =0Pointerwhentoallpollwordattributesforcollectedquery if query not finished yet. Is kept during a query.else assigned query handle.R7 = Pointer to pollword for query if query not finished yet. Is keptduring a query.
Use
-
The operation code determines the kind of file path handling
Bit 1 Bit 0 Path used 0 0 File$Path system variable 0 1 path string pointed to by R2 1 0 path variable pointed to by R2 1 1 none and the multitasking:
Bit 2 Multitasking mode 0 Single Task 1 Multitask If SWI is multitasking it returns the query handle and an automatically allocated pollword in case that a part of the query is processed in multitasking mode. In this case the according part is stored internally. You can either call the SWI periodically if you like or you can wait until pollword becomes non zero. However don't make the assumption that if the pollword becomes non zero your query is entirely completed. It may only have become a bit more complete. So you may have to poll again and again.
SWIis multitasking it returns the query handle and an automaticallyallocated pollword in case that a part of the query is processedin multitasking mode. In this case the according part is storedinternally. You can either call theSWIperiodically if you likeor you can wait until pollword becomes non zero. However don’t makethe assumption that if the pollword becomes non zero your query isentirely completed. It may only have become a bit more complete.So you may have to poll again and again.The list containing the required attributes consists of one entry for each attributed with the following format:
each attributed with the following format:Offset Meaning 0 Size of entry (incl. this size field) a size of zero marks end of list but without alignment. The size of the optional data can be calculated from this value.
The size of the optional data can be calculated from this value.The begin of the next entry must be word aligned.
4 Tag of the required attribute 8 Optional attribute specific data which format is determined by the attribute. by the attribute.The result consists of an array of entries which is preceded by the number of array elements and followed by detailed data for each attribute if the information doesn't fit into the array entry. The array will be set up at start completely. However the contents of the entries may change until the query is finished. To find out whether an entry is valid please check Bit 0 of the flags of an attribute.
number of array elements and followed by detailed data for each attributeif the information doesn’t fit into the array entry. The array willbe set up at start completely. However the contents of the entries maychange until the query is finished. To find out whether an entry isvalid please check Bit 0 of the flags of an attribute.Offset Meaning 0 Number of array elements. 4 Array of result entries. Each entry has the following format:
Offset Meaning 0 Attribute tag 4 Flags
Bit Meaning 0 Information is valid. May be invalid during queries in multitasking environments (Maintained by ExtdAttrib). 1 Attribute exists for the file (Maintained by ExtdAttrib). 2 Attribute is writable for the file 3 Data is incomplete due to limitation (only with attribute types 4 and 6). 4 Data is incomplete due to insufficient result memory. 8 32 Bit value or offset to data from start if available and required. 12 64 Bit value or size of data.
ExtdAttrib 8
( (SWI &)SWI &)
Aborts a pending operation in multitasking mode.
On entry
R0 = 8
R1 = Reserved. Must be set to 0.
R6 = handle of operation to abort.
On exit
AllR0,registersR6 preserved
Use
Aborts the operation belonging to the given handle in multitasking mode.
You must not perform any queries or modifications using this handle until it is
passed again towards you as a result of new file attribute information
fetch/modification.Aborts the operation belonging to the given handle in multitasking mode. You must not perform any queries or modifications using this handle until it is passed again towards you as a result of new file attribute information fetch/modification.
ExtdAttrib 9
( (SWI &)SWI &)
Fetches information about a tag and enumerates the tags.
On entry
R0 = 9
R2R1 = Reserved. Must be set to 0.
R3R2 =PointerFlagstowithresultingthe following meaning:attribute descriptormemory block.If set to 0 the maximal required size will be reported withoutgenerating the information.R4 = Maximal size of result memory block.R6 = Attribute tag for which information should be obtained.&FFFFFFFFindicates first tag in list.Bit Meaning 0 Set indicates that only the first entry shall of an attribute shall be reported. 1 If set then do not return exact entry for attribute tag and internal search tag but also allow the next entry in case that the given combination is not found. This Bit is set in general at start of an enumeration or request for a particular tag. In both cases the internal search tag must be set to 0 but in the first case the attribute tag must be set to 0 whilst it must contain the required tag in the later case. 2 If set only the actual attribute tag is allowed for the enumeration. 3 - 31 Reserved. Must be set to 0. R3 = Pointer to resulting attribute descriptor memory block. If set to 0 and the maximal size of result memory is also set to 0 the maximal required size will be reported without generating the information.
R4 = Maximal size of result memory block. Must be set to 0 if only the size should be fetched. If the value is non 0 but the pointer to resulting memory block is 0 Extdattrib will claim the required memory inside its own dynamic area. The claimed memory won't be larger than the value given in this register but may be smaller.
R5 = Internal search tag. It shall contain the value returned by the previous call. &0 indicates first entry in list.
R6 = Attribute tag for which information should be obtained. &0 indicates first tag in list.
On exit
R0-R3R0 preserved.
R6R2 =NumberBitof1nextwilltag.be cleared.
R3 = Pointer to resulting memory block inside dynamic area of ExtdAttrib&if 0 at entry and R4 non 0 else preserved. R4 = If the pointer to memory block is 0 at entry R4 will contain the required or allocated size to store theFFFFFFFFattribute descriptorindicatesendoftaglistincluding alignment.
R5 = Internal search tag of next tag.
R6 = Number of next tag. &FFFFFFFF indicates end of list.
Use
The request will return an attribute descriptor in the given
memory which describes the given attribute. It also returns the attribute tag
of the next attribute (in numerical ascending order) if available so that you can use
this function to enumerate the attributes. However the information is
retrieved directly from the registered attribute handlers. There can be
several handlers registered for the same attribute. Only the information
of the first handler will be returned. There might be slightly different
internal flag information for each handler which must be therefore ignored
by your evaluation.The request will return an attribute descriptor in the given memory which describes the given attribute. It also returns the attribute tag of the next attribute (in numerical ascending order) if available so that you can use this function to enumerate the attributes. The information is retrieved directly from the registered attribute handlers. There can be several handlers registered for the same attribute. All are enumerated one by one in the order of their calling making usage of the internal search tag. If setting Bit 0 of R2 only the first entries of the attributes are enumerated. However take into account that handlers may provide some flags in a different way and so you won't see the whole truth about an attribute if only evaluating the first handler entry.
An error is returned if no entry is found for the given attribute tag and internal search tag combination.
ExtdAttrib 10
( (SWI &)SWI &)
Registers an attribute handler.
On entry
R0 = 10
R1 =PointerModuletobaseregistrationaddress.block.
R2 = Pointer tolistofregistration block.
R3 = Handler private word.
R4 = Pointer to list of attribute descriptors.
R3R5 = Handlerprivatepriority.word.7 Bit Value. If you want to have your handler the lowest priority. You should set the value to &FFFFFFFF.
R4R6 =HandlerReserved.priority.Must7beBitsetValue.to 0.
On exit
R1-R3R0-R3, R5 preserved
R4 = Handler deregistration tag assigned by ExtdAttrib.
Use
Every attribute handler has to register itself using this SWI.
The registration block consists of the following entries:
Offset Meaning 0 Size of registration block including size field 4 Offset of routine to fetch attributes for a file (ExtdAttrib_FetchAttribute) 8 Offset of routine to abort multitasking operation (ExtdAttrib_Abort) 12 Offset of routine to modify attributes for a file (ExtdAttrib_ModifyAttribute)
ExtdAttrib 11
( (SWI &)SWI &)
Deregisters an attribute handler.
On entry
R0 = 11
R4R1 =HandlerReserved.deregistrationMusttagbe set to 0.
R4 = Handler deregistration tag.
On exit
R0, R4 preserved
Use
Handler is deregistered from ExtdAttrib. Pending modifications
shall be perfomed by the handler. Pending queries must be dropped.
ExtdAttrib will remove the handler from its internal structure.
Pending operations will be continued at the remaining handlers if
possible and the pollword will be set to non zero.Handler is deregistered from ExtdAttrib. Pending modifications shall be perfomed by the handler. Pending queries must be dropped. ExtdAttrib will remove the handler from its internal structure. Pending operations will be continued at the remaining handlers if possible and the pollword will be set to non zero.
ExtdAttrib 16-23 12
( (SWI &)SWI &)
Frees memory which has been automatically allocated by ExtdAttrib.
On entry
R0 = 12
R1 = Reserved. Must be set to 0.
R3 = Pointer to memory which should been deallocated.
On exit
R0, R1, R4 preserved
Use
-
In some operations you can request that ExtdAttrib claims result memory for you inside its own dynamic area. If the memory is no longer used you must free it by using this SWI.
ExtdAttrib 16-23
(SWI &)
Changes attributes for a given file.
On entry
R0 = 16 to 23
R1 = Pointer to object name.
R2 = Optional pointer to path string or path variable.
R5 = Pointer to list with modified attributes.
R6 = Assigned query handle, must be 0 at start of a query.
R7 = Pointer to pollword evaluated at start of a query else ignored. If 0 at start of a query the pollword is automatically assigned by ExtdAttrib. If it is non 0 the value is taken as pointer to the pollword.
Ifset0toat0.startofaquerythepollwordisautomaticallyassignedbyExtdAttrib. If it is non 0 the value is taken as pointer to the pollword.
On exit
R0-R2, R5 preserved
R6 = 0 when all attributes modified else assigned modification handle.
R7 = Pollword for query if query not finished yet. Is keptelseassignedmodificationhandle.during a query.R7 = Pollword for query if query not finished yet. Is keptduring a query.
Use
-
The operation codes determine the kind of file path handling and the multitasking in the same kind as described under the
and the multitasking in the same kind as described under thefetching of.
attributesThe list containing the modified attributes consists of one entry for each attributed with the following format:
each attributed with the following format:Offset Meaning 0 Size of entry (incl. this size field) a size of zero marks end of list but without alignment. The size of the modified data can be calculated from this value.
The size of the modified data can be calculated from this value.The begin of the next entry must be word aligned.
4 Tag of the attribute which should be modified.
8 Number of modifications performed. Bit 31=1 indicates that modification is complete.
12 Modified attribute data which format is determined by the attribute.
by the attribute.
The number of modifications is increased for every modification done by a handler. If used in multitasking mode the program can evaluate which attributes have been modified for the file.
If used in multitasking mode the program can evaluate which attributes have been modified for
the file.
Social
and
ROOL Store
Buy RISC OS Open merchandise here, including SD cards for Raspberry Pi and more.