Safeguarding the past, present and future of RISC OS for everyone
Account
News | Downloads | Bugs | Bounties | Forums | Library

Extended Attributes API Specification (Rev #2, changes)

Showing changes from revision #1 to #2: 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.

<!DOCTYPE <notexttile> html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <html> <head>ExtdAttrib </head> <body alink='red' bgcolor='white' link='blue' text='black' vlink='darkblue'>

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 programm 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 by the calling application. 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 requeried 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 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 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.
 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 modificable changeable and so ExtdAttrib provides a SWI with which an application can change modificable 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.

<pBecause ExtdAttrib a and arbitrary attributes easy graphics handling implement including is it of provides sound thumbnail to viewer with>

Note Because this all this is not provided ExtdAttrib itself provides but handling may of be arbitrary provided attributes by including additional sound modules and or graphics calling programs.
 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.

Displaying attributes

Your application has to enumerate the available attributes first. According the reported
 According to the reported attribute tags it has to decided decide whether to handle the 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
 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 attribut handlers are performing this. If the result of this query informs your application that an attirbute 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
 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.

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
 has the following format:

Byte Offset Meaning
0

Size of entry including the size information. information 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.

If 0 then tag is invalid.The begin of the next entry must be word aligned.

If 0 and obtained by a SWI ExtdAttrib 9
call then tag is invalid. A 0 during a handler registration indicates
end of list with supported attributes.
4 Attribute tag
8

Type of attribute

Value Meaning Position inside query result attribute entries Modification format
0 Bitflag Bit flag Four Bytes from offset 8 containing &00000000 or &00000001; &00000001. Four Bytes from offset 12 containing &00000000 or &00000001; &00000001.
1 32 Bit Integer Four Bytes from offset 8. Four Bytes from offset 12.
2 64 Bit Integer Eight Bytes from offset 8. Eight Bytes from offset 12.
3 Time or Duration ... … Same format as on fetching. Data starts from offset 12.
4 String Offset 8 gives offset to start of string from start of result query block. String has unicode format and is terminated by 0.
 String has Unicode format and is terminated by 0.
You can limit the maximal size on query.		 Unicode string starts from offset 12. Size is determined by size in offset 0 incl. the terminator.
5 Data fix sized Offset 8 gives offset to start of data from start of result query block. Size is determined by attribute.
 Size is determined by attribute.		 Data of fixed fix size starts from offset 12.
6 Data flexible size Offset 8 gives offset to start of data from start of result query block.
Offset 16 contains the data size.
You can limit the maximal size on query.		 Data starts from offset 12. Size is determined by size in offset 0.
7 Icon information Offset 8 gives offset to start of sprite include sprite size from start of result query block.
12

Attribute flags

Bit Meaning
0 Pass on when if attribute determined is modified by this handler.
1 Attribute is writable for this handler.
2 Attribute is an overlay (only with attribute type 7) for identification purposes.
16 Begin of optional attirbute attribute specific data

You can obtain a certain attribute descriptor by calling theSWI ExtdAttrib 9
 . The same SWI is used to enumerate the available attributes.SWI 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 Remarks
RISC OSRISC OS &00000000 - – &0000001F file attributes 0
&00000020 Load Address 1
&00000021 Execution Address Adress 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
Music &00000300 Title 4
&00000301 Interpret 4
&00000302 Author 4
&00000303 Verlag 4
&00000304 Duration 3
&00000305 Date of publishing 3
&00000310 Type of Music 1
&00000320 User dependent rating 1
&00000321 Play volume 1
Revision Handling &00000400 Checkout state 1
&00000410 Checkout overlay small 7
&00000411 Checkout overlay big 7
Graphics &00000500 Icon flexible 7 Required size has to be set by caller
Internal usage &FFFFFFFF &FFFFFFFF Indicates start/end of list

How to handle 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 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 changing an attribute it makes sense to pass the change 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.

A handler must be able to fetch or modify an attribute in a non multitasking way.
 way. It may offer the possibilty possibility to fetch/modify an attribute in a multitasking way. This concept has been choosen to ensure that program can operate in a non multitasking way.
 way. This concept has been chosen to ensure that programs can operate in a non multitasking
 way.

... …

Please contact ... … to obtain additional tags.

Interfaces

ExtdAttrib_FetchAttribute

Fetches an attribute for a certain file.

On entry

R0 = Pointer to pollword (can be also used as identfier 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 to obtain be maximal determined. amount of memory.
R6 R5 = Maximal Pointer size to of data. This may be either free memory or the actual result. The It latter can depends be whater result is located 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 0 if there is no 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 is
 located 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.
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 multitaking 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 Result modified. Pass on.
2 Result modified. Don't Don’t pass on.
3 Result not modified. Pass on.
4 Result not modified. Don't Don’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 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.

After a result has been determined inside a mulitasking multitasking way it must be buffered until the handler is requested again.The handler must not write the result into the result entry or the result data memory whilst it is not requested
 for there may be parallel 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 requested ExtdAttrib_FetchAttribute again. for the attribute.The handler must not write the result into the result
entry or the result data memory whilst it is not requested for there may be
 parallel 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 the
 attribute.

If a handler can't can’t find a result e.g. for the required attribute doesn't doesn’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 also
 return code 3 or 4 in case that there is already a result but the handler doesn’t want to
 modify 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 cases
 it will be enough to set the values from offset 4 of the result 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 must not change Bits 0 and 1 which are mantained by ExtdAttrib.
 After performing the update the handler must return a code of 1 or 2 in R0. In case that the pointer to the result entry is 0 the handler can't evaluate any existing result and can't write its own result. It simply has to pass back the required amount of memory in R7 to allow determination of result memory.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 handler
 must return a code of 1 or 2 in R0. In case that the pointer to the result entry
 is 0 the handler can’t evaluate any existing result and can’t write its own result. It
 simply has to pass back the required amount of memory in R7 to allow determination
 of 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 additonal information as told inside
 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
 required attribute entry . Such a limitation has to be indicated by setting Bit 3 inside the flags of
 has to be indicated by setting Bit 3 inside the flags of result 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 then 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 availlable 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 specifc size can't) and set Bit 4 inside the flags of
 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 specifc size can’t) and set
 Bit 4 inside the flags of result 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 modifiactions 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 SWI ExtdAttrib 9SWI ExtdAttrib 9 call. 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 optimized
 modifications 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 query, modification, else it is a retry.
1 Reserved
2 1 indicates that the fetch modification shall be done in multitaking 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 Modified. Pass on.
2 Modified. Don't Don’t pass on.
3 Not modified. Pass on.
4 Not modified. Don't Don’t pass on.
5 Modified in an optimized way. Pass 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 it
 must be called at the end of modification by
 ExtdAttrib_Abort.
6 Modified in an optimized way. Don't Don’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 by
 that something is still open for this modification on this handler and it
 must be called at the end of modification by
 ExtdAttrib_Abort.
Use

A handler examines whether it can modify an attribute result 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 query is finished or aborted. It can't rely on the other pointers, so ithave 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 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.

After a modifcation modification has been perfomed inside in a mulitasking multitasking way the result must be noted until the handler is requested again. After the handler has performed the modification 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_ModifyAttribute for the attribute.
 the handler is called again for the attribute. After the handler has performed the modification 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_ModifyAttribute for the attribute.

If a handler can't can’t perfom perform the modifiaction modification a.g. e.g. for the required attribute doesn't doesn’t exists for the given file it shall return a code 3 or 4 in R0. In case that a handler performed the update 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 modification
 it 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 chnage 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 callingRISC 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 ExtdAttrib_Abort.

Service Calls

Service_DeclareAttribHandlers
(Service Call &)

On entry

On exit

Interrupt

Processor mode

Re-entrancy

Use

You must not claim this service call.

SWI Calls

ExtdAttrib Service_ExtAttribDying
(SWI (Service Call &)

Performs various actions to obtain and manipulate file attributes.

On entry
On exit

Interrupt

Processor mode

Re-entrancy

Use

You must not claim this service call.

SWI Calls

ExtdAttrib
(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 are enabled

Processor mode

Processor is in SVC modeSVC mode

Re-entrancy

SWI is reentrantSWI is reentrant

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. SWI ExtdAttrib 0-7SWI ExtdAttrib 0-7
1 Fetches file attributes using a separate path string non multitasking. SWI ExtdAttrib 0-7SWI ExtdAttrib 0-7
2 Fetches file attributes using a path variable non multitasking. SWI ExtdAttrib 0-7SWI ExtdAttrib 0-7
3 Fetches file attributes non multitasking. SWI ExtdAttrib 0-7SWI ExtdAttrib 0-7
4 Fetches file attributes using File$Path multitasking. SWI ExtdAttrib 0-7SWI ExtdAttrib 0-7
5 Fetches file attributes using a separate path string multitasking. SWI ExtdAttrib 0-7SWI ExtdAttrib 0-7
6 Fetches file attributes using a path variable multitasking. SWI ExtdAttrib 0-7SWI ExtdAttrib 0-7
7 Fetches file attributes multitasking. SWI ExtdAttrib 0-7SWI ExtdAttrib 0-7
8 Aborts a pending opreation operation in multitasking mode. SWI ExtdAttrib 8SWI ExtdAttrib 8
9 Fetches information about a tag and enumerates the tags. SWI ExtdAttrib 9SWI ExtdAttrib 9
10 Registers an attribute handler. SWI ExtdAttrib 10SWI ExtdAttrib 10
11 Deregisters an attribute handler. SWI ExtdAttrib 11SWI ExtdAttrib 11
16 Modifies file attributes using File$Path non multitasking. SWI ExtdAttrib 16-23SWI ExtdAttrib 16-23
17 Modifies file attributes using a separate path string non multitasking. SWI ExtdAttrib 16-23SWI ExtdAttrib 16-23
18 Modifies file attributes using a path variable non multitasking. SWI ExtdAttrib 16-23SWI ExtdAttrib 16-23
19 Modifies file attributes non multitasking. SWI ExtdAttrib 16-23SWI ExtdAttrib 16-23
20 Modifies file attributes using File$Path multitasking. SWI ExtdAttrib 16-23SWI ExtdAttrib 16-23
21 Modifies file attributes using a separate path string multitasking. SWI ExtdAttrib 16-23SWI ExtdAttrib 16-23
22 Modifies file attributes using a path variable multitasking. SWI ExtdAttrib 16-23SWI ExtdAttrib 16-23
23 Modifies file attributes multitasking. SWI ExtdAttrib 16-23SWI ExtdAttrib 16-23

ExtdAttrib 0-7
(SWI ( &)SWI &)

Fetches file attributes

On entry

R0 = 0 to 7
R1 = pointer Pointer to object name name.
R2 = optional Optional pointer to path string or path variable variable.
R3 = Pointer to attribute result memory block. If set to 0 the maximal required size will be reported without generating the information.
R4 = Maximal If set to 0 the maximal required size of will attribute be result reported memory without block
R5 = Pointer to list with generating required the attributes information.
R6 R4 = Assigned Maximal query size handle, must be 0 at start of a attribute query. result memory block.
 R5 = Pointer to list with required 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.

On exit

R0-R3, R5 preserved
R4 = size of used block when all attributes collected, else preserved.
R6 = 0 when all attributes collected else assigned preserved. query handle.
R7 R6 = Pollword 0 for when query all if attributes query collected not finished yet. Is kept during a query.
 else assigned query handle.
 R7 = Pointer to pollword for query if query not finished yet. Is kept
 during 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.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.

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 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.

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 ( Mantained Maintained by ExtdAttrib).
1 Attribute exists for the file ( Mantained 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
R6 = handle of operation to abort.

On exit

All registers preserved

Use

Aborts the operation belonging to the given handle in multitasking mode. You must not perform any queries or modfications using this handle until it is passed again towards you as a result of new file attribute information fetch/modification.
 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
R2 = Reserved. Must be set to 0.
R3 = Pointer to resulting attribute descriptor memory block. if set to 0 the maximal required size will be reported without generating the information.
R4 = Maximal size of tag result memory block.attribute descriptor memory block.
R6 = Attribute tag for which information should be obtained. If set to 0 the maximal required &FFFFFFFF size indicates will first be tag reported in without list.
 generating the information.
 R4 = Maximal size of result memory block.
 R6 = Attribute tag for which information should be obtained.
 &FFFFFFFF indicates first tag in list.

On exit

R0-R3 preserved.
R6 = Number of next tag. &FFFFFFFF indicates end of tag list
 &FFFFFFFF indicates end of tag 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.
 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.

ExtdAttrib 10
(SWI ( &)SWI &)

Registers an attribute handler.

On entry

R0 = 10
 R1 = Pointer to registration block.
 R2 = Pointer to list of attribute descriptor.
 R3 = Handler private word.

On exit

R1-R3 preserved
R4 = Handler deregistration tag assigned by ExtdAttrib.

Use

ExtdAttrib 11
(SWI ( &)SWI &)

Deregisters an attribute handler.

On entry

R0 = 11
 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.

ExtdAttrib 16-23
(SWI ( &)SWI &)

Changes attributes for a given file.

On entry

R0 = 16 to 23
R1 = pointer Pointer to object name name.
R2 = optional Optional pointer to path string or path variable variable.
R5 = Pointer to list with modified attributes 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.

On exit

R0-R2, R5 preserved
R6 = 0 when all attributes modified else assigned query handle.
R7 = Pollword for query if query not finished yet. Is kept else assigned modification handle. during a query.
 R7 = Pollword for query if query not finished yet. Is kept
 during a query.

Use

The operation codes determine the kind of file path handling and the multitasking in the same kind as described under thefetching of attributes
 and the multitasking in the same kind as described under the fetching of
attributes.

The 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.

</body> </html>

</notextile>

Revision from July 2, 2007 20:49:31 by Thomas Milius (126)?
Forward in time (4 more) | Back in time (1 more) | See current | Hide changes | History | Rollback | Linked from: Individual specifications

Search the Wiki

Social

Follow us on and

ROOL Store

Buy RISC OS Open merchandise here, including SD cards for Raspberry Pi and more.

Donate! Why?

Help ROOL make things happen – please consider donating!

RISC OS IPR

RISC OS is an Open Source operating system owned by RISC OS Developments Ltd and licensed primarily under the Apache 2.0 license.

Navigation

  • Home Page
  • All Pages
  • Recently Revised
  • Authors
  • Feeds
Contact Us  |  About Us

The RISC OS Open Instiki theme is based on Insitki's default layout
Site design © RISC OS Open Limited 2024 except where indicated

Hosted by Arachsys

Instiki 0.19.1(MML+)
This site runs on Rails