Ftp

Enums

enum sfFtpTransferMode

Enumeration of transfer modes.

Values:

enumerator sfFtpBinary

Binary mode (file is transfered as a sequence of bytes)

enumerator sfFtpAscii

Text mode using ASCII encoding.

enumerator sfFtpEbcdic

Text mode using EBCDIC encoding.

enum sfFtpStatus

Status codes possibly returned by a FTP response.

Values:

enumerator sfFtpRestartMarkerReply

Restart marker reply.

enumerator sfFtpServiceReadySoon

Service ready in N minutes.

enumerator sfFtpDataConnectionAlreadyOpened

Data connection already opened, transfer starting.

enumerator sfFtpOpeningDataConnection

File status ok, about to open data connection.

enumerator sfFtpOk

Command ok.

enumerator sfFtpPointlessCommand

Command not implemented.

enumerator sfFtpSystemStatus

System status, or system help reply.

enumerator sfFtpDirectoryStatus

Directory status.

enumerator sfFtpFileStatus

File status.

enumerator sfFtpHelpMessage

Help message.

enumerator sfFtpSystemType

NAME system type, where NAME is an official system name from the list in the Assigned Numbers document.

enumerator sfFtpServiceReady

Service ready for new user.

enumerator sfFtpClosingConnection

Service closing control connection.

enumerator sfFtpDataConnectionOpened

Data connection open, no transfer in progress.

enumerator sfFtpClosingDataConnection

Closing data connection, requested file action successful.

enumerator sfFtpEnteringPassiveMode

Entering passive mode.

enumerator sfFtpLoggedIn

User logged in, proceed. Logged out if appropriate.

enumerator sfFtpFileActionOk

Requested file action ok.

enumerator sfFtpDirectoryOk

PATHNAME created.

enumerator sfFtpNeedPassword

User name ok, need password.

enumerator sfFtpNeedAccountToLogIn

Need account for login.

enumerator sfFtpNeedInformation

Requested file action pending further information.

enumerator sfFtpServiceUnavailable

Service not available, closing control connection.

enumerator sfFtpDataConnectionUnavailable

Can’t open data connection.

enumerator sfFtpTransferAborted

Connection closed, transfer aborted.

enumerator sfFtpFileActionAborted

Requested file action not taken.

enumerator sfFtpLocalError

Requested action aborted, local error in processing.

enumerator sfFtpInsufficientStorageSpace

Requested action not taken; insufficient storage space in system, file unavailable.

enumerator sfFtpCommandUnknown

Syntax error, command unrecognized.

enumerator sfFtpParametersUnknown

Syntax error in parameters or arguments.

enumerator sfFtpCommandNotImplemented

Command not implemented.

enumerator sfFtpBadCommandSequence

Bad sequence of commands.

enumerator sfFtpParameterNotImplemented

Command not implemented for that parameter.

enumerator sfFtpNotLoggedIn

Not logged in.

enumerator sfFtpNeedAccountToStore

Need account for storing files.

enumerator sfFtpFileUnavailable

Requested action not taken, file unavailable.

enumerator sfFtpPageTypeUnknown

Requested action aborted, page type unknown.

enumerator sfFtpNotEnoughMemory

Requested file action aborted, exceeded storage allocation.

enumerator sfFtpFilenameNotAllowed

Requested action not taken, file name not allowed.

enumerator sfFtpInvalidResponse

Response is not a valid FTP one.

enumerator sfFtpConnectionFailed

Connection with server failed.

enumerator sfFtpConnectionClosed

Connection with server closed.

enumerator sfFtpInvalidFile

Invalid file to upload / download.

Functions

void sfFtpListingResponse_destroy(sfFtpListingResponse *ftpListingResponse)

Destroy a FTP listing response.

Parameters:

• ftpListingResponse – Ftp listing response to destroy

sfBool sfFtpListingResponse_isOk(const sfFtpListingResponse *ftpListingResponse)

Check if a FTP listing response status code means a success.

This function is defined for convenience, it is equivalent to testing if the status code is < 400.

Parameters:

• ftpListingResponse – Ftp listing response

Returns:

sfTrue if the status is a success, sfFalse if it is a failure

sfFtpStatus sfFtpListingResponse_getStatus(const sfFtpListingResponse *ftpListingResponse)

Get the status code of a FTP listing response.

Parameters:

• ftpListingResponse – Ftp listing response

Returns:

