Topic Path: Symbol Reference > Classes > TIdMLSTFTPListItem Class > TIdMLSTFTPListItem Properties > Facts Property
ContentsIndexHome
PreviousUpNext
TIdMLSTFTPListItem.Facts Property

Represents keyword-value pairs from an FTP MLST or MLSD response.

property Facts [const Name: string]: string;

Facts is an indexed read-only string property that represents keyword-value pairs returned in file or directory listings for the FTP MLST or MLSD commands. The indexer for the property is a string that represents the keyword desired, and the the property returns the fact value for the specified keyword. 

The following keywords are allowed as indexer values for the Facts property: 

 

Keyword 
Meaning 
size 
Size in octets. 
modify 
Last modification time. 
Creation time. 
type 
Entry type. 
unique 
Unique id of file/directory. 
perm 
File permissions, whether read, write, execute is allowed for the login id. 
lang 
Language of the file name per IANA[12] registry. 
media-type 
MIME media-type of file contents per IANA registry. 
charset 
Character set per IANA registry (if not UTF-8) 

 

Fact name keywords are not case sensitive; using the value 'Size', 'size', 'SIZE', and 'SiZe' will return same fact. 

Additional operating system specific keywords could be specified by using the IANA operating system name as a prefix (examples only): 

 

Keyword 
Meaning 
OS/2.ea 
OS/2 extended attributes 
MACOS.rf 
MacIntosh resource forks 
UNIX.mode 
Unix file modes (permissions) 

 

FTP server implementations may define keywords for experimental, or private use. All such keywords begin with the two character sequence "x.". As type names are case independent, "x." and "X." are equivalent. For example: 

 

Keyword 
Meaning 
x.ver 
Version information 
x.desc 
File description 
x.type 
File type 

 

Fact keyword-value pairs are not guaranteed to be present for all files and directories returned in a listing response. Some facts are not applicable for certain resource types, or may not be provided by the FTP server implementation. 

 

The type Fact

 

The type fact indicates is the directory listing collection item represents a file or a directory. If it is a directory, is it the current directory, a regular directory, or a parent directory? The MLST specification makes this unambiguous using the type fact. 

The type fact specifies information about the object listed in the MLST/MLSD response, and may contain one of the following values: 

 

Value 
Meaning 
file 
A file entry for a file containing data that is not host- or system-specific. 
cdir 
The path name for the current listed directory (Returned only in MLSD responses). In a sense, it can be viewed as representing the title of the listing, in a machine friendly format. 
pdir 
The path name for a parent directory (Returned only in MLSD responses). 
dir 
A name of a directory or sub-directory. It generally cannot be transferred from machine to machine, but can be used as a target for the MLSD command. 
OS.name=type 
An OS or file system dependent file type. Name is any IANA registered operating system name, like UNIX. the type portion provides system dependent information as to the type of the file listed. 

 

The unique Fact

 

The unique fact is used to present a unique identifier for a file or directory in the NVFS (Network Virtual File System) accessed via a server-FTP process. The value of this fact should be the same for any number of pathnames that refer to the same underlying file. The fact should have different values for names which reference distinct files. The mapping between files, and unique fact tokens should be maintained, and remain consistent, for at least the lifetime of the control connection from user-PI to server-PI. 

This fact would normally be used by Server-FTPs whose host system allows things such as symbolic links so that the same file may be represented in more than one directory on the server. The only conclusion that should be drawn is that if two different names each have the same value for the unique fact, they refer to the same underlying object. The value of the unique fact (the token) should be considered an opaque string for comparison purposes, and is a case dependent value. The tokens "A" and "a" do not represent the same underlying object. 

 

The modify Fact

 

The modify fact is used to determine the last time the content of the file (or directory) indicated was modified. Any change of substance to the file should cause this value to alter. That is, if a change is made to a file such that the results of a RETR command would differ, then the value of the modify fact should alter. User-PIs should not assume that a different modify fact value indicates that the file contents are necessarily different than when last retrieved. Some systems may alter the value of the modify fact for other reasons, though this is discouraged wherever possible. Also a file may alter, and then be returned to its previous content, which would often be indicated as two incremental alterations to the value of the modify fact. 

For directories, this value should alter whenever a change occurs to the directory such that different file names would (or might) be included in MLSD output of that directory. 

 

The create Fact

 

The create fact indicates when a file, or directory, was first created. The exact content of the create fact is not specified and may vary from server to server. About all that can be said about the value returned is that it can never indicate a later time than the modify fact. 

 

The perm Fact

 

The perm fact is used to indicate access rights the current FTP user has for the object listed. Of the permission indicators currently defined, many are meaningful only when used with a particular type of object. The indicators are case independent, "d" and "D" are the same indicator. The perm value is always an unordered sequence of alphabetic characters, including: 

 

