StarBurn_CdvdBurnerGrabber_CreateEx Function

C++

__stdcall STARBURN_IMPEX_API EXCEPTION_NUMBER StarBurn_CdvdBurnerGrabber_CreateEx(OUT PVOID * p__PPVOID__CdvdBurnerGrabber, OUT PCHAR p__PCHAR__ExceptionText, IN ULONG p__ULONG__ExceptionTextSizeInUCHARs, OUT PULONG p__PULONG__SystemError, OUT PCDB_FAILURE_INFORMATION p__PCDB_FAILURE_INFORMATION, IN PCALLBACK p__PCALLBACK, IN PVOID p__PVOID__Context, IN PCHAR p__PCHAR__DeviceName, IN LONG p__LONG__CacheSizeInMBs);

File

StarBurn.h

Parameters

Parameters	Description
OUT PVOID * p__PPVOID__CdvdBurnerGrabber	Pointer to pointer to the object that toolkit will set to the CdvdBurnerGrabber object it will allocate.
OUT PCHAR p__PCHAR__ExceptionText	Pointer to array of CHARs that will be used to store formatted exception description message.
IN ULONG p__ULONG__ExceptionTextSizeInUCHARs	Size of the array of CHARs used to be formatted exception message storage.
OUT PULONG p__PULONG__SystemError	Pointer to ULONG that will contain the system error (if some will occur).
OUT PCDB_FAILURE_INFORMATION p__PCDB_FAILURE_INFORMATION	Pointer to CDB_FAILURE_INFORMATION that will be filled with apropriate values.
IN PCALLBACK p__PCALLBACK	Callback that will be called to indicate progress of various actions.
IN PVOID p__PVOID__Context	Context value that will be passed to callback function.
IN PCHAR p__PCHAR__DeviceName	Pointer to device symbolic link name we'll use.
IN LONG p__LONG__CacheSizeInMBs	Cache size to use during I/O operations, 0 is a special value that tells the toolkit to allocate default cache size.

Returns

Execution status. EN_SUCCESS if the operation completed successfuly. If the exception number will be EN_SYSTEM_CALL_FAILED, variable that SystemError points to will be filled with system error. If something other then EN_SUCCESS will be returned buffer that ExceptionText will point to will be filled with formatted exception message. If the exception number will be EN_SCSI_CDB_FAILED, CDB_FAILURE_INFORMATION will be filled with apropriate values (CDB that faled, CDB size, SCSI sense data, SCSI sense data size, SCSI transport, device and host adapter status codes).

Description

This function creates CD/DVD/Blu-Ray/HD-DVD burner device object using SPTI (SCSI Pass Thru Interface) transport. This object will be used later to perform CD/DVD/Blu-Ray/HD-DVD releated actions.

Remarks

Please take a look at FindDeviceEx sample to find out how StarBurn_CdvdBurnerGrabber_CreateEx could be used to create CD/DVD/Blu-Ray/HD-DVD burner object. Please note that StarBurn_CdvdBurnerGrabber_CreateEx would create SPTI device thus would work only under Windows NT/2000/XP/2003. If you need Windows 95/98/Me compatibility please use StarBurn_CdvdBurnerGrabber_Create legacy call as it's for ASPI transport (ASPI is natively supported under Windows 95/98/Me and we provide own ASPI-to-SPTI wrapper for StarBurn).

Example

This example allocates CdvdBurnerGrabber object and destroys the device object after it's not needed any more.

// Somewhere in the data region
PVOID l__PVOID__CdvdBurnerGrabber;
EXCEPTION_NUMBER l__EXCEPTION_NUMBER;
ULONG l__ULONG__SystemError;
CHAR l__CHAR__ExceptionText[ 1024 ];
CDB_FAILURE_INFORMATION l__CDB_FAILURE_INFORMATION;

// Prepare exception text buffer
RtlZeroMemory(
    &l__CHAR__ExceptionText,
    sizeof( l__CHAR__ExceptionText )
    );

// Prepare CDB failure information
RtlZeroMemory(
    &l__CDB_FAILURE_INFORMATION,
    sizeof( l__CDB_FAILURE_INFORMATION )
    );

// Try to create CdvdBurnerGrabber using name "D:" with 32MB of cache
l__EXCEPTION_NUMBER =
StarBurn_CdvdBurnerGrabber_CreateEx(
    &l__PVOID__CdvdBurnerGrabber,
    ( PCHAR )( &l__CHAR__ExceptionText ),
    sizeof( l__CHAR__ExceptionText ),
    &l__ULONG__SystemError,
    &l__CDB_FAILURE_INFORMATION,
    ( PCALLBACK )( StarBurn_Callback ),
    "D:",
    32
    );

// Check for correct reply
if (  l__EXCEPTION_NUMBER != EN_SUCCESS )
{
// Handle error here...
}

// Do something with CdvdBurnerGrabber device object here...        

// Destroy the CdvdBurnerGrabber
StarBurn_Destroy( &l__PVOID__CdvdBurnerGrabber );

// Just check for pointer (paranoid?)
if ( l__PVOID__CdvdBurnerGrabber != NULL )
{
// Handle error here...
}

Group

Functions

Links

StarBurn.h, Functions, Example, See Also

Contents | Index | Home