Native dll interface

General description

Native dll API usage is the most quick and efficient way to implement virtual drive callback handlers. Native DLL can be used by any programming language that supports external DLL functions calls. It can be C++, Delphi, Visual Basic etc. Script languages like python should use COM interface.

VDSDKCommon.h: common types declarations

#ifndef _VSDK_COMMON_DECL_H_
#define _VSDK_COMMON_DECL_H_

#include <windows.h>

typedef long DRIVE_HANDLE;
#define INVALID_DRIVE_HANDLE -1

// -------------------------------------------
// Callback handlers definitions
// -------------------------------------------

/*
Read callback typedef
@param h drive handle
@param ReadOffset read data offset
@param ReadSize size of data to read
@param ReadBuffer pointer to the destination buffer
@param BytesRead actually read bytes count
@return result
*/
typedef BOOL (_stdcall *ON_READ_CALLBACK)(
    DRIVE_HANDLE h,
    ULONGLONG ReadOffset,
    ULONG ReadSize,
    void* ReadBuffer,
    ULONG *BytesRead
    );

/*
Write callback typedef
@param h drive handle
@param Writeffset write data offset
@param WriteSize size of data to write
@param WriteBuffer pointer to the destination buffer
@param BytesWritten actually written bytes count
@return  result
*/
typedef BOOL (_stdcall *ON_WRITE_CALLBACK)(
    DRIVE_HANDLE h,
    ULONGLONG WriteOffset,
    ULONG WriteSize,
    const void* WriteBuffer,
    ULONG *BytesWritten
    );





// VDSDK notifications
enum
{
    VDSDK_OnUnmountRemovableMedia = 0, // removable media is being unmounted
    VDSDK_OnUnmountedDrive = 1, // drive has been unmounted
};

/*
VDSDK notifications handler typedef
@param h drive handle
@param NotificationCode notification code
@param Reserved ignored
@return  result
*/
typedef BOOL (_stdcall *ON_VDSDK_NOTIFICATION)(
    DRIVE_HANDLE h,
    ULONG NotificationCode,
    ULONG Reserved
    );




// -------------------------------------------
// Callback handlers for drive formatting
// -------------------------------------------

// Format callback
// @param Progress: Progress in percents
// @return ignored
typedef BOOL (_stdcall *ON_FORMAT_CALLBACK)(ULONG Progress);


#endif

VDSDKDll.h: VDSDK exported functions declarations

#ifndef _VSDK_DLL_H_
#define _VSDK_DLL_H_

#include "VDSDKCommon.h"

#ifdef VSDK_DLL_EXPORTS
#define VDSDK_API extern "C" _declspec(dllexport)
#else
#define VDSDK_API extern "C" _declspec(dllimport)
#endif


// drive flags (DriveFlags in CreateVirtualDriveEx)
enum
{
    DRIVE_FLAG_REMOVABLE = 1,
    DRIVE_FLAG_CDROM = 2,
    DRIVE_FLAG_FLOPPY = 4,
};


// -------------------------------------------
// General purpose API functions
// -------------------------------------------

/*
Initialize Virtual Drive SDK
If driver is not running, it will be installed and started
@return result
*/
VDSDK_API
BOOL
_stdcall InitializeVDSDK();


/*
Uninitialize Virtual Drive SDK
@param bForceUnmountDisks forcibly dismount disks if they are used
*/
VDSDK_API
void
_stdcall ShutdownVDSDK(BOOL bForceUnmountDisks);


/*
Create virtual drive and register virtual drive callback handlers
@param DriveLetter drive letter (e.g. 'X')
@param DriveSize drive size, MB
@param pReadCallback pointer to read callback handler
@param pWriteCallback pointer to write callback handler
@return drive handle
*/
VDSDK_API
DRIVE_HANDLE
_stdcall CreateVirtualDrive(
           char DriveLetter,
           ULONG DriveSize,
           ON_READ_CALLBACK pReadCallback,
           ON_WRITE_CALLBACK pWriteCallback
           );


/*
Create virtual drive and register virtual drive callback handlers
@param DriveLetter drive letter (e.g. 'X')
@param DriveSize drive size, MB
@param pReadCallback pointer to read callback handler
@param pWriteCallback pointer to write callback handler
@param bReadOnly create read-only drive
@param DriveFlags: drive flags
@return drive handle
*/
VDSDK_API
DRIVE_HANDLE
_stdcall CreateVirtualDriveEx(
                   char DriveLetter,
                   ULONG DriveSize,
                   ON_READ_CALLBACK pReadCallback,
                   ON_WRITE_CALLBACK pWriteCallback,
                   BOOL bReadOnly,
                   ULONG DriveFlags
                   );



/*
Format drive
@param h drive handle
@param bQuickFormat quick or full format
@param FileSystem "FAT", "FAT32" or "NTFS"
@param VolumeLabel volume label
@param pCallbackHandler callback (format callback, can be NULL)
@return result
*/
VDSDK_API
BOOL
_stdcall FormatVirtualDrive(
                         DRIVE_HANDLE h, 
                         BOOL bQuickFormat, 
                         const char* FileSystem, 
                         const char* VolumeLabel, 
                         ON_FORMAT_CALLBACK pCallbackHandler);


/*
Destroy virtual drive by drive handle
@param h drive handle
@param bForce force dismount disk in case it is used
@return result
*/
VDSDK_API
BOOL
_stdcall DestroyVirtualDrive(DRIVE_HANDLE h, BOOL bForce);


/*
Get error code.
Error codes are defined in VDSDKErrors.h
@return result
*/
VDSDK_API
int
_stdcall GetVDSDKErrorCode();


/*
Register VDSDK notification handler
*/
VDSDK_API
void
_stdcall RegisterNotificationHandler(ON_VDSDK_NOTIFICATION pNotificationHandler);


// -------------------------------------------
// Additional kernel driver control functions
// -------------------------------------------

/*
Install kernel driver service
@return result
*/
VDSDK_API
BOOL
_stdcall InstallDriver();


/*
Start kernel driver service
@return result
*/
VDSDK_API
BOOL
_stdcall StartDriver();

/*
Stop kernel driver service
@return result
*/
VDSDK_API
BOOL
_stdcall StopDriver();

/*
Uninstall kernel driver service
@return result
*/
VDSDK_API
BOOL
_stdcall UninstallDriver();

/*
Query whether kernel driver is started
@return result
*/
VDSDK_API
BOOL
_stdcall IsDriverReady();

/*
Obtain kernel driver version
@param major (reference) Major version
@param minor (reference) Minor version
@return result
*/
VDSDK_API
BOOL
_stdcall GetVDSDKDriverVersion(int &major, int &minor);

/*
Activate VDSDK
@param ActivationKey Activation key that activates all features. 
                     It is shipped with commercial license.
@return result
*/
VDSDK_API
BOOL 
_stdcall ActivateVDSDK(const char* ActivationKey);

#endif

VDSDKDynamicLoad.h: dynamic native dll loading support

#ifndef _VSDK_DYNAMIC_LOAD_H_
#define _VSDK_DYNAMIC_LOAD_H_

/*
    Dynamic VDSDKDll.dll loading support.
    You should define _VDSDK_DECLARE_FUNCTION_POINTERS_ macro
    and include this file once in your code.
*/

#include "VDSDKCommon.h"

// ===================================
// Declare VDSDK functions prototypes
// ===================================
typedef BOOL (_stdcall *Proc_InitializeVDSDK)();
typedef void (_stdcall *Proc_ShutdownVDSDK)(BOOL bForceUnmountDisks);
typedef DRIVE_HANDLE (_stdcall *Proc_CreateVirtualDrive)(
    char DriveLetter,
    ULONG DriveSize,
    ON_READ_CALLBACK pReadCallback,
    ON_WRITE_CALLBACK pWriteCallback
    );

typedef DRIVE_HANDLE (_stdcall *Proc_CreateVirtualDriveEx)(
    char DriveLetter,
    ULONG DriveSize,
    ON_READ_CALLBACK pReadCallback,
    ON_WRITE_CALLBACK pWriteCallback,
    BOOL bReadOnly,
    ULONG DriveFlags
    );

typedef BOOL (_stdcall *Proc_DestroyVirtualDrive)(DRIVE_HANDLE h, BOOL bForce);
typedef int (_stdcall *Proc_GetVDSDKErrorCode)();
typedef BOOL (_stdcall *Proc_InstallDriver)();
typedef BOOL (_stdcall *Proc_StartDriver)();
typedef BOOL (_stdcall *Proc_StopDriver)();
typedef BOOL (_stdcall *Proc_UninstallDriver)();
typedef BOOL (_stdcall *Proc_IsDriverReady)();
typedef BOOL (_stdcall *Proc_GetVDSDKDriverVersion)(int &major, int &minor);
typedef BOOL (_stdcall *Proc_ActivateVDSDK)(const char* ActivationKey);
typedef BOOL (_stdcall *Proc_FormatVirtualDrive)(DRIVE_HANDLE h, BOOL bQuickFormat, const char* FileSystem, const char* VolumeLabel, ON_FORMAT_CALLBACK pCallback);
typedef void (_stdcall *Proc_RegisterNotificationHandler)(ON_VDSDK_NOTIFICATION pNotificationHandler);


// declaration of the function to correctly initialize pointers
bool InitializeVDSDKFunctionPointers(const char* DllPath = "VDSDKDll.dll");


#ifdef _VDSDK_DECLARE_FUNCTION_POINTERS_
// ===================================
// Declare pointers to VDSDK functions 
// ===================================
Proc_InitializeVDSDK InitializeVDSDK = NULL;
Proc_ShutdownVDSDK ShutdownVDSDK = NULL;
Proc_CreateVirtualDrive CreateVirtualDrive = NULL;
Proc_CreateVirtualDriveEx CreateVirtualDriveEx = NULL;
Proc_DestroyVirtualDrive DestroyVirtualDrive = NULL;
Proc_GetVDSDKErrorCode GetVDSDKErrorCode = NULL;
Proc_InstallDriver InstallDriver = NULL;
Proc_StartDriver StartDriver = NULL;
Proc_StopDriver StopDriver = NULL;
Proc_UninstallDriver UninstallDriver = NULL;
Proc_IsDriverReady IsDriverReady = NULL;
Proc_GetVDSDKDriverVersion GetVDSDKDriverVersion = NULL;
Proc_ActivateVDSDK ActivateVDSDK = NULL;
Proc_FormatVirtualDrive FormatVirtualDrive = NULL;
Proc_RegisterNotificationHandler RegisterNotificationHandler = NULL;

// ===================================
// Initialize function pointers
// ===================================
bool InitializeVDSDKFunctionPointers(const char* DllPath)
{
    HMODULE h = LoadLibrary(DllPath);
    if(h == NULL)
        return false;

    if((InitializeVDSDK = (Proc_InitializeVDSDK)GetProcAddress(h, "InitializeVDSDK")) == NULL)return false;
    if((ShutdownVDSDK = (Proc_ShutdownVDSDK)GetProcAddress(h, "ShutdownVDSDK")) == NULL)return false;
    if((CreateVirtualDrive = (Proc_CreateVirtualDrive)GetProcAddress(h, "CreateVirtualDrive")) == NULL)return false;
    if((CreateVirtualDriveEx = (Proc_CreateVirtualDriveEx)GetProcAddress(h, "CreateVirtualDriveEx")) == NULL)return false;
    if((DestroyVirtualDrive = (Proc_DestroyVirtualDrive)GetProcAddress(h, "DestroyVirtualDrive")) == NULL)return false;
    if((GetVDSDKErrorCode = (Proc_GetVDSDKErrorCode)GetProcAddress(h, "GetVDSDKErrorCode")) == NULL)return false;
    if((InstallDriver = (Proc_InstallDriver)GetProcAddress(h, "InstallDriver")) == NULL)return false;
    if((StartDriver = (Proc_StartDriver)GetProcAddress(h, "StartDriver")) == NULL)return false;
    if((StopDriver = (Proc_StopDriver)GetProcAddress(h, "StopDriver")) == NULL)return false;
    if((UninstallDriver = (Proc_UninstallDriver)GetProcAddress(h, "UninstallDriver")) == NULL)return false;
    if((IsDriverReady = (Proc_IsDriverReady)GetProcAddress(h, "IsDriverReady")) == NULL)return false;
    if((GetVDSDKDriverVersion = (Proc_GetVDSDKDriverVersion)GetProcAddress(h, "GetVDSDKDriverVersion")) == NULL)return false;
    if((ActivateVDSDK = (Proc_ActivateVDSDK)GetProcAddress(h, "ActivateVDSDK")) == NULL)return false;
    if((FormatVirtualDrive = (Proc_FormatVirtualDrive)GetProcAddress(h, "FormatVirtualDrive")) == NULL)return false;
    if((RegisterNotificationHandler = (Proc_RegisterNotificationHandler)GetProcAddress(h, "RegisterNotificationHandler")) == NULL)return false;

    return true;
}

#endif


#endif