FTP API Reference

This section provides comprehensive documentation for the File Transfer Protocol (FTP) Application Programming Interfaces (APIs) available on Windows. These APIs allow developers to integrate FTP functionality into their applications, enabling file uploads, downloads, directory listings, and other standard FTP operations.

Core FTP Functions

These functions are the building blocks for interacting with FTP servers. They handle the low-level communication and command execution.

Uploading Files

FtpPutFile: Uploads a local file to an FTP server.
FtpPutPartialFile: Uploads a portion of a local file to an FTP server.

Downloading Files

FtpGetFile: Downloads a file from an FTP server to a local path.
FtpGetPartialFile: Downloads a portion of a file from an FTP server.

Directory Operations

FtpCreateDirectory: Creates a new directory on the FTP server.
FtpRemoveDirectory: Deletes a directory on the FTP server.
FtpFindFirstFile: Begins searching for files and directories in a specified directory on the FTP server.
FtpFindNextFile: Continues searching for files and directories.
FtpFindClose: Closes the directory search handle.

Connection Management

FtpConnect: Establishes a connection to an FTP server.
FtpDisconnect: Disconnects from an FTP server.
FtpSetCurrentDirectory: Sets the current working directory on the FTP server.
FtpGetCurrentDirectory: Retrieves the current working directory on the FTP server.

Data Transfer Modes

FTP supports different data transfer modes. The Windows FTP API allows you to specify these modes:

ASCII Mode: Used for transferring text files. Line ending translations may occur.
Binary Mode: Used for transferring non-text files (e.g., executables, images). Data is transferred byte-for-byte.

You can set the transfer mode using the FtpSetTransferType function.

Common Error Codes

Understanding common error codes is crucial for robust FTP application development. Here are a few:

Error Code	Description
`ERROR_INTERNET_CANNOT_CONNECT`	The FTP server could not be reached.
`ERROR_INTERNET_LOGIN_FAILURE`	Authentication failed (invalid username or password).
`ERROR_INTERNET_OPERATION_TIMED_OUT`	The operation timed out waiting for a response.
`ERROR_INTERNET_INVALID_URL`	The provided FTP URL is malformed.

Example Snippet: Uploading a File

Here's a simplified C++ example demonstrating how to upload a file using FtpPutFile:


#include <windows.h>
#include <wininet.h>
#include <iostream>

#pragma comment(lib, "wininet.lib")

int main() {
    HINTERNET hSession = InternetOpen(L"MyFTPSession", INTERNET_OPEN_TYPE_DIRECT, NULL, NULL, 0);
    if (!hSession) {
        std::cerr << "InternetOpen failed." << std::endl;
        return 1;
    }

    HINTERNET hFtpConnection = FtpConnect(hSession, L"ftp.example.com", INTERNET_INVALID_PORT, L"anonymous", L"user@example.com", FTP_TRANSFER_TYPE_BINARY, 0, 0);
    if (!hFtpConnection) {
        std::cerr << "FtpConnect failed." << std::endl;
        InternetCloseHandle(hSession);
        return 1;
    }

    const WCHAR* localFilePath = L"C:\\path\\to\\local\\file.txt";
    const WCHAR* remoteFileName = L"remote_file.txt";

    if (FtpPutFile(hFtpConnection, localFilePath, remoteFileName, FTP_TRANSFER_TYPE_BINARY, 0)) {
        std::cout << "File uploaded successfully." << std::endl;
    } else {
        std::cerr << "FtpPutFile failed." << std::endl;
    }

    FtpDisconnect(hFtpConnection);
    InternetCloseHandle(hSession);
    return 0;
}

For detailed function parameters, return values, and more advanced scenarios, please refer to the specific API documentation within the Windows SDK.