The FTP Voyager Software Development Kit was designed with ease of use and expandability in mind. FTP Voyager, and consequently the SDK, is very flexible and contains many options that could make programming a complex task. With that in mind, the SDK was created in such a way that legacy applications can easily migrate to newer versions. The idea was to limit the number of function parameters by keeping most options and settings in a single structure.
The FVSDK_Session structure contains each of the available options concerning an FTP client's session to an FTP server. For each session you want to establish with an FTP server, you'll create a separate FVSDK_Session structure. Disabling connection saver in the FVSDK_Session structure will cause subsequent connections to be made to the same server on behalf of this session for the purpose of transferring a file. In this case, these connections will inherit the attributes defined in the FVSDK_Session structure used when creating the initial connection to the server. This allows you to quickly and easily define all options and attributes that govern the behavior of all connections made to that server in a single session.
Various functions can be used to create, initialize, and maintain this structure. Depending on your needs, an FVSDK_Session structure may be allocated on the stack or on the heap.
| FVSDK_ValidSession() | Verifies an FVSDK_Session structure. Usually used internally by the SDK, however can be called by the application as well. |
| FVSDK_InitSession() | Initializes an FVSDK_Session structure, usually when allocated on the stack. Prior to calling this function, the FVSDK_Session structure elements nSize and nVersion must be set appropriately. |
| FVSDK_CloseSession() | Closes and frees internal memory associated with an FVSDK_Session. Call this function ONLY when FVSDK_InitSession() was used to initialize the session. Do NOT call when FVSDK_NewSession() was used. |
| FVSDK_NewSession() | Allocates and initializes (by calling FVSDK_InitSession()) an FVSDK_Session on the heap. |
| FVSDK_FreeSession() | Releases, closes, and frees internal memory associated with an FVSDK_Session. Call this function ONLY when FVSDK_NewSession() was used to initialize the session. Do NOT call when FVSDK_InitSession() was used. |
| FVSDK_ApplySessionChange() | Applies the session elements to the connecting session. If session changes are required, such as using PASV mode, change the element in the FVSDK_Session structure, then call this function to apply the change. |
The following C sample shows how an FVSDK_Session structure can be allocated on the stack, then initialized. Notice how the nVersion and nSize members must be set prior to the FVSDK_InitSession() call.
#include <windows.h>
#include "FVSDK_Funcs.h"
int main(int argc, char* argv[])
{
int nRet = 0;
// create the session structure
FVSDK_Session Session;
// initialize the structure
Session.nVersion = FVSDK_SESSION_CURRENT_VERSION;
Session.nSize = sizeof(Session);
// initialize the session in the SDK
if (FVSDK_InitSession(&Session, FALSE) == FVSDK_OK) {
// ... do some work
// close the session
if (FVSDK_CloseSession(&Session) != FVSDK_OK)
nRet = 1;
} // if
else
nRet = 2;
// exit from our application, 0 == success, otherwise an error
return (nRet);
} // main
The following C sample shows how an FVSDK_Session structure can be allocated on the heap by the FTP Voyager SDK then freed. When using the FTP Voyager SDK functions to allocate and release the structure, there is no need to set the nVersion and nSize elements in the structure.
#include <windows.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) { // ... do some work // close and release the session FVSDK_FreeSession(pSession); } // if else nRet = 1; // exit from our application, 0 == success, otherwise an error return (nRet); } // main