The File System: 5.3 Files: GEOS Extended Attributes

FileGetHandleExtAttributes(), FileGetPathExtAttributes(), FileSetHandleExtAttributes(), FileSetPathExtAttributes(), FileExtAttrDesc, FileDateAndTime, FileAttrs

All GEOS files, whether they contain code or data, have special extended attributes . Geodes cannot look at these directly; instead, they make calls to the file system when they want to examine or change the attributes. There are many different extended attributes; however, they are all accessed and changed in a uniform way. Some of the extended attributes are also supported for non-GEOS files. The following extended attributes are currently available:

FEA_MODIFICATION
FEA_FILE_ATTR
FEA_SIZE
FEA_FILE_TYPE
FEA_FLAGS
FEA_RELEASE
FEA_PROTOCOL
FEA_TOKEN
FEA_CREATOR
FEA_USER_NOTES
FEA_NOTICE
FEA_CREATION
FEA_PASSWORD
FEA_CUSTOM
FEA_NAME
FEA_GEODE_ATTR
FEA_PATH_INFO
FEA_FILE_ID
FEA_DESKTOP_INFO
FEA_DRIVE_STATUS
FEA_DISK
FEA_DOS_NAME
FEA_OWNER
FEA_RIGHTS

There are also two special constants, FEA_MULTIPLE and FEA_END_OF_LIST. These are also described below.

There are two different routines to read a file's extended attributes: FileGetHandleExtAttributes() and FileGetPathExtAttributes() . These routines are the same except in the way the file is specified: in one, the handle of an open file is passed, whereas in the other, the address of a path string is passed.

FileGetHandleExtAttributes() takes four arguments. The first is the handle of the file whose attributes are desired; this may be a VM file handle or a byte-file handle. The second is a constant specifying the attribute desired. All extended attributes which are currently supported are listed above; more may be added later. The third is a pointer to a buffer; the attribute's value will be written into that buffer. The fourth argument is the size of the buffer (in bytes). Before it returns, FileGetHandleExtAttributes() will write the value of the attribute into the buffer. If successful, it will return zero; otherwise, it will return one of the following error codes:

ERROR_ATTR_NOT_SUPPORTED: The file system does not recognize the attribute constant passed.
ERROR_ATTR_SIZE_MISMATCH: The buffer passed was too small for the attribute requested.
ERROR_ATTR_NOT_FOUND: The file does not have a value set for that attribute. This is returned if you try to get certain extended attributes of a non-GEOS file.
ERROR_ACCESS_DENIED: You do not have read-access to the file.

FileGetHandleExtAttrs() can also fetch several attributes at once. For details on this, see the section on FEA_MULTIPLE ( FEA_MULTIPLE ).

You can get a file's extended attributes without having it open by calling FileGetPathExtAttributes() . This routine takes a pointer to a null-terminated path string instead of a file handle. This makes it suitable for examining the attributes of an executable file or directory. Note that the file system will still have to open the file in order to get the attributes. If any geode (including the caller) has the file open with "deny-read" exclusive, the call will fail with error condition ERROR_ACCESS_DENIED. If it could not find the file specified, it will return ERROR_FILE_NOT_FOUND.

To change one of a file's extended attributes, make a call either to FileSetHandleExtAttributes() or to FileSetPathExtAttributes (). These routines take the same arguments as the FileGet...() routines above; however, they copy the data from the buffer into the attribute, instead of vice versa. These routines return zero if the operation was successful. Otherwise, they return one of the following error codes:

ERROR_ATTR_NOT_SUPPORTED: The file system does not recognize the attribute constant passed. This is returned if you try to set an extended attribute for a non-GEOS file.
ERROR_ATTR_SIZE_MISMATCH: The buffer passed was the wrong size for the attribute specified.
ERROR_ACCESS_DENIED: FileSetHandleExtAttributes() returns this if the caller does not have write-access to the file. FileSetPathExtAttributes() returns this if any geode (including the caller) has the file open with "deny-write" exclusive access, or if the file is not writable.
ERROR_CANNOT_BE_SET: The extended attribute cannot be changed. Such attributes as FEA_SIZE and FEA_NAME cannot be changed with the FileSet...() routines.

FEA_MULTIPLE