Value 
Meaning 
"a" 
Applies to file object types, and indicates that the APPE (append) command may be applied to the file named. 
"c" 
Applies to directory object types (dir, cdir, pdir), and indicates that may be created in the directory named using the STOR, STOU, APPE, and RNTO commands. 
"d" 
Applies to all object types, and indicates that the named object may be deleted using the DELE or RMD commands (as appropriate). 
"e" 
Applies to directory object types (dir, cdir, pdir), and indicates that the path for the directory named can be entered using navigational commands like CWD and CDUP. 
"f" 
Applies to objects that may be renamed, and indicates if can be renamed using the RNFR and RNTO commands. 
"l" 
Applies to directory object types, and indicates that the listing commands LIST, NLST, and MLSD may be applied to the directory named. 
"m" 
Applies to directory object types, and indicates that the new sub-directories can be made using the MKD command for the directory named. 
"p" 
Applies to directory object types, and indicates that objects in the directory may be purged by the file system on the remote FTP server. Please note that it does not indicate that the RMD command may be used to remove the directory named itself; the "d" permission indicator indicates that. 
"r" 
Applies to file objects types, and for some systems may apply to other types of objects, and indicates that the object named can be retrieved using the RETR command. 
"w" 
Applies to file objects types, and for some systems may apply to other types of objects, and indicates that the object named can be written using the STOR command. 

 

Please note that a permission indicator can never imply that the appropriate command is guaranteed to work; just that it might. Other system specific limitations, such as limitations on available space for storing files, may cause an operation to fail, where the permission flags may have indicated that it was likely to succeed. The permissions are a guide only. 

Please note that te permissions are described here as they apply to FTP commands. They may not map easily into particular permissions available on the server's operating system. Servers are expected to synthesize these permission bits from the permission information available from operating system. For example, to correctly determine whether the "D" permission bit should be set on a directory for a server running on the UNIX(TM) operating system, the server should check that the directory named is empty, and that the user has write permission on both the directory under consideration, and its parent directory. 

Some systems may have more specific permissions than those listed here, such systems should map those to the flags defined as best they are able. Other systems may have only more broad access controls. They will generally have just a few possible permutations of permission flags, however they should attempt to correctly represent what is permitted. 

 

The lang Fact

 

The lang fact describes the natural language of the file or directory name for use in displaying the listing to the end user. Values used in the lang fact should be taken from the language registry of the IANA

Server-FTP implementations must not guess language values. Language values must be determined in an unambiguous way such as file system tagging of language or by user configuration. Note that the lang fact provides no information at all about the content of a file, only about the encoding of its name. 

 

The size Fact

 

The size fact applies to non-directory file types and should always reflect the approximate size of the file. This should be as accurate as the server can make it, without going to extraordinary lengths, such as reading the entire file. The size is expressed in units of octets of data in the file. 

Given limitations in some systems, Client-FTP implementations must understand this size may not be precise and may change between the time of a MLST and RETR operation. 

Clients that need highly accurate size information for some particular reason should use the SIZE command. The most common need for this accuracy is likely to be in conjunction with the REST command. The size fact, on the other hand, should be used for purposes such as indicating to a human user the approximate size of the file to be transferred, and perhaps to give an idea of expected transfer completion time. 

 

The media-type Fact

 

The media-type fact represents the IANA media type of the file named, and applies only to non-directory types. The list of values used must follow the guidelines set by the IANA registry. 

Server-FTP implementations must not guess media type values. Media type values must be determined in an unambiguous way such as file system tagging of media-type or by user configuration. This fact gives information about the content of the file named. Both the primary media type, and any appropriate subtype should be given, separated by a slash "/" as is traditional. 

 

The charset Fact

 

The charset fact provides the IANA character set name, or alias, for the encoded pathnames in a MLST or MLSD response. The default character set is UTF-8 unless specified otherwise. FTP implementations should use UTF-8 if possible to encourage maximum inter-operability. The value of this fact applies to the pathname only, and provides no information about the contents of the file. 

 

Required facts

 

Servers are not required to support any particular set of the available facts. However, servers should, if conceivably possible, support at least the type, perm, size, unique, and modify facts. 

 

System Dependent and Local Facts

 

By using an system dependent fact, or a local fact, a server may communicate to the user information about the file named which is peculiar to the underlying file system. 

 

System Dependent Facts

 

System dependent fact names are labeled by prefixing a label identifying the specific information returned by the name of the appropriate operating system from the IANA maintained list of operating system names. 

The value of an OS dependent fact may be whatever is appropriate to convey the information available. In order to allow reliable inter-operation between users of system dependent facts, the IANA will maintain a registry of system dependent fact names, their syntax, and the interpretation to be given to their values. 

 

Local Facts

 

Server implementations may also make available other facts of their own choosing. As the method of interpretation of such information will generally not be widely understood, servers should be aware that clients will typically ignore any local facts provided. As there is no registration of locally defined facts, it is entirely possible that different servers will use the same local fact name to provide vastly different information. Hence users should be hesitant about making any use of any information in a locally defined fact without some other specific assurance that the particular fact is one that they do comprehend. 

Local fact names all begin with the sequence "X.". The rest of the name is a "token". The value of a local fact can be anything at all, provided it can be encoded as a token.

Copyright 1993-2006, Chad Z. Hower (aka Kudzu) and the Indy Pit Crew. All rights reserved.
Post feedback to the Indy Docs Newsgroup.