| |
Read a directory entry from an FTP server.
Syntax
object.ReadDirectory(FileName,
[FileLength], [FileDate], [FileOwner],
[FileGroup], [FilePerms], [IsDirectory])
Parameters
- FileName
- A string value that specifies the name of the file that status
information will be returned for.
- FileLength
- An integer value that will specify the size of the file on the
server when the method returns. This parameter must be passed
by reference. Note that if this is a text file, the file size may be
different on the server than it is on the local system. This is
because different operating systems use different conventions that
indicate the end of a line and/or the end of the file. On Windows
platforms, directories have a file size of zero bytes.
- FileDate
- A string value that will specify the date and time the file was
created or last modified on the server. This parameter must be
passed by reference. The date format that is returned is expressed
in local time (in other words, the timezone of the server is
not taken into account) and depends on both the local host settings
via the Control Panel and the format of the date and time
information returned by the server
- FileOwner
- A string value that will specify the owner of the file on the
server. This parameter must be passed by reference. On some
platforms, this information may not be available for security
reasons if an anonymous login session was specified
- FileGroup
- A string value that will specify the group that the file owner
belongs to. This parameter must be passed by reference. On some
platforms, this information may not be available for security
reasons if an anonymous login session was specified
- FilePerms
- An integer value that will specify the permissions assigned to
the file. This parameter must be passed by reference. This value is
actually a combination of bits that specify the individual
permissions for the file owner, group and world (all other users).
For those familiar with UNIX, the file permissions are the same as
those used by the chmod command. The permissions are as follows:
| Value |
Description |
| ftpPermWorldExecute |
All users have permission to execute the contents of the
file. If this permission is set for a directory, this may also
grant all users the right to open that directory and search for
files in that directory. |
| ftpPermWorldWrite |
All users have permission to open the file for writing. This
permission grants any user the right to replace the file. If this
permission is set for a directory, this grants any user the right
to create and delete files. |
| ftpPermWorldRead |
All users have permission to open the file for reading. This
permission grants any user the right to download the file to the
local system. |
| ftpPermGroupExecute |
Users in the specified group have permission to execute the
contents of the file. If this permission is set for a directory,
this may also grant the user the right to open that directory and
search for files in that directory. |
| ftpPermGroupWrite |
Users in the specified group have permission to open the file
for writing. On some platforms, this may also imply permission to
delete the file. If the current user is in the same group as the
file owner, this grants the user the right to replace the file.
If this permission is set for a directory, this grants the user
the right to create and delete files. |
| ftpPermGroupRead |
Users in the specified group have permission to open the file
for reading. If the current user is in the same group as the file
owner, this grants the user the right to download the file. |
| ftpPermOwnerExecute |
The owner has permission to execute the contents of the file.
The file is typically either a binary executable, script or batch
file. If this permission is set for a directory, this may also
grant the user the right to open that directory and search for
files in that directory. |
| ftpPermOwnerWrite |
The owner has permission to open the file for writing. If the
current user is the owner of the file, this grants the user the
right to replace the file. If this permission is set for a
directory, this grants the user the right to create and delete
files. |
| ftpPermOwnerRead |
The owner has permission to open the file for reading. If the
current user is the owner of the file, this grants the user the
right to download the file to the local system. |
| ftpPermSymbolicLink |
The file is a symbolic link to another file. Symbolic links
are special types of files found on UNIX based systems which are
similar to Windows shortcuts. |
- IsDirectory
- A boolean value that will specify if the file is a directory or
a regular file. This parameter must be passed by reference.
Return Value
A value of zero is returned if the method succeeds. Otherwise,
a non-zero error code is returned which indicates the cause of the
failure.
Remarks
The ReadDirectory method reads the next entry from the
directory listing. This method can only be used after the
OpenDirectory method has been called to begin the transfer of
file information to the client. All parameters of
ReadDirectory are output parameters. The first parameter,
FileName, is required, and all other are optional. If the
ParseList parameter of the OpenDirectory method was
missing, or was explicitly set to True, then the output parameters
that are present will have the meanings described below. If the
ParseList parameter of the OpenDirectory method was
False, then the FileName parameter will contain all file
information, exactly as provided by the server, without
interpretation.
For the proprietary Sterling directory formats, the "status code"
is returned in the FilePerms argument. This value is a
combination of bits. Bits 0-25 correspond to letters of the alphabet,
most of which have distinct meanings in the Sterling formats.
| Letter code |
Bit position |
Hexadecimal value |
| A |
1h |
| B |
2h |
| C |
4h |
| n-th letter of alphabet |
n-1 |
2 to the (n-1) power |
| Z |
2000000h |
For the proprietary Sterling directory formats, bits 26-31
represent the transfer protocol associated with the file:
| Protocol |
Bit position |
Hexadecimal value |
Value |
| TCP |
4000000h |
ftpSterlingStatusTcp |
| FTP |
8000000h |
ftpSterlingStatusFtp |
| BSC |
10000000h |
ftpSterlingStatusBsc |
| ASC |
20000000h |
ftpSterlingStatusAsc |
| FTS |
40000000h |
ftpSterlingStatusFts |
| other |
80000000h |
ftpSterlingStatusOther |
Certain error codes should be treated as normal
terminations of a directory listing. If the OpenDirectory
method was called with the ParseList parameter specified as
True, or if the ParseList parameter is omitted, then
ReadDirectory will return the error
fileErrorEndOfDirectory when the end of the directory listing
is reached. If the OpenDirectory method was called with the
ParseList parameter specified as False, then the
ReadDirectory method will return the error
fileErrorEndOfData when there are no more filenames to
return.
You must call the CloseDirectory method after the
list of files has been returned by the server. Failure to do so will
result in an error when you attempt to transfer a file because the
data channel to the server has been left open. For this same reason,
you cannot call the GetFile or PutFile methods while
reading the contents of a directory on the server.
Example
Example 1:
'
' Display full file listing for specified directory
'
nError = FileTransfer1.OpenDirectory(strDirName)
If nError > 0 Then
MsgBox "OpenDirectory error: " & nError
Exit Sub
End If
Do
nError = FileTransfer1.ReadDirectory(strFileName, _
dwFileLength, strFileDate, _
strFileOwner, strFileGroup, _
dwFilePerms, bIsDirectory)
If nError > 0 Then
If nError <> fileErrorEndOfDirectory Then
MsgBox "ReadDirectory error: " & nError
End If
Exit Do
End If
'
' See GetFileStatus help topic for FilePerms function
'
strPerms = FilePerms(dwFilePerms, bIsDirectory)
txtFileStatus.Text = txtFileStatus.Text & _
strFileName & " " & dwFileLength & " " & strFileDate & " " & _
strFileOwner & " " & strFileGroup & " " & strPerms & vbCrLf
Loop
FileTransfer1.CloseDirectory
Example 2:
'
' Display file names and dates for specified directory
'
nError = FileTransfer1.OpenDirectory(strDirName)
If nError > 0 Then
MsgBox "OpenDirectory error: " & nError
Exit Sub
End If
Do
nError = FileTransfer1.ReadDirectory(strFileName, , strFileDate)
If nError > 0 Then
If nError <> fileErrorEndOfDirectory Then
MsgBox "ReadDirectory error: " & nError
End If
Exit Do
End If
txtFileStatus.Text = txtFileStatus.Text & _
strFileName & " " & strFileDate & vbCrLf
Loop
FileTransfer1.CloseDirectory
Example 3:
'
' Display unparsed file listing for specified directory
'
nError = FileTransfer1.OpenDirectory(strDirName, False)
If nError > 0 Then
MsgBox "OpenDirectory error: " & nError
Exit Sub
End If
Do
nError = FileTransfer1.ReadDirectory(strFileDescription)
If nError > 0 Then
If nError <> fileErrorEndOfData Then
MsgBox "ReadDirectory error: " & nError
End If
Exit Do
End If
txtFileStatus.Text = txtFileStatus.Text & strFileDescription & vbCrLf
Loop
FileTransfer1.CloseDirectory
See Also
GetFileStatus Method,
CloseDirectory Method,
OpenDirectory Method
|
|