By passing this extended attribute, you can get or set several extended attributes at once. This is also the only way to get, set, or create a custom attribute. If you pass this, the other arguments are slightly different. The first argument is still the file specifier (handle or path), and the second argument is FEA_MULTIPLE. However, the third argument is the base address of an array of FileExtAttrDesc structures, and the fourth argument is the number of these structures in the array. The array has one element for each attribute you wish to get or set. Each FileExtAttrDesc structure has the following fields:

FEAD_attr: This is the numerical constant for the attribute to be read or set. If a custom attribute is being set, this should be FEA_CUSTOM.
FEAD_value: If the attribute is being set, this is the address of the new value. If the attribute is being read, this is the address of the buffer into which to copy the value.
FEAD_size: This is the size of the buffer or value pointed to by FEAD_value .
FEAD_name: If FEAD_attr is set to FEA_CUSTOM, this is the address of a null-terminated string containing the custom attribute's name. If FEAD_attr is set to anything else, this field is ignored.

FEA_CUSTOM

In addition to the system-defined extended attributes, any GEOS file may have any number of custom attributes. Each custom attribute is named by a null-terminated ASCII string. To create a custom attribute, call one of the FileSet...() routines, specifying the new attribute with a FileExtAttrDesc structure (as described immediately above). If you try to read a custom attribute which has not been defined for that file, the routine will fail with error condition ERROR_ATTR_NOT_FOUND.

Note that not all file systems support the use of custom extended attributes; therefore, you should write your applications so they can perform correctly without using them.

FEA_MODIFICATION

Every file has a "last modified" time. This is automatically updated whenever the file is written to. To find the modification time of a file, get the extended attribute FEA_MODIFICATION. The modification time is returned as a 32-bit FileDateAndTime value. The value has the following fields, each of which is small enough to fit in a signed-byte variable:

FDAT_YEAR: This field records the year, counting from a base year of 1980. (The constant FDAT_BASE_YEAR is defined as 1980.) This field is at an offset of FDAT_YEAR_OFFSET bits from the low end of the value.
FDAT_MONTH: This field records the month as an integer, with January being one. It is located at an offset of FDAT_MONTH_OFFSET.
FDAT_DAY: This field records the day of the month. It is located at an offset of FDAT_DAY_OFFSET.
FDAT_HOUR: This field records the hour on a 24-hour clock, with zero being the hour after midnight. It is located at an offset of FDAT_HOUR_OFFSET.
FDAT_MINUTE: This field records the minute. It is located at an offset of FDAT_MINUTE_OFFSET.
FDAT_2SECOND: This field records the second, divided by two; that is, a field value of 15 indicates the 30th second. (It is represented this way to let the second fit into 5 bits, thus letting the entire value fit into 32 bits.) It is located at an offset of FDAT_2SECOND_OFFSET.

The macros FDATExtractYear() , ...Month() , ...Day() , ...Hour() , ...Minute() , and ...2Second() all extract the specified field from a FileDateAndTime value. The macro FDATExtractSecond() extracts the FDAT_2SECOND field and doubles it before returning it. The FDATExtractYearAD() extracts the year field and adds the base year, thus producing a word-sized year value.

FEA_FILE_ATTR

There are certain attributes which all files have. These attributes specify such things as whether the file is hidden, whether it is read-only, and several other things. To get these attributes, call an extended attribute routine with argument FEA_FILE_ATTRIBUTES. The attributes are passed or returned in a FileAttrs record. This record has the following fields:

FA_ARCHIVE: This flag is set if the file requires backup. Backup programs typically clear this flag.
FA_SUBDIR: This flag is set if the "file" is actually a directory. Geodes may not change this flag.
FA_VOLUME: This flag is set if the "file" is actually the volume label. This flag will be off for all files a geode will ever see. Geodes may not change this flag.
FA_SYSTEM: This flag is set if the file is a system file. Geodes should not change this flag.
FA_HIDDEN: This flag is set if the file is hidden from normal directory searches. For example, a GenFileSelector, by default, does not list files that have this flag set.
FA_RDONLY: This flag is set if the file is read-only.

Many file systems (including DOS) require that files be closed when you set these attributes. For that reason, you cannot change these attributes with FileSetHandleExtAttributes() . You must use either FileSetPathExtAttributes() or FileSetAttributes() (described below in Getting and Setting Information about a Byte File ). If you try to set this field with FileSetHandleExtAttributes() , you will be returned ERROR_ATTR_CANNOT_BE_SET.

