aftp_dir_open

The aftp_dir_open call begins a directory listing and specifies the file search parameters on the AFTP server. The aftp_dir_read call is used to read individual directory entries. The aftp_dir_close call is used to end the directory listing. A connection to the AFTP server must be established before using this call.

See AFTP File and Directory Concept for details on how the directory concept is handled for supported operating systems.

AFTP_ENTRY aftp_dir_open(
IN AFTP_HANDLE_TYPE connection_id,
IN unsigned char AFTP_PTR filespec,
IN AFTP_LENGTH_TYPE length,
IN AFTP_FILE_TYPE_TYPE file_type,
IN AFTP_INFO_LEVEL_TYPE info_level,
OUT unsigned char AFTP_PTR path,
IN AFTP_LENGTH_TYPE path_buffer_length,
OUT AFTP_LENGTH_TYPE AFTP_PTR path_returned_length,
OUT AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

connection_id

An AFTP connection object originally created with aftp_create.

filespec

The search string that the server uses to generate the directory listing. The files in the listing must match the search string. The format of this name can be either the native syntax on the AFTP server or the AFTP common naming convention described in the APPC Application Suite User's Guide. The file specified can be either an absolute or relative path name and can contain wildcard characters.

length

The length of the filespec parameter in bytes.

file_type

The type of information (directory names or file names) to be returned.

AFTP_FILE

Only file entries.

AFTP_DIRECTORY

Only directory entries.

AFTP_ALL_FILES

Both file and directory entries.

info_level

The level and format of information to be returned about each file or directory entry.

AFTP_NATIVE_NAMES

Native names without attributes.

AFTP_NATIVE_ATTRIBUTES

Native names and native file attributes.

path

The fully qualified directory name in which of all of the directory entries exist. The actual directory entries will be returned when the aftp_dir_read call is used. The path can be used along with the returned directory entry file name to create a fully qualified path name to use on another AFTP file call.

Use the AFTP_FILE_NAME_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

path_buffer_length

The size in bytes of the buffer pointed to by the path parameter.

path_returned_length

The number of bytes returned in the path parameter.

return_code

The return code issued for this function. See AFTP Return Codes for the list of possible return codes.

Example

See aftp_dir_read for a complete example showing the related calls aftp_dir_open, aftp_dir_read, and aftp_dir_close.

Line Flows

Sends a request for a directory listing to the AFTP server and waits for a response that includes the fully specified path of the directory listing or an error indicator. If the path of the directory listing is received, the AFTP server sends all of the directory entries as well. When the list is complete, a special end-of-list indicator is sent to the AFTP client.