The primary use for the FTP Voyager SDK is to upload and download files to FTP servers. With the FTP Voyager SDK, this is accomplished using two methods: One-Step Transfers and Manual Transfers. Although each method achieves the same results, there may be times where one method is more appropriate or useful to your application than the other.
The easiest way to transfer a file is to use either FVSDK_Download() or FVSDK_Upload(). The parameters for both of these functions are the same: the FVSDK_Session pointer, the source file, and the destination file or directory. If the source file path contains a wild carded file name, such as "*.txt", the destination must be a directory name. If the source file path is a single file, the destination may be a directory path or a file path (i.e., with a different file name than the source file).
These one-step transfer functions operate at a higher level and contain user interface messages and dialogs that may be displayed. For example, if the FVSDK_Session element bShowTransferDialogs is set to TRUE, pop-up transfer dialogs are displayed to the user. If overwrite confirmations (bConfirmUploadOverwrite and bConfirmDownloadOverwrite) are enabled, the user will be prompted for action if the destination file already exists.
Like FTP Voyager itself, these functions also allow you to asynchronously upload or download files. Set bConnectionSaver to FALSE to enable asynchronous (non-blocking) transfers. When set to TRUE, both FVSDK_Download() and FVSDK_Upload() return after the file transfer(s) has completed. When set to FALSE, both functions return after a new connection is established for the file transfer(s). The following example, SampleC-XFer-One-Step.c, shows how to download a file using a blocking FVSDK_Download() call.
#include <windows.h>
#include <stdio.h>
#include <conio.h>
#include "FVSDK_Funcs.h"
int main(int argc, char* argv[])
{
int nRet = 0;
FVSDK_Session* pSession;
// allocate and initialize the session in the SDK
if (FVSDK_NewSession(&pSession) == FVSDK_OK) {
// set the server name to connect to
pSession->pszServer = "ftp.rhinosoft.com";
// show the pop-up transfer dialog
pSession->bShowTransferDialogs = TRUE;
// try to connect to the server
if (FVSDK_Connect(pSession) == FVSDK_OK) {
// download the file from the server
if (FVSDK_Download(pSession, "/rhinosoft/00index.txt", "C:\\Temp\\00index.txt") != FVSDK_OK)
nRet = 3;
// disconnect from the server
FVSDK_Disconnect(pSession);
} // if
else
nRet = 2;
// close and release the session
FVSDK_FreeSession(pSession);
} // if
else
nRet = 1;
// display any error or a success message
if (nRet)
printf("error: %d\r\n", nRet);
else
printf("File transferred successfully.\r\n");
// tell the user to press a key on the keyboard
printf("Press any key --> ");
// wait for the user to press a key on the keyboard
getch();
// exit from our application, 0 == success, otherwise an error
return (nRet);
} // main
In the example above, FVSDK_Upload() could be used instead of FVSDK_Download() to upload a file, however a proper user ID and password would need to be set in addition to the file paths being reversed. Please remember to use UNIX style file and directory paths for remote paths. UNIX style listings use a forward slash "/" instead of a backslash "\" to delimit directory names.
For information about receiving status information for file transfers, refer to the Getting Started Callback section.
For some applications, you may want or need to transfer a file in much the same way Windows programmers save a file. The standard open, read or write, and close operations are also available for both downloading and uploading files through the FTP Voyager SDK. To download, a file use FVSDK_OpenFile(), FVSDK_ReadFile(), and FVSDK_CloseFile(). To upload a file, use FVSDK_CreateFile(), FVSDK_WriteFile(), and FVSDK_CloseFile(). Higher level functionality is not available for these functions. FVSDK_Session elements such as bConnectionSaver and bShowTransferDialogs have no effect on this type of transfer. Each operation is synchronous (blocking).
The following example shows how a C program, SampleC-XFer-Manual.c, can download a file using the manual method. This sample prints the file directly to the screen using puts().
#include <windows.h>
#include <stdio.h>
#include <conio.h>
#include "FVSDK_Funcs.h"
int main(int argc, char* argv[])
{
int nRet = 0;
FVSDK_Session* pSession;
// allocate and initialize the session in the SDK
if (FVSDK_NewSession(&pSession) == FVSDK_OK) {
// set the server name to connect to
pSession->pszServer = "ftp.rhinosoft.com";
// try to connect to the server
if (FVSDK_Connect(pSession) == FVSDK_OK) {
// attempt to open the file to be downloaded
if (FVSDK_OpenFile(pSession, "/pub/rhinosoft/00index.txt", FALSE, 0) == FVSDK_YES) {
BYTE Buffer[1025];
int nBytes = (sizeof(Buffer) - 1);
// read all of the data from the remote file, and write it the console
while (FVSDK_ReadFile(pSession, Buffer, &nBytes) == FVSDK_YES) {
// add a NULL terminator to the string
Buffer[nBytes] = '\0';
// display the data from the file
puts(Buffer);
// reset the buffer size
nBytes = (sizeof(Buffer) - 1);
} // while
// close the remote file
FVSDK_CloseFile(pSession);
} // if
else
nRet = 3;
// disconnect from the server
FVSDK_Disconnect(pSession);
} // if
else
nRet = 2;
// close and release the session
FVSDK_FreeSession(pSession);
} // if
else
nRet = 1;
// display any error
if (nRet)
printf("error: %d\r\n", nRet);
// tell the user to press a key on the keyboard
printf("Press any key --> ");
// wait for the user to press a key on the keyboard
getch();
// exit from our application, 0 == success, otherwise an error
return (nRet);
} // main
In the sample above, the file is opened in ASCII mode with the FVSDK_OpenFile() function. FVSDK_ReadFile() is called until no more data is available. For each packet of data read from the file, the packet is printed to the screen. When complete, the FVSDK_CloseFile() function is called. During the transfer, no transfer dialog is displayed and there are no overwrite confirmations. Additionally, no callback functions are called for transfer status or transfer errors.