Wrapped API of FtpLib

 

Version 1.0.03

 

Version

Date

Change Log

V1.0.00

2008/12/01

Document created

V1.0.01

2009/05/26

Non-Blocking Connection

V1.0.02

2009/06/04

Add non-blocking connecting function by mingyoung based on Anne sample.

V1.0.03

2010/07/09

Update the FTP library for making several levels of directories

 

Description

This document introduces the wrapped APIs which support a friendly interface of FTP Client. These APIs are designed and implemented base on FtpLib code base. This document provides an example and a figure of Calls Flow for user to understand how to use these APIs.

 

 

Application InterFace

FtpConnect

        Connect & Login to an FTP server.

<SYNOPSIS>

#include <ftplib.h>

int FtpConnect(const FtpContent *pCnt, ControlInfo **pCtrl);

<PARAMETERS>

        pCnt

A pointer of FtpContent structure which contains hostname, username, password, port and connection mode. User must fill struct data before using.

typedef struct FtpContent {

     char host[64];

     char user[32];

     char pass[32];

     unsigned int port;

     int mode;

     int timer;

}FtpContent;

l   pCnt->host: The name/IP address of the remote host machine.

l   pCnt->user: Specifies the username.

l   pCnt->pass: Specifies the password.

l   pCnt->port: An endpoint of communication on a host. The default is 21.

l   pCnt->mode: Connection Mode (FTPLIB_PASSIVE or FTPLIB_ACTIVE)

If you want to try passive FTP, you can use FTPLIB_PASSIVE. On the contrary, you can use FTPLIB_ACTIVE to try active FTP.

l   pCnt->timer: is an upper bound on the amount of time elapsed before FtpConnect returns. The unit of timeout is msec.

If it is larger than zero, FtpConnect() will be non-blocking connection function. It will try to connect to the server till to timeout.

If it is equal to zero, FtpConnect() will block indefinitely.

pCtrl

A pointer of a control handle structure which contains FtpCallBack, cmode, idletime, data, response, etc. FtpConnect() will allocate a memory for this structure and fill it before returning. Other functions, which need pCtrl handle, have to be executed after using FtpConnect() for taking the newly created control handle structure.

<DESCRIPTION>

FtpConnect() establishes a connection to the FTP server, and login to the server with the supplied username and password. After connecting successfully, it returns a handle for control ling connection.

<RETURN VALUE>

FTP_SUCCESS -- If the connection was established and the login succeeded

FTP_FAIL -- Failure

 

FtpDisconnect

        Close the connection to server.

<SYNOPSIS>

#include <ftplib.h>

void FtpDisconnect(ControlInfo *pCtrl);

<PARAMETERS>

pCtrl

A handle returned by FtpConnect().

<DESCRIPTION>

FtpDisconnect() closes the connection of the remote server and frees any resources associated with the connection.

<RETURN VALUE>

None

 

FtpNewDir

        Create a new directory on the remote server and support the multiple level directories build-up.

<SYNOPSIS>

#include <ftplib.h>

int FtpNewDir(const char *cpFolderName, ControlInfo *pCtrl);

<PARAMETERS>

cpFolderName

A character pointer to a new directory name string which contains the path (path/folder). The path will be created if it doesn’t exist.

pCtrl

A handle returned by FtpConnect().

<DESCRIPTION>

FtpNewDir() creates a new directory at the remote server by using the connection control handle returned by FtpConnect(). Thus, it works if only if the FTP connection was established.
        FtpNewDir supports the multiple level directories build-up. It parsers the levels of the directory from the cpFolderName. If the folder does not exist, it should create it.

<RETURN VALUE>

FTP_SUCCESS -- Successfully

FTP_FAIL -- Failure

       

FtpOpen

        Set up data connection to the remote server.

<SYNOPSIS>

#include <ftplib.h>

int FtpOpen(const char *cpDestFileName, ControlInfo *pCtrl, DataInfo **pData)

<PARAMETERS>

cpDestFileName

A character pointer to a new file name string which will be created on destination. The file will be created at the new directory which created by using FtpNewDir().

pCtrl

A handle returned by FtpConnect().

        pData

                     A pointer of a newly created control handle for data transfer.

<DESCRIPTION>

FtpOpen() sets up data connection to the remote server. After setting successfully, the folder/file named in cpDestFileName will be created and FtpOpen() will return a handle which can be used to initiate data transfers .

<RETURN VALUE>

FTP_SUCCESS -- Successfully

FTP_FAIL -- Failure

 

FtpClose

        Close a data connection.

<SYNOPSIS>

#include <ftplib.h>

int FtpClose(DataInfo *pData)

<PARAMETERS>

        pData

                     A handle returned by FtpOpen().

<DESCRIPTION>

FtpClose() closes the data connection from the remote server.

<RETURN VALUE>

FTP_SUCCESS -- Successfully

FTP_FAIL -- Failure

 

FtpPutDataFromMem

Send data from memory address to remote server.

<SYNOPSIS>

#include <ftplib.h>

int FtpPutDataFromMem(char *pMemAddr, size_t nSize, DataInfo *pData);

<PARAMETERS>

pMemAddr

A pointer to a memory address.

nSize

The data size which you want to transfer to the remote server. The unit of size is byte.

        pData

                     A handle returned by FtpOpen().

<DESCRIPTION>

FtpPutDataFromMem() issues a PUT command and sends memory data to remote server. The destination for transfer data is set by FtpOpen() with parameter cpDestFileName.

<RETURN VALUE>

FTP_FAIL -- Failure

Otherwise -- returns the number of bytes written to the file

 

 

Calls Flow

call flow.bmp

 

 

Example

 

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#include "ftplib.h"

 

static ControlInfo *pCtrl = NULL;

char strarr[10]={"Hello!"};

 

int main()

{

    FtpContent sCnt;

    DataInfo *pData;

        int count = 5;

        int nBytes;

 

    strcpy(sCnt.host, "172.16.3.19");

    strcpy(sCnt.user, "ftpuser");

    strcpy(sCnt.pass, "123456");

    sCnt.port = 203;

    sCnt.mode = FTPLIB_PASSIVE; // FTPLIB_PASSIVE or FTPLIB_ACTIVE

    sCnt.timer = 10000; //mSec

 

    if(FTPLIB_ACTIVE == sCnt.mode)

        printf("active mode\n");

    else if (FTPLIB_PASSIVE == sCnt.mode)

        printf("passive mode\n");

 

    //Connect

    if (FTP_FAIL == FtpConnect(&sCnt, &pCtrl))

    return 0;

 

//New Dir

if (FTP_SUCCESS == FtpNewDir("Folder1/Folder2/Folder3", pCtrl))

    printf("mkdir Folder1/Folder2/Folder3\n", );

else

    printf("Unable to mkdir\n");

 

//Open

if (FTP_SUCCESS == FtpOpen("hello", pCtrl, &pData))

    printf("Open Successfully\n");

else

    printf("Open failure");

 

while(0 < count)

{

        nBytes = FtpPutDataFromMem(strarr, sizeof(strarr), pData);

    if (FTP_FAIL == nBytes)

        printf("Unable to send files from Mem\n");

    else

        printf("Send %d bytes From Mem\n", nBytes);

 

    sleep(1);

    printf("count: %d\n", count);

    count--;

}

 

//Close

if(FTP_SUCCESS == FtpClose(pData))

    printf("Close\n");

else

    printf("Close failure\n");

 

//Disconnect

FtpDisconnect(pCtrl);

printf("Disconnect!\n");

 

return 0;

}

 

 

Reference: http://nbpfaus.net/~pfau/ftplib/ftplib.html