ReadDirectory Method

Read a directory entry from an FTP server.

Syntax

object.ReadDirectory(FileName [,FileLength] [,FileDate] [,FileOwner] [,FileGroup] [,FilePerms] [,IsDirectory])

The object placeholder represents an expression that evaluates to a FileTransfer object.

Return Type

Integer

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.

The FileName argument specifies the name of the file that status information is to be returned on.

The FileLength argument specifies the size of the file on the remote host. Note that if this is a text file, the file size may be different on the remote host 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 MS-DOS and Windows platforms, directories have a file size of zero bytes.

The FileDate argument specifies the date and time the file was created or last modified on the remote host. The date format that is returned is expressed in local time (in other words, the timezone of the remote 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 remote host.

The FileOwner argument specifies the owner of the file on the remote host. On some platforms, this information may not be available for security reasons if an anonymous login session was specified. For the proprietary Sterling directory formats, the "mailbox" is returned in this argument.

The FileGroup argument specifies the group that the file owner belongs to. On some platforms, this information may not be available for security reasons if an anonymous login session was specified. For the proprietary Sterling directory formats, the "batch number" is returned in this argument, with the character # preprended for the format fileDirectorySterling2.

The FilePerms argument specifies the permissions assigned to the file. 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 Constant Description
1 filePermWorldExecute 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.
2 filePermWorldWrite 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.
4 filePermWorldRead 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.
8 filePermGroupExecute 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.
16 filePermGroupWrite 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.
32 filePermGroupRead 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.
64 filePermOwnerExecute 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.
128 filePermOwnerWrite 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.
256 filePermOwnerRead 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.
4096 filePermSymbolicLink 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.

See the example in the GetFileStatus method topic for a function that produces a UNIX-style representation of the file permissions.

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 0 1h
B 1 2h
C 2 4h
n-th letter of alphabet n-1 2 to the (n-1) power
Z 25 2000000h

For the proprietary Sterling directory formats, bits 26-31 represent the transfer protocol associated with the file:

Protocol Bit position Hexadecimal value Constant
TCP 26 4000000h fileSterlingStatusTcp
FTP 27 8000000h fileSterlingStatusFtp
BSC 28 10000000h fileSterlingStatusBsc
ASC 29 20000000h fileSterlingStatusAsc
FTS 30 40000000h fileSterlingStatusFts
other 31 80000000h fileSterlingStatusOther

The IsDirectory argument specifies if the file is a directory or regular file.

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

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

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

Examples

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

Copyright © 2008 Catalyst Development Corporation. All rights reserved.