FEA_SIZE

This attribute is simply the size of the file in bytes. It is dword-sized (allowing for files as large as 4096 megabytes). The attribute can be read, but not directly changed.

FEA_FILE_TYPE

This attribute is a member of the GeosFileType enumerated type and should not be altered. The type has the following values:

GFT_NOT_GEOS_FILE: The file is not a GEOS file. This constant is guaranteed to be equal to zero.
GFT_EXECUTABLE: The file is executable; in other words, it is some kind of geode.
GFT_VM: The file is a VM file.
GFT_DATA: The file is a GEOS byte file (see below).
GFT_DIRECTORY: The file is a GEOS directory.
GFT_LINK: The file is a symbolic link (not yet implemented).

FEA_FLAGS

This attribute is a word-sized flag field, named GeosFileHeaderFlags . The following flags are implemented:

GFHF_TEMPLATE: The file is a document template.
GFHF_SHARED_SINGLE: The file can be opened for shared-single access.
GFHF_SHARED_MULTIPLE: The file can be opened for shared-multiple access.

Shared-single and shared-multiple access are described in the VM chapter. For more details, see the VM chapter.

FEA_RELEASE

This attribute is a ReleaseNumber structure. Generally, only geodes have release numbers. The structure has the following fields:

RN_major: The file's major release number. An increase in the major release number generally indicates a change which is not downward-compatible.
RN_minor: The file's minor release number. An increase in the minor release number generally indicates that the new version is compatible with previous versions.
RN_change: A field for use by individual manufacturers.
RN_engineering: A field for use by individual manufacturers.

FEA_PROTOCOL

This attribute contains the file's protocol numbers. A ProtocolNumber structure is returned. For a discussion of file protocols, see the Document Objects chapter.

FEA_TOKEN

This attribute is the file's token. It consists of a GeodeToken structure. For more information about tokens, see the Applications and Geodes chapter.

FEA_CREATOR

This attribute is the token of the document's creator. It consists of a GeodeToken structure. For more information about tokens, see the Applications and Geodes chapter.

FEA_USER_NOTES

This attribute is a null-terminated string. It is displayed in the file's "Info" box. Users can edit this string with GeoManager.

FEA_NOTICE

This attribute contains the file's copyright notice.

FEA_CREATION

This attribute is a FileDateAndTime structure. It contains the time when the file was created.

FEA_PASSWORD

This attribute contains the file's encrypted password, if any.

FEA_NAME

This attribute contains the file's virtual name. It is a null-terminated character string.

FEA_GEODE_ATTR

This attribute contains information about the geode. If the file is not a geode, this field's value will be zero. If it is a geode, it will contain a record of GeodeAttrs . This record has the following fields:

GA_PROCESS: This geode has a process thread.
GA_LIBRARY: This geode is a library.
GA_DRIVER: This geode is a driver.
GA_KEEP_FILE_OPEN: The GEOS kernel keeps this file open while GEOS is running.
GA_SYSTEM: This file is part of the kernel.
GA_MULTI_LAUNCHABLE: This geode can be loaded more than once simultaneously.
GA_DRIVER_INITIALIZED: The geode is a driver which has been opened, loaded and initialized.
GA_LIBRARY_INITIALIZED: The geode is a library which has been opened and loaded, and whose entry point has been called.
GA_GEODE_INITIALIZED: The geode has been opened and completely initialized.
GA_USES_COPROC: The geode uses a math coprocessor, if one is available.
GA_REQUIRES_COPROC: The geode can only run if a math coprocessor or emulator is present.
GA_HAS_GENERAL_CONSUMER_MODE: The geode is an application which can be run in GCM mode.
GA_HAS_ENTRY_POINTS_IN_C: This geode is a library or driver which can be called from C code.

FEA_PATH_INFO

This field contains information about the file's path. It is for internal use by the kernel.

FEA_FILE_ID

This field is for internal use by the kernel.

FEA_DESKTOP_INFO

This field is for use by the desktop manager.

FEA_DRIVE_STATUS

This attribute contains the DriveExtendedStatus word for the drive containing the file. The DriveExtendedStatus value is described in Accessing Drives .

GEOS SDK TechDocs |

5.2 Files and File Handles | Next:

5.4 File Utilities