Status code

const char *sfFtpListingResponse_getMessage(const sfFtpListingResponse *ftpListingResponse)

Get the full message contained in a FTP listing response.

Parameters:

• ftpListingResponse – Ftp listing response

Returns:

The response message

size_t sfFtpListingResponse_getCount(const sfFtpListingResponse *ftpListingResponse)

Return the number of directory/file names contained in a FTP listing response.

Parameters:

• ftpListingResponse – Ftp listing response

Returns:

Total number of names available

const char *sfFtpListingResponse_getName(const sfFtpListingResponse *ftpListingResponse, size_t index)

Return a directory/file name contained in a FTP listing response.

Parameters:

• ftpListingResponse – Ftp listing response

• index – Index of the name to get (in range [0 .. getCount])

Returns:

The requested name

void sfFtpDirectoryResponse_destroy(sfFtpDirectoryResponse *ftpDirectoryResponse)

Destroy a FTP directory response.

Parameters:

• ftpDirectoryResponse – Ftp directory response to destroy

sfBool sfFtpDirectoryResponse_isOk(const sfFtpDirectoryResponse *ftpDirectoryResponse)

Check if a FTP directory response status code means a success.

This function is defined for convenience, it is equivalent to testing if the status code is < 400.

Parameters:

• ftpDirectoryResponse – Ftp directory response

Returns:

sfTrue if the status is a success, sfFalse if it is a failure

sfFtpStatus sfFtpDirectoryResponse_getStatus(const sfFtpDirectoryResponse *ftpDirectoryResponse)

Get the status code of a FTP directory response.

Parameters:

• ftpDirectoryResponse – Ftp directory response

Returns:

Status code

const char *sfFtpDirectoryResponse_getMessage(const sfFtpDirectoryResponse *ftpDirectoryResponse)

Get the full message contained in a FTP directory response.

Parameters:

• ftpDirectoryResponse – Ftp directory response

Returns:

The response message

const char *sfFtpDirectoryResponse_getDirectory(const sfFtpDirectoryResponse *ftpDirectoryResponse)

Get the directory returned in a FTP directory response.

Parameters:

• ftpDirectoryResponse – Ftp directory response

Returns:

Directory name

void sfFtpResponse_destroy(sfFtpResponse *ftpResponse)

Destroy a FTP response.

Parameters:

• ftpResponse – Ftp response to destroy

sfBool sfFtpResponse_isOk(const sfFtpResponse *ftpResponse)

Check if a FTP response status code means a success.

This function is defined for convenience, it is equivalent to testing if the status code is < 400.

Parameters:

• ftpResponse – Ftp response object

Returns:

sfTrue if the status is a success, sfFalse if it is a failure

sfFtpStatus sfFtpResponse_getStatus(const sfFtpResponse *ftpResponse)

Get the status code of a FTP response.

Parameters:

• ftpResponse – Ftp response object

Returns:

Status code

const char *sfFtpResponse_getMessage(const sfFtpResponse *ftpResponse)

Get the full message contained in a FTP response.

Parameters:

• ftpResponse – Ftp response object

Returns:

The response message

sfFtp *sfFtp_create(void)

Create a new Ftp object.

Returns:

A new sfFtp object

void sfFtp_destroy(sfFtp *ftp)

Destroy a Ftp object.

Parameters:

• ftp – Ftp object to destroy

sfFtpResponse *sfFtp_connect(sfFtp *ftp, sfIpAddress server, unsigned short port, sfTime timeout)

Connect to the specified FTP server.

The port should be 21, which is the standard port used by the FTP protocol. You shouldn’t use a different value, unless you really know what you do. This function tries to connect to the server so it may take a while to complete, especially if the server is not reachable. To avoid blocking your application for too long, you can use a timeout. Using 0 means that the system timeout will be used (which is usually pretty long).

Parameters:

• ftp – Ftp object

• server – Name or address of the FTP server to connect to

• port – Port used for the connection

• timeout – Maximum time to wait

Returns:

Server response to the request

sfFtpResponse *sfFtp_loginAnonymous(sfFtp *ftp)

Log in using an anonymous account.

Logging in is mandatory after connecting to the server. Users that are not logged in cannot perform any operation.

Parameters:

• ftp – Ftp object

Returns:

Server response to the request

sfFtpResponse *sfFtp_login(sfFtp *ftp, const char *name, const char *password)

Log in using a username and a password.

Logging in is mandatory after connecting to the server. Users that are not logged in cannot perform any operation.

Parameters:

• ftp – Ftp object

• name – User name

• password – Password

Returns:

Server response to the request

sfFtpResponse *sfFtp_disconnect(sfFtp *ftp)

Close the connection with the server.

Parameters:

• ftp – Ftp object

Returns:

Server response to the request

sfFtpResponse *sfFtp_keepAlive(sfFtp *ftp)

Send a null command to keep the connection alive.

This command is useful because the server may close the connection automatically if no command is sent.

Parameters:

• ftp – Ftp object

Returns:

Server response to the request

sfFtpDirectoryResponse *sfFtp_getWorkingDirectory(sfFtp *ftp)

Get the current working directory.

The working directory is the root path for subsequent operations involving directories and/or filenames.

Parameters:

• ftp – Ftp object

Returns:

Server response to the request

sfFtpListingResponse *sfFtp_getDirectoryListing(sfFtp *ftp, const char *directory)

Get the contents of the given directory.

This function retrieves the sub-directories and files contained in the given directory. It is not recursive. The directory parameter is relative to the current working directory.

Parameters:

• ftp – Ftp object

• directory – Directory to list

Returns:

Server response to the request

sfFtpResponse *sfFtp_changeDirectory(sfFtp *ftp, const char *directory)

Change the current working directory.

The new directory must be relative to the current one.

Parameters:

• ftp – Ftp object

• directory – New working directory

Returns:

Server response to the request

sfFtpResponse *sfFtp_parentDirectory(sfFtp *ftp)

Go to the parent directory of the current one.

Parameters:

• ftp – Ftp object

Returns:

Server response to the request

sfFtpResponse *sfFtp_createDirectory(sfFtp *ftp, const char *name)

Create a new directory.

The new directory is created as a child of the current working directory.

Parameters:

• ftp – Ftp object

• name – Name of the directory to create

Returns:

Server response to the request

sfFtpResponse *sfFtp_deleteDirectory(sfFtp *ftp, const char *name)

Remove an existing directory.

The directory to remove must be relative to the current working directory. Use this function with caution, the directory will be removed permanently!

Parameters:

• ftp – Ftp object

• name – Name of the directory to remove

Returns:

Server response to the request

sfFtpResponse *sfFtp_renameFile(sfFtp *ftp, const char *file, const char *newName)

Rename an existing file.

The filenames must be relative to the current working directory.

Parameters:

• ftp – Ftp object

• file – File to rename

• newName – New name of the file

Returns:

Server response to the request

sfFtpResponse *sfFtp_deleteFile(sfFtp *ftp, const char *name)

Remove an existing file.

The file name must be relative to the current working directory. Use this function with caution, the file will be removed permanently!

Parameters:

• ftp – Ftp object

• name – File to remove

Returns:

Server response to the request

sfFtpResponse *sfFtp_download(sfFtp *ftp, const char *remoteFile, const char *localPath, sfFtpTransferMode mode)

Download a file from a FTP server.

The filename of the distant file is relative to the current working directory of the server, and the local destination path is relative to the current directory of your application.

Parameters:

• ftp – Ftp object

• remoteFile – Filename of the distant file to download

• localPath – Where to put to file on the local computer

• mode – Transfer mode

Returns:

Server response to the request

sfFtpResponse *sfFtp_upload(sfFtp *ftp, const char *localFile, const char *remotePath, sfFtpTransferMode mode, sfBool append)

Upload a file to a FTP server.

The name of the local file is relative to the current working directory of your application, and the remote path is relative to the current directory of the FTP server.

Parameters:

• ftp – Ftp object

• localFile – Path of the local file to upload

• remotePath – Where to put to file on the server

• mode – Transfer mode

• append – Pass sfTrue to append to or sfFalse to overwrite the remote file if it already exists

Returns:

Server response to the request

sfFtpResponse *sfFtp_sendCommand(sfFtp *ftp, const char *command, const char *parameter)

Send a command to the FTP server.

While the most often used commands are provided as specific functions, this function can be used to send any FTP command to the server. If the command requires one or more parameters, they can be specified in parameter. Otherwise you should pass NULL. If the server returns information, you can extract it from the response using sfResponse_getMessage().

Parameters:

• ftp – Ftp object

• command – Command to send

• parameter – Command parameter

Returns:

Server response to the request