User Callbacks

Functions to notify the user application about FTP client events. More...

Functions
uint32_t	netFTPc_Process (netFTPc_Request request, char *buf, uint32_t buf_len)
	Request parameters for FTP client session. [user-provided]. More...
void	netFTPc_Notify (netFTPc_Event event)
	Notify the user application when FTP client operation ends. [user-provided]. More...

Description

Functions to notify the user application about FTP client events.

All required session parameters are given in the netFTPc_Process callback function. This function is in the FTP_Client_UIF.c module. From the callback function, you can specify the username/password to access the FTP server, a working directory on the FTP server, a filename for the file operation, etc.

The FTP client's operation mode is working with a relative path. This means the filename can not contain a path information. Instead of this, a working directory must be specified in the FTP_Client_UIF.c user interface module. After login, the FTP client first changes the working directory to the path specified in user interface module, and then performs a file command. To add the module to your project, simply right-click on the Source group, select Add New Item to Group, then click on User Code Template and scroll in the template files list until you find the FTP Client User Interface template. The FTP client also supports directory manipulation and rename commands. This allows you to create or remove directories, and to rename files or directories on the server.

The end of a FTP client operation can be notified to the user utilizing the netFTPc_Notify function. It is part of the file FTP_Client_UIF.c module as well. You need to adapt the function to the application's needs.

Function Documentation

netFTPc_Notify()

void netFTPc_Notify

(

netFTPc_Event

event

)

Notify the user application when FTP client operation ends. [user-provided].

Parameters

[in]

event

FTP client notification event as specified in netFTPc_Event.

Returns

none.

Note

Network library calls this function to inform the user about events.

The callback function netFTPc_Notify is called automatically when an FTP event occurred and notifies the user application when the FTP client operation ends.

The argument event is a netFTPc_Event signal:

Event	Description
netFTPc_EventSuccess	The file operation completed successfully
netFTPc_EventTimeout	FTP Server response has timed out, and hence the FTP client has aborted the operation
netFTPc_EventLoginFailed	The FTP client failed to login to FTP server
netFTPc_EventAccessDenied	The file access to a specified file is not allowed
netFTPc_EventFileNotFound	The requested file was not found on FTP server
netFTPc_EventInvalidDirectory	Working directory path not found on FTP server
netFTPc_EventLocalFileError	File open or file write error on local system
netFTPc_EventError	An error encountered during the file operation

Code Example

The following skeleton is available in the user code template file FTP_Client_UIF.c. Customize it to the application's needs.

void netFTPc_Notify (netFTPc_Event event) {
  switch (event) {
    case netFTPc_EventSuccess:
      // File operation successful
      break;
 
    case netFTPc_EventTimeout:
      // Timeout on file operation
      break;
 
    case netFTPc_EventLoginFailed:
      // Login error, username/password invalid
      break;
 
    case netFTPc_EventAccessDenied:
      // File access not allowed
      break;
 
    case netFTPc_EventFileNotFound:
      // File not found
      break;
 
    case netFTPc_EventInvalidDirectory:
      // Working directory path not found
      break;
 
    case netFTPc_EventLocalFileError:
      // Local file open/write error
      break;
 
    case netFTPc_EventError:
      // Generic FTP client error
      break;
  }
}

netFTPc_Process()

uint32_t netFTPc_Process	(	netFTPc_Request	request,
		char *	buf,
		uint32_t	buf_len
	)

Request parameters for FTP client session. [user-provided].

Parameters

[in]	request	request code.
[out]	buf	output buffer to write the data to.
[in]	buf_len	length of the output buffer in bytes.

Returns

number of bytes written to output buffer.

The callback function netFTPc_Process provides additional parameters for the FTP client session such as the credentials to login to the FTP server, local and remote file name for the file operation, etc. The FTP client calls this function several times to complete the file operation requested.

The argument request specifies the type of additional information (user, password, file name, etc.) that the FTP Client requires:

Type	Description
netFTPc_RequestUsername	Username to login to FTP server
netFTPc_RequestPassword	Password to login to FTP server
netFTPc_RequestDirectory	Working directory path on server for all commands
netFTPc_RequestName	File or Directory name for FTP commands
netFTPc_RequestNewName	New File or Directory name for RENAME command
netFTPc_RequestListMask	File filter/mask for LIST command (wildcards allowed)
netFTPc_RequestList	Received data if LIST command is given
netFTPc_RequestLocalFilename	Local filename (including path)

The argument buf is a pointer to the output buffer where the function writes the requested data.

The argument buf_len specifies the length of the output buffer in bytes.

Code Example

The following example is available in the user code template file FTP_Client_UIF.c. Customize it to the application's needs.

uint32_t netFTPc_Process (netFTPc_Request request, char *buf, uint32_t buf_len) {
  uint32_t len = 0;
  int32_t i;
 
  switch (request) {
    case netFTPc_RequestUsername:
      // Username to login to FTP server
      len = sprintf (buf, "anonymous");
      break;
 
    case netFTPc_RequestPassword:
      // Password to login to FTP server
      len = sprintf (buf, "test@keil.com");
      break;
 
    case netFTPc_RequestDirectory:
      // Working directory path on server
      len = sprintf (buf, "/Logs");
      break;
 
    case netFTPc_RequestName:
      // Filename for PUT, GET, APPEND, DELETE and RENAME commands
      // Directory name for MKDIR and RMDIR commands
      len = sprintf (buf, "test.log");
      break;
 
    case netFTPc_RequestNewName:
      // New name for a RENAME command
      len = sprintf (buf, "renamed.log");
      break;
 
    case netFTPc_RequestListMask:
      // File filter/mask for LIST command (wildcards allowed)
      len = sprintf (buf, "");
      break;
 
    case netFTPc_RequestList:
      // Received data if LIST command is given
      for (i = 0; i < len; i++) {
        putchar (buf[i]);
      }
      break;
 
    case netFTPc_RequestLocalFilename:
      // Local filename
      len = sprintf (buf, "test_log.txt");
      break;
  }
  return (len);
}