General

InstantWrite SDK

The InstantWrite SDK exposes functions of the InstantWrite package for use of client applications. The SDK allows applications to perform operations on discs and devices that would require user interactions without the SDK library. These operations include formatting and finalizing discs, writing and reading of the files that are written with the InstantWrite filesystem is done by calling the appropriate operating system functions. The SDK hides details of calling the file system drivers from the client application. The devices are identified by their drive letters.

The SDK can be called by exported library functions or by using automation objects.

(This is a preliminary version of the documentation and subject to changes and enhancements)


DLL reference

InstantWrite API

The DLL reference lists the functions exported by the API library and the structures and constants that are used by these functions. The reference contains syntax information for C++ and ObjectPascal as used with Borland Delphi.

Usage

The link library is named iwsdk.dll. It is located in the InstantWrite installation folder. It is recommended to load the library dynamically in your application.


Initialize

Initializes the InstantWrite library.

C++:
TIWAPIResult __stdcall Initialize(void);

Delphi:
function Initialize: TIWAPIResult; stdcall;

Parameters

none

Return Values

Error code of type IWAPIResult.

Remarks

The client application has to call this function before it can call the functions of the SDK. The function searches for the supported devices and checks if the components of InstantWrite are installed correctly.


GetDevices

Returns a list of the supported devices.

C++:
TIWAPIResult __stdcall GetDevices(PDevices Devices);

Delphi:
function GetDevices(Devices: PDevices): TIWAPIResult; stdcall;

Parameters

Devices

Pointer to a TDevices structure.

Return Values

Error code of type IWAPIResult.

Remarks

This function lets the client application determine what installed devices are supported by InstantWrite. The TDevices structure contains the driveletter that is assigned to a specific device. This driveletter is needed to specify the drive for the possible operations (e.g. Format).


GetDeviceInfo

Returns information about the specified device and the inserted disc.

C++:
TIWAPIResult __stdcall GetDeviceInfo(char DriveLetter, TDeviceInfo &DeviceInfo);
Delphi:
function GetDeviceInfo(DriveLetter: Char; var DeviceInfo: TDeviceInfo): TIWAPIResult; stdcall;

Parameters

DriveLetter

The drive letter that identifies the device.

DeviceInfo

Structure that is filled with the requested information.

Return Values

Error code of type IWAPIResult.

Remarks

GetDeviceInfo returns the drive identifier and information about the inserted disc including the disc type (e.g. CD-R, DVD-RAM,..) and the file system that is on the disc.


FormatDisc

Starts the format process on the disc inserted in the specified device.

C++:
TIWAPIResult __stdcall FormatDisc(char DriveLetter, const TFormatSettings &FormatSettings)
Delphi:
function FormatDisc(DriveLetter: Char; const FormatSettings: TFormatSettings): TIWAPIResult; stdcall;

Parameters

DriveLetter

The drive letter that identifies the device.

FormatSettings

Structure that contains information on the destination format of the disc.

Return Values

Error code of type IWAPIResult.

Remarks

FormatDisc returns after the format is finished. The structure FormatSettings contains a field to set a callback function that will be called by the library to indicate the progress of the format process. Depending on the type of the inserted disc and the format and erase options, formatting a disc can take from a few seconds up to approximately two hours.


FinalizeDisc

Starts the format process on the disc inserted in the specified device.

C++:
TIWAPIResult __stdcall FinalizeDisc(char DriveLetter, const TFinalizeSettings &FinalizeSettings)

Delphi:
function FinalizeDisc(DriveLetter: Char; const FinalizeSettings: TFinalizeSettings): TIWAPIResult;

Parameters

DriveLetter

The drive letter that identifies the device.

FinalizeSettings

Structure that contains information to set options of the finalize process.

Return Values

Error code of type IWAPIResult.

Remarks

FinalizeDisc returns after finalizing the disc is finished. The structure FinalizeSettings contains a field to set a callback function that will be called by the library to indicate the progress of the process.


FormatSettings

Structure to set the options of a disc format invoked with FormatDisc

C/C++:
struct TFormatSettings
{
TFormatType FormatType;
TEraseType EraseType;
TUDFVersion UDFVersion;
DWORD Reference;
char DiscLabel[19];
TCallBackFunction cbProgress;
} ;

Delphi:
TFormatSettings = packed record
FormatType: TFormatType;
EraseType: TEraseType;
UDFVersion: TUDFVersion;
Reference: DWORD;
DiscLabel: array[0..18] of Char;
cbProgress: TCallBackFunction;
end;

Members

FormatType

Can be one of the following values:

  • ftAudio: The CD is prepared to store audio data as single tracks. The user can add tracks by copying .WAV files to the disc.

  • ftDataIncremental: The disc is prepared to store files and folders. Deleting files will not increase the free disc space.

  • ftDataRandom: The disc is prepared to store files and folders. Deleting files will restore disc space. This option can only be used for read/write-discs

EraseType

Determines if and how the disc is erased before formatting.

  • etNone: The disc is not erased. If the disc is already formatted incremental and finished, new data will be appended and the old data can still be read.

  • etQuick: The disc is erased by deleting the directory information of the disc. This takes only a few minutes, but may not be safe on all devices.

  • etFull: The disc is erases by deleting all the sectors on the disc.

UDFVersion

Selects what version of the UDF file system will be written do the disc. Possible values are:

uv102 for version 1.02,
uv150 for version 1.50,
uv200 for version 2.00 and
uv201 for version 2.01

Reference

A value that can be set freely by the client application. This value is passed to the client application as a parameter of the callback function.

DiscLabel

The name that the formatted disc will have.

cbProgress

Address of a callback function that is called to indicate the progress.

Remarks

If you do not want a callback you can set cbProgress to NULL, but you should consider that formatting can take up to about two hours depending on the type of disc you want to format.


FinalizeSettings

Structure to set the options of a disc format invoked with FinalizeDisc

C/C++:
struct TFinalizeSettings
{
DWORD Reference;
TCallBackFunction cbProgress;
} ;

Delphi:
TFormatSettings = packed record
Reference: DWORD;
cbProgress: TCallBackFunction;
end;

Members

Reference

A value that can be set freely by the client application. This value is passed to the client application as a parameter of the callback function.

cbProgress

Address of a callback function that is called to indicate the progress.


Device

Object Device

Description


Device - Erase

Object Device
Erase method

Syntax

object.Erase

Part | Description
object | An object expression that evaluates to a Device object


Device - Finalize

Object Device
Finalize method

Syntax

object.Finalize

Part | Description
object | An object expression that evaluates to a Device object


Device - Format

Object Device
Format method

Syntax

object.Format(DestinationFormat, UDFVersion, EraseMethod)

Part | Description
object | An object expression that evaluates to a Device object
DestinationFormat |
UDFVersion |
EraseMethod |


Device - GetDiscInfo

Object Device
GetDiscInfo method

Syntax

object.GetDiscInfo

Part | Description
object | An object expression that evaluates to a Device object


Device - Mount

Object Device
Mount method

Syntax

object.Mount

Part | Description
object | An object expression that evaluates to a Device object


Device - Settings

Object Device
Settings property (read-only)

Syntax

value = object.Settings

objectAn object expression that evaluates to a Device object

Part | Description
value | Reference to a DeviceSettings object


Device - Unmount

Object Device
Unmount method

Syntax

object.Unmount

Part | Description
object | An object expression that evaluates to a Device object


Devices

Object Devices

Description


Devices - GetDevice

Object Devices
GetDevice method

Syntax

value = object.GetDevice(Index)

objectAn object expression that evaluates to a Devices object

Part | Description
value | Reference to a Device object
Index |


Devices - GetDeviceByPath

Object Devices
GetDeviceByPath method

Syntax

value = object.GetDeviceByPath(Path)

objectAn object expression that evaluates to a Devices object

Part | Description
value | Reference to a Device object
Path |


DeviceSettings

Object DeviceSettings

Description


DeviceSettings - Autoformat

Object DeviceSettings
Autoformat property (read/write)

Syntax

object.Autoformat

Part | Description
object | An object expression that evaluates to a DeviceSettings object


DeviceSettings - CurrentReadspeed

Object DeviceSettings
CurrentReadspeed property (read/write)

Syntax

object.CurrentReadspeed

Part | Description
object | An object expression that evaluates to a DeviceSettings object


DeviceSettings - CurrentWriteSpeed

Object DeviceSettings
CurrentWriteSpeed property (read/write)

Syntax

object.CurrentWriteSpeed

Part | Description
object | An object expression that evaluates to a DeviceSettings object


DeviceSettings - IWActive

Object DeviceSettings
IWActive property (read/write)

Syntax

object.IWActive

Part | Description
object | An object expression that evaluates to a DeviceSettings object


DeviceSettings - ReadSpeeds

Object DeviceSettings
ReadSpeeds property (read-only)

Syntax

object.ReadSpeeds

Part | Description
object | An object expression that evaluates to a DeviceSettings object


DeviceSettings - Writeprotection

Object DeviceSettings
Writeprotection property (read/write)

Syntax

object.Writeprotection

Part | Description
object | An object expression that evaluates to a DeviceSettings object


DriveInformation

Object DriveInformation

Description


DriveInformation - AudioFormatted

Object DriveInformation
AudioFormatted property (read-only)

Syntax

object.AudioFormatted

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - CurrentReadspeed

Object DriveInformation
CurrentReadspeed property (read/write)

Syntax

object.CurrentReadspeed

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - CurrentWriteSpeed

Object DriveInformation
CurrentWriteSpeed property (read/write)

Syntax

object.CurrentWriteSpeed

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - DiscType

Object DriveInformation
DiscType property (read-only)

Syntax

object.DiscType

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - Eraseable

Object DriveInformation
Eraseable property (read-only)

Syntax

object.Eraseable

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - FATFormatted

Object DriveInformation
FATFormatted property (read-only)

Syntax

object.FATFormatted

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - FormatAllowed

Object DriveInformation
FormatAllowed property (read-only)

Syntax

object.FormatAllowed

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - ISOBridgeDisc

Object DriveInformation
ISOBridgeDisc property (read-only)

Syntax

object.ISOBridgeDisc

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - ISOFormatted

Object DriveInformation
ISOFormatted property (read-only)

Syntax

object.ISOFormatted

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - MaxReadSpeed

Object DriveInformation
MaxReadSpeed property (read-only)

Syntax

object.MaxReadSpeed

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - MaxWriteSpeed

Object DriveInformation
MaxWriteSpeed property (read-only)

Syntax

object.MaxWriteSpeed

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - UDFFormatted

Object DriveInformation
UDFFormatted property (read-only)

Syntax

object.UDFFormatted

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - UDFVersion

Object DriveInformation
UDFVersion property (read-only)

Syntax

object.UDFVersion

Part | Description
object | An object expression that evaluates to a DriveInformation object


DriveInformation - UnformattedDVD

Object DriveInformation
UnformattedDVD property (read-only)

Syntax

object.UnformattedDVD

Part | Description
object | An object expression that evaluates to a DriveInformation object


GeneralSettings

Object GeneralSettings

Description


GeneralSettings - ShowEjectForm

Object GeneralSettings
ShowEjectForm property (read/write)

Syntax

object.ShowEjectForm

Part | Description
object | An object expression that evaluates to a GeneralSettings object


iwservice

Object iwservice

Description


iwservice - Devices

Object iwservice
Devices property (read-only)

Syntax

value = object.Devices

objectAn object expression that evaluates to a iwservice object

Part | Description
value | Reference to a Devices object


iwservice - Settings

Object iwservice
Settings property (read-only)

Syntax

value = object.Settings

objectAn object expression that evaluates to a iwservice object

Part | Description
value | Reference to a GeneralSettings object