Topic Path: Symbol Reference > Classes > TIdFTP Class > TIdFTP Methods > ExtractFeatFacts Method
ContentsIndexHome
PreviousUpNext
TIdFTP.ExtractFeatFacts Method
procedure ExtractFeatFacts(
    const ACmd: String; 
    AResults: TIdStrings
);
Parameters 
Description 
ACmd 
 
AResults 
 

ExtractFeatFacts is a procedure used to capture the facts associated with the Feature negotiation mechanism for the File Transfer Protocol, as described in RFC 2389. The FTP FEAT command provides a mechanism for identifying new commands, or facilities. 

Implementations of the FTP protocol cannot be assumed to all immediately implement all newly defined mechanisms. The Capabilities property is used to store the responses received from an FTP FEAT command, and to identify the extended features available in the server. 

One of the negotiated features available includes information about the Trivial Virtual File Store which provides file system naming conventions modeled loosely upon those of the UNIX(TM) file system. That is, a tree structured file system, built of directories, each of which can contain other directories, or other kinds of files, or both. Each file and directory has a name relative to the directory that contains it, except for the directory at the root of the tree, which is contained in no other directory, and hence has no name of its own. 

In addition the MLST and MLSD commands were introduced to provide access to the values. The MLST and MLSD responses including the detailed data provided by TVFS are referred to as "facts". The "facts" for a file in a reply to a MLSx command consist of information about that file. The facts are a series of keyword=value pairs each followed by semi-colon (";") characters. An individual fact may not contain a semi-colon in its name or value. The complete series of facts may not contain the space character. 

The following represents the facts returned when the MLST command is issued for a directory containing the requested file. 

 

  C> PWD
  S> 257 "/tmp" is current directory.
  C> MLst cap60.pl198.tar.gz
  S> 250- Listing cap60.pl198.tar.gz
  S>  Type=file;Size=1024990;Perm=r; /tmp/cap60.pl198.tar.gz
  S> 250 End

 

The standard list of facts defined for the MLST and MLSD commands include the following names and associated meanings: 

 

Name 
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, or 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 names are case-insensitive. Size, size, SIZE, and SiZe are the same fact. 

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

 

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

 

Implementations may define keywords for experimental, or private use. All such keywords MUST begin with the two character sequence "x.". As type names are case independent, "x." and "X." are equivalent. 

 

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

 

The Type fact is of special interest due to its in representing either a file or a directory. If the fact is for 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 given specifies information about the object listed on the same line of the MLST response. 

Five values are possible for the Type fact: 

 

Value 
Meaning 
file 
a file entry 
cdir 
the current listed directory 
pdir 
path for the parent directory 
dir 
a directory or sub-directory in the current directory 
OS.name=type 
an OS or file system dependent file type 

 

Unique Fact

 

Another fact of interest is the unique fact used to present a unique identifier for a file or directory in the file system accessed via a server 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. 

This fact would be expected to be used by servers 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. 

 

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

 

Create Fact

 

The create fact indicates when a file, or directory, was first created. Exactly what "creation" is for this purpose is not specified here, 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. 

Implementors of this fact on UNIX(TM) systems should note that the unix "stat" "st_ctime" field does not give creation time, and that unix file systems do not record creation time at all. Unix (and POSIX) implementations will normally not include this fact. 

 

Perm Fact

 

The perm fact is used to indicate access rights the current FTP user has over the object listed. Its value is always an unordered sequence of up to ten alphabetic characters, like: 

 

Meaning 
Applies to objects of type=file, and indicates that the APPE (append) command may be applied to the named file. 
Applies to objects of type=dir (and type=pdir, type=cdir), and indicates that files may be created in the directory named using STOU, STOR, APPE, and RNTO. 
Applies to all object types, and indicates that the named object may be deleted using the DELE or RMD commands. 
Applies to the directory types, and indicates the user can enter the named directory using the CWD or CDUP commands. 
Indicates that the named object named may be renamed using the RNFR command. 
Applies to the directory file types, and indicates that the LIST, NLST, and MLSD commands can be used for the named directory. 
Applies to directory types, and indicates that the MKD command may be used to create a new directory in the named directory. 
Applies to directory types, and indicates that objects in the directory may be deleted or purged using the DELE command but not with the RMD command. 
Applies to object of type=file and indicates that the RETR command may be used to access the object. 
Applies to objects of type=file, and indicates that the STOR command may be applied to the named object. 

 

Many permissions are meaningful only when used with a particular type of object. The indicators are case independent, "d" and "D" are the same indicator. 

Please note that when a permission indicator is set, it does not imply that the appropriate command is guaranteed to work. 

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

 

Lang Fact

 

The lang fact describes the natural language of the file name for use in display purposes. Values used here should be taken from the language registry of the IANA. FTP server implementations must not guess at 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. 

 

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, FTP client 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. 

 

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. 

FTP server implementations must not guess at 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. 

 

Charset Fact

 

The charset fact provides the IANA character set name, or alias, for the encoded pathnames in a MLSx 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.

Missing parameter docs.

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