© Sonic Solutions. All Rights Reserved.
PrimoSDK's function calls are covered in the following sections:
To find a specific call by name, see Alphabetic Call List.
Each call entry below includes a description of the usage of the call, the value(s) returned by the call, and the call's parameter(s), if any. Parameters are categorized as follows:
! NOTE: The following sections include references to PrimoSDK functions that are licensed on an optional basis (see PrimoSDK Options in Chapter 1). For information on which functions are included in your license, or to license optional PrimoSDK functionality, please contact your Sonic representative.
6.1 API Management and Status | go: top |
This section covers the following calls:
PrimoSDK_Trace, PrimoSDK_Init, PrimoSDK_End, PrimoSDK_GetHandle, PrimoSDK_ReleaseHandle, PrimoSDK_RunningStatus
These calls are used to launch and terminate PrimoSDK, to get and release handles needed for operations, and to obtain running status information.
The following launch sequence is used to work with PrimoSDK:
PrimoSDK_Trace | go: top | section |
PrimoSDK_Trace sets the trace mode. If the parameter dwTrace is set to "0," the trace mode is disabled. If not, all calls to PrimoSDK are logged in the text file <appname>.DBG. The PrimoSDK trace may be enabled or disabled at any time.
NOTE: It may be helpful to introduce a "back door" in the host application allowing users to activate trace mode when needed to create a log file to aid debugging.
Syntax
DWORD WINAPI PrimoSDK_Trace ( DWORD dwTrace );
Parameters
Input
dwTrace
A DWORD whose value is used to set the debug trace mode:
- if "0" then trace mode is disabled.
- if not "0" then trace mode is enabled
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_Init | go: top | section |
PrimoSDK_Init initializes the internal structures of the PrimoSDK. The version number of the initialized DLL is output with the parameter pdwRelease.
NOTES:
! If your license is for PrimoSDK Realtime and you plan to use PrimoSDK's StreamFS (streaming-related file system) functions, initialize PrimoSDK with PrimoSDK_InitStreamFileSystem instead of this call.
» This function must be called before any all other PrimoSDK calls except PrimoSDK_Trace. The function is called only once, when the host application or module starts.
» PrimoSDK needs an ASPI layer to communicate with both ATAPI or SCSI units. A compatible WinASPI layer or PxHelper (recommended) may be used.
Syntax
DWORD WINAPI PrimoSDK_Init ( PDWORD pdwRelease );
Parameters
Output
pdwRelease
A pointer to the DWORD that is to be filled in with the version number of the PRIMOSDK.DLL. The version is output in the format 0xRRSSBBBB, with the following component parts:
- RR = Version number
- SS = Sub Version number
- BBBB = Build number
Returned values
PRIMOSDK_CDDVDVERSION
A retail CD and DVD version of PrimoSDK has been successfully initialized.
PRIMOSDK_DEMOVERSION
A demo version of PrimoSDK has been successfully initialized.
PRIMOSDK_CMDSEQUENCE
PrimoSDK has already been initialized.
PRIMOSDK_NOASPI
The ASPI layer is not loading or is in error.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_End | go: top | section |
PrimoSDK_End terminates PrimoSDK, freeing the internal structures. This function must be called after all the other PrimoSDK calls have been terminated.
NOTE: Call this function only once, when the host application or module terminates.
Syntax
DWORD WINAPI PrimoSDK_End ( VOID );
Parameters
VOID
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_INTERR
An internal error occurred.
PrimoSDK_GetHandle | go: top | section |
PrimoSDK_GetHandle outputs a handle (a unique resource identifier for the PrimoSDK) that must be used in any call to PrimoSDK. The handle is output with the parameter pdwHandle. Multiple handles may be obtained, allowing multiple simultaneous operations on different drives.
NOTE: A handle is released by calling PrimoSDK_ReleaseHandle.
Syntax
DWORD WINAPI PrimoSDK_GetHandle ( PDWORD pdwHandle );
Parameters
Output
pdwHandle
A pointer to the DWORD that is to be filled in with the newly-created handle.
Returned values
PRIMOSDK_OK
The handle was successfully created.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_INTERR
An internal error occurred.
PrimoSDK_ReleaseHandle | go: top | section |
PrimoSDK_ReleaseHandle releases a handle that has been output by PrimoSDK_GetHandle. The handle to release is specified with the parameter dwHandle.
Syntax
DWORD WINAPI PrimoSDK_ReleaseHandle ( DWORD dwHandle );
Parameters
Input
dwHandle
A DWORD specifying the handle to release.
Returned values
PRIMOSDK_OK
The handle has been released.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_INTERR
An internal error occurred.
PrimoSDK_RunningStatus | go: top | section |
PrimoSDK_RunningStatus reports on the current status of the testing, recording, extracting, or erasing operation identified with the handle in the parameter dwHandle.
Depending on the value specified in dwFlags, the call may also be used to abort the operation. Because some recording situations take time to conclude, the call may continue to return "PRIMOSDK_RUNNING" for some time after an abort request before returning "PRIMOSDK_USERABORT."
The sector on which the operation is currently acting is output as pdwCurSector, while the total number of sectors involved in the operation is output as pdwTotSector.
NOTES:
» If the operation is no longer running (the call returns PRIMOSDK_OK), use PrimoSDK_UnitStatus to check whether or not the operation completed successfully for each of the operation's target media.
» To avoid clogging the system, this function should be called every 1, 2 or 3 seconds in a timer loop.
» If the current operation is data mastering, pdwTotSector will return as "0" from the time that PrimoSDK_WriteImage is launched until the premastering phase is completed and it becomes known exactly how many sectors are required.
» If PrimoSDK_RunningStatus is called after PrimoSDK_WriteImage and after the value of pdwTotSector becomes greater than "0," the mastering operation will pause for 2 seconds, allowing time for the operation to be aborted before the start of any real recording. This is particularly useful in close-to-full situations because the pdwSize parameter of PrimoSDK_WriteImage returns only an approximation of the total sectors needed.
Syntax
DWORD WINAPI PrimoSDK_RunningStatus (
DWORD dwHandle,
DWORD dwFlags,
PDWORD pdwCurSector,
PDWORD pdwTotSector
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwFlags
A DWORD containing one of the following:
- PRIMOSDK_GETSTATUS gets the status of the operation;
- PRIMOSDK_ABORT aborts the operation.
Output
pdwCurSector
A pointer to the DWORD that is to be filled in with the number of the sector on which the operation is currently acting.
pdwTotSector
A pointer to the DWORD that is to be filled in with the total sectors involved in the operation.
Returned values
PRIMOSDK_RUNNING
The operation is currently running.
PRIMOSDK_OK
The operation is no longer running. To check the result for each of the target media, use PrimoSDK_UnitStatus.
PRIMOSDK_USERABORT
The operation was aborted because of a call with the PRIMOSDK_ABORT flag.
The following codes apply to all drives involved in the operation:
PRIMOSDK_CMDSEQUENCE
PrimoSDK_RunningStatus was called out of sequence. This usually indicates that a job was not started correctly (something failed) before calling this command.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_BADPARAM
dwFlags contains an invalid combination of flags.
PRIMOSDK_FEATURE_NOT_SUPPORTED
A call was made to a function that is not available.
PRIMOSDK_FILEERROR
There was an error writing a file during extraction or while creating an image:
- If writing to a file (for example PrimoSDK_SaveGI), this would occur if the file cannot be opened or written (for example the hard disc is full).
- If reading from a file (for example PrimoSDK_WriteGI), this would occur if the file cannot be opened or read (for example an invalid file name, or the file is on the network and the connection was lost).
PRIMOSDK_TMPOVERFLOW
If a temporary disc cache was specified for small files while mastering, this error could be returned if there was an error writing to or reading from the temporary cache.
PRIMOSDK_DVDSTRUCTERROR
If mastering a DVD Video, there was a problem detected in the DVD Video file set.
PRIMOSDK_INTERR
An internal error occured.
6.2 Drive Information and Status | go: top |
This section covers the following calls:
PrimoSDK_ListSupportedUnits, PrimoSDK_UnitInfo, PrimoSDK_UnitInfo2, PrimoSDK_UnitSpeeds, PrimoSDK_UnitReady, PrimoSDK_UnitStatus
These calls are used to retrieve information related to drives and to check drive status.
NOTE: Additional functionality related to drives is available via PrimoSDK Realtime, a set of optional StreamFS functions (documented in the StreamFS Addendum).
PrimoSDK_ListSupportedUnits | go: top | section |
PrimoSDK_ListSupportedUnits outputs a list of the drives supported by the currently initialized version of PrimoSDK. The list, output with the parameter szList, contains one drive per line, separated by " <CR><LF>" and terminated by " <00>." Each line contains three comma-delimited fields: Vendor ID, Product ID, and Px class.
The "class" number is a proprietary number used to group drives (from either a single manufacturer or various manufacturers) whose firmware has similar characteristics. This allows Px engine to deal more effectively with any anomalies of the drives assigned to each class.
NOTES:
» szList must be at least 10,000 bytes in length.
» The Vendor ID and the Product are returned exactly as they are spelled by the unit. If the manufacturer has left the vendor ID blank then the Vendor ID is returned as " [no brand]."
» szList does not include drives temporarily supported via a Px.ini file.
Syntax
DWORD WINAPI PrimoSDK_ListSupportedUnits ( PBYTE szList );
Parameters
Output
szList
A pointer to the BYTE buffer that is to be filled in with the list.
Returned values
DWORD
The number of the entries in the list.
PrimoSDK_UnitInfo | go: top | section |
PrimoSDK_UnitInfo retrieves information about the unit specified by the parameter pdwUnit. The type of drive is output with pdwType, while the Vendor, Product, and Firmware Version of the unit are output with szDescr. The call also retrieves the readiness state of the unit and outputs it with pdwReady.
pdwUnit allows the unit to be identified either by drive letter, by SCSI Host/ID/LUN triple, or by both. The drive letter, which must be uppercase, takes precedence over the triple. The drive letter is specified with the least significant byte of the DWORD (e.g. for unit "D," pdwUnit points to "0x00000044"), in which case the other three bytes are ignored. To identify the drive by triple, the least significant byte must be "00" or "20" (e.g. for the unit at Host 1, ID 3, Lun 0, pdwUnit points to "0x01030000").
When the function executes, the value of the DWORD pointed to by pdwUnit may be modified by PrimoSDK. In both of the examples above, for instance, the value would become "0x01030044" (combining the triple and the drive letter). However, if the least significant byte is given as "20" rather than "00," PrimoSDK will not change the least significant byte to the drive letter, leaving the value of the DWORD unchanged.
NOTES:
» In some cases recorders of SCSI Type 4 (e.g. Yamaha CDR100) are not assigned a drive letter by the system, or the drive's letter setting (especially under Windows NT/2000) may not be completely or correctly seen by the ASPI layer. In these situations the DWORD pointed to by pdwUnit must identify the unit by triple only, with the least significant byte given as "00."
» For drives that support DVD-RW and DVD+RW, the value of the parameter pdwType is PRIMOSDK_DVDRW.
» szDescr must be at least 50 bytes in length. The last 4 characters of szDescr always contain the firmware version of the drive.
Syntax
DWORD WINAPI PrimoSDK_UnitInfo (
DWORD dwHandle,
PDWORD pdwUnit,
PDWORD pdwType,
PBYTE szDescr,
PDWORD pdwReady
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple.
Output
pdwType
A pointer to the DWORD that is to be filled in with the unit type:
- PRIMOSDK_CDROM for CD-ROM
- PRIMOSDK_CDR for supported CD-R
- PRIMOSDK_CDRW for supported CD-RW
- PRIMOSDK_DVDR for supported DVD-R
- PRIMOSDK_DVDROM for DVD-ROM
- PRIMOSDK_DVDRAM for supported DVD-RAM
- PRIMOSDK_DVDRW for supported DVD-RW
- PRIMOSDK_ROBOTICS for robotic changer
- PRIMOSDK_DVDPRW for supported DVD+RW
- PRIMOSDK_DVDPR for DVD+R
- PRIMOSDK_DVDPR9 for supported DVD+RW9
- PRIMOSDK_OTHER if the unit is of another type
szDescr
A pointer to the BYTE that is to be filled in with the Vendor, Product, and Firmware Version of the unit (to have PrimoSDK skip retrieval of this information, pass a NULL pointer).
pdwReady
A pointer to the DWORD that is to be filled in with the unit's ready state (to have PrimoSDK skip retrieval of this information, pass a NULL pointer):
- if "1" the unit is ready;
- if "0" the unit is not ready.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The requested drive does not exist.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_UnitInfo2 | go: top | section |
PrimoSDK_UnitInfo2 retrieves additional information about the unit specified by the parameter pdwUnit that is not covered by PrimoSDK_UnitInfo. The class of the unit is output with pdwClass, and the type of bus to which the unit is connected is output with pdwBusType.
The call also retrieves a list of the type of media handled by the unit. The list is output to a DWORD vector pointed to by pdwTypes. The last element in the vector will always be "0xFFFFFFFF." The following examples illustrate a couple of typical pdwTypes vectors:
NOTES:
» The capacity of pdwTypes should reflect the fact that some combo units can handle multiple types of media.
» If a drive is taken by the "Silent Select" mechanism, which means that it is not in the drive table but is still managed, pdwClass will point to a DWORD with the special value "PRIMOSDK_SSCLASS."
Syntax
DWORD WINAPI PrimoSDK_UnitInfo2 (
DWORD dwHandle,
PDWORD pdwUnit,
PDWORD pdwTypes,
PDWORD pdwClass,
PDWORD pdwBusType,
PDWORD pdwRFU
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Output
pdwTypes
A pointer to a DWORD vector that is to be filled in with the media types handled by the unit:
- PRIMOSDK_CDROM for CD-ROM, including DDCD-ROM
- PRIMOSDK_CDR for CD-R, including DDCD-R
- PRIMOSDK_CDRW for CD-RW, including DDCD-RW
- PRIMOSDK_DVDR for DVD-R
- PRIMOSDK_DVDROM for DVD-ROM (any type)
- PRIMOSDK_DVDRAM for DVD-RAM
- PRIMOSDK_DVDRW for DVD-RW
- PRIMOSDK_DVDPRW for DVD+RW
- PRIMOSDK_DVDPR for DVD+R
- PRIMOSDK_DVDPR9 for dual-layer DVD+R
- PRIMOSDK_OTHER for other types
pdwClass
A pointer to the DWORD that is to be filled in with the class identifier assigned to the unit. Drives of different brands may be assigned to the same class.
pdwBusType
A pointer to the DWORD that is to be filled in with the type of bus to which the device is connected:
- PRIMOSDK_ATAPI = 1
- PRIMOSDK_SCSI = 2
- PRIMOSDK_1394 = 3
- PRIMOSDK_USB = 4
- PRIMOSDK_USB2 = 5
- PRIMOSDK_Unknown = 0
pdwRFU
Reserved for future use.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The requested drive does not exist.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_UnitSpeeds | go: top | section |
PrimoSDK_UnitSpeeds retrieves the various speeds at which a unit operates for various operations and media types. The speeds for operations involving CD media are output with the parameter pdwCDSpeeds, while speeds for operations involving DVD media are output with pdwDVDSpeeds. The call also reports on any additional capabilities of the unit using pdwCapabilities.
pdwCDSpeeds and pdwDVDSpeeds each point to a DWORD vector that is used for three sets of retrieved values (a set may be empty if it does not apply to the unit):
Each set in the pdwCDSpeeds and pdwDVDSpeeds vectors is terminated by 0xFFFFFFFF. The following examples illustrate two pdwCDSpeeds vectors:
NOTE: Because of the number of different speeds at which some drives operate, a vector of at least 20 DWORDs may be required for pdwCDSpeeds and at least 12 DWORDs for pdwDVDSpeeds.
Syntax
DWORD WINAPI PrimoSDK_UnitSpeeds (
DWORD dwHandle,
PDWORD pdwUnit,
PDWORD pdwCDSpeeds,
PDWORD pdwDVDSpeeds,
PDWORD pdwCapabilities
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Output
pdwCDSpeeds
A pointer to a DWORD vector that is to be filled in with the unit speeds for CD, CD-R recording, and CD-RW recording.
pdwDVDSpeeds
A pointer to a DWORD vector that is to be filled in with the unit speeds for DVD: reading, recording (e.g. DVD-R), and rewriting (e.g. DVD-RW). If the drive does not support DVD, the vector will be empty except for terminators ("0xFFFFFFFF,0xFFFFFFFF,0xFFFFFFFF").
pdwCapabilities
A pointer to a DWORD that is to be filled in with information about special drive capabilities (all of the following that apply are ORed together):
- 1st bit (0x00000001) is set if the drive supports BURN-Proof;
- 2nd bit (0x00000002) is set if the drive handles CD Text;
- 3rd bit (0x00000004) is set if the drive supports Adjustable Write Speed (AWS), and therefore accepts PRIMOSDK_BEST as a speed;
- 4th bit (0x00000008) is set if the drive supports reading DVD-ROM discs;
- 5th bit (0x00000010) is set if the drive is to open the tray after Test;
-6th bit (0x00000020) is set if the drive is to open the tray after Record.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The requested drive does not exist.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_UnitReady | go: top | section |
PrimoSDK_UnitReady tests if the unit specified with the parameter pdwUnit is ready. This function is optimized for use in timer loop while waiting for a drive to become ready.
NOTE: The unit identified with pdwUnit must be a CD or DVD drive. If pdwUnit identifies a hard-disk, board, or other unit that can be identified by SCSI triple, the function may have unpredictable results.
Syntax
DWORD WINAPI PrimoSDK_UnitReady (
DWORD dwHandle,
PDWORD pdwUnit
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Returned values
PRIMOSDK_OK
The unit is ready.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The specified unit does not exist.
PRIMOSDK_NOTREADY
The unit is not ready.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_UnitStatus | go: top | section |
PrimoSDK_UnitStatus returns the current status of the drive specified with the parameter pdwUnit, indicating whether or not the drive's most recent operation completed successfully. The function's main purpose is to allow the host application to determine the status of individual units during multi-drive operations.
If an error occured during the operation, the specified drive's most recent command code is output with pdwCommand, while the most recent Sense, ASC, and ASCQ codes (see Drive Error Codes in Chapter 4) are output with pdwSense, pdwASC, and pdwASCQ. If the operation completed successfully, the DWORDs pointed to by these parameters are left unchanged.
NOTES:
» To confirm the meaning of a drive's error codes, refer to its SCSI or ATAPI specifications.
» Before checking an operation's result with this function, call PrimoSDK_RunningStatus to see whether or not the operation is still running.
Syntax
DWORD WINAPI PrimoSDK_UnitStatus (
DWORD dwHandle,
PDWORD pdwUnit,
PDWORD pdwCommand,
PDWORD pdwSense,
PDWORD pdwASC,
PDWORD pdwASCQ
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Output
pdwCommand
A pointer to a DWORD to be filled in with the unit's most recent command code.
pdwSense
A pointer to a DWORD to be filled in with the unit's most recent Sense code.
pdwASC
A pointer to a DWORD to be filled in with the unit's most recent Additional Sense Code.
pdwASCQ
A pointer to a DWORD to be filled in with the unit's most recent Additional Sense Code Qualifier.
Returned values
PRIMOSDK_OK
The unit is not in error, meaning that the last operation completed successfully.
PRIMOSDK_BUR
The unit went into buffer underrun (the call sets pCommand, pSense, pASC and pASCQ).
PRIMOSDK_READERROR
The unit reported a reading error (the call sets pCommand, pSense, pASC and pASCQ).
PRIMOSDK_WRITEERROR
The unit reported a recording error (the call sets pCommand, pSense, pASC and pASCQ).
PRIMOSDK_UNITERROR
The unit reported an error of another type (the call sets pCommand, pSense, pASC and pASCQ).
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_SCSIERROR
A communication error occurred.
PRIMOSDK_INTERR
An internal error occured.
6.3 Drive Control | go: top |
This section covers the following calls:
PrimoSDK_MoveMedium, PrimoSDK_UnitVxBlock, PrimoSDK_UnitAIN, PrimoSDK_UnitLock, PrimoSDK_Command
These calls are used to control drive operations directly or to make settings that ensure successful recording by asserting PrimoSDK's control over the drive.
The following list illustrates the typical sequence and relevant parameter values for these functions when writing to disc or verifying a written disc:
NOTE: In the sequence shown above, the use of PrimoSDK_UnitVxBlock is required; if not used, it can cause problems in both the host application and other applications that might try to access the drive. PrimoSDK_UnitAIN and PrimoSDK_UnitLock are not required, but are recommended. Using them minimizes potential interruptions by end-users and the OS.
PrimoSDK_MoveMedium | go: top | section |
PrimoSDK_MoveMedium controls the tray or caddy in the drive specified with the parameter pdwUnit. The drive's response to the call may be to open or close the tray, to eject the caddy, or to stop the drive, depending on the values passed in dwFlags:
dwFlags | PRIMOSDK_IMMEDIATE included |
PRIMOSDK_IMMEDIATE not included |
PRIMOSDK_OPENTRAYEJECT | - call returns immediately; - drive rotation stopped; - tray opened or caddy ejected. |
- drive rotation stopped; - tray opened or caddy ejected. - call returns. |
PRIMOSDK_CLOSETRAY | - call returns immediately; - tray closed. |
- tray closed; - call returns. |
neither PRIMOSDK_OPENTRAYEJECT nor PRIMOSDK_CLOSETRAY |
- call returns immediately; - drive rotation stopped. |
- drive rotation stopped; - call returns. |
NOTES:
» If PrimoSDK_MoveMedium is called without including PRIMOSDK_IMMEDIATE in dwFlags, the function will not return until the tray movement has completed.
» If the drive rotation is stopped by calling the function without either PRIMOSDK_OPENTRAYEJECT or PRIMOSDK_CLOSETRAY, calling the function again with PRIMOSDK_OPENTRAYEJECT will immediately open the tray or eject the caddy.
Syntax
DWORD WINAPI PrimoSDK_MoveMedium (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwFlags
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwFlags
A DWORD indicating the desired drive operation:
- PRIMOSDK_OPENTRAYEJECT to open/eject the tray/caddy;
- PRIMOSDK_CLOSETRAY to close the tray (has no effect if the drive uses a caddy);
- PRIMOSDK_IMMEDIATE have the call return without waiting for the specified operation to be completed.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOTREADY
The unit is not ready to move the tray.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_UnitVxBlock | go: top | section |
PrimoSDK_UnitVxBlock uses the VxBlock.dll mechanism to enquire if the drive specified with the parameter pdwUnit is currently in use, to reserve that drive, or to release it. The result of the function is determined by the operation to perform (specified with dwFlags) and whether the drive is already in use by another application:
dwFlags | Drive not in use by another application... | Drive in use by another application... |
PRIMOSDK_TEST | - call returns PRIMOSDK_OK. | - call returns PRIMOSDK_NOTREADY; - a string provided by the using application is written to szAppName. |
PRIMOSDK_LOCK | - call returns PRIMOSDK_OK; - the drive is reserved for the calling application (all other applications will be blocked from using the drive); - the string passed in with szAppName will be used to respond to any other applications that try to use the drive. |
- call returns PRIMOSDK_NOTREADY; - a string provided by the using application is written to szAppName. |
PRIMOSDK_UNLOCK | - call returns PRIMOSDK_OK; - the drive is released (applications other than the calling application will be able to use the drive). |
- call returns PRIMOSDK_NOTREADY; - a string provided by the using application is written to szAppName. |
VxBlock, a DLL that can be redistributed, is a mandatory component of PrimoSDK that helps achieve exclusive access to a device. VxBlock knows how to handle the most common applications that can bypass exclusive access mechanisms, such as DLA (drive letter access) type applications and mastering applications written either by Sonic or third parties. Using VxBlock, PrimoSDK can retrieve which application is currently using a device, and can also disable these applications from using a device that the client intends to use.
PrimoSDK_UnitVxBlock is a required call, and is generally the first call in a typical pre-write or verify sequence (see Drive Control Sequence above) and the last in a typical post-write or verify sequence.
NOTES:
» When using this call to release a drive (dwFlags = PRIMOSDK_UNLOCK), the string in szAppName must be exactly the same as that used when the drive was reserved (dwFlags = PRIMOSDK_LOCK).
» When using this call to inquire about a drive (dwFlags = PRIMOSDK_TEST), the suggested size of szAppName is 256 bytes.
Syntax
DWORD WINAPI PrimoSDK_UnitVxBlock (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwFlags,
PBYTE szAppName
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwFlags
A DWORD specifying the type of operation:
- PRIMOSDK_TEST to inquire about the VxBlock status of the drive;
- PRIMOSDK_LOCK to reserve the drive;
- PRIMOSDK_UNLOCK to release the drive.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
szAppName
A pointer to a BYTE used for one of the following (to have PrimoSDK ignore this parameter, pass a NULL pointer):
- If dwFlags is PRIMOSDK_LOCK: to pass a string that will be used to respond to any other application that tries to use the drive;
- If the drive is already reserved by another application: to retrieve the string set by the application that reserved the drive.
Returned values
PRIMOSDK_OK
The drive is not already reserved by another application.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_INCOMPATIBLE
The drive does not have a drive letter associated with it or VXBLOCK.DLL could not be loaded.
PRIMOSDK_NOTREADY
The drive specified with pdwUnit was already reserved by another application.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_UnitAIN | go: top | section |
PrimoSDK_UnitAIN blocks or unblocks Windows' Auto Insert Notification (AIN) and file system activity for the drive specified with the parameter pdwUnit. When the activity is blocked on a drive, all operations other than those initiated by PrimoSDK are filtered out
(they return that the unit is not ready).
When AIN is enabled, it can interfere with the disc recording process by automatically executing routines when it detects that a disc has been inserted into the drive. It is therefore mandatory that AIN as well as any other drive access not performed by PrimoSDK be blocked on recording drives.
In a typical pre-write or verify sequence (see Drive Control Sequence above), PrimoSDK_UnitAIN is called after PrimoSDK_UnitVxBlock and before PrimoSDK_UnitLock; this order is reversed after the write or verify operation is completed.
NOTE: The blocking is actuated by the PxHelper driver; an error will result when running under WinASPI.
Syntax
DWORD WINAPI PrimoSDK_UnitAIN (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwFlags
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwFlags
A DWORD in which all of the following that apply are ORed together:
- PRIMOSDK_LOCK to disabled AIN and block file system activity or PRIMOSDK_UNLOCK to enable AIN and unblock file system activity;
- PRIMOSDK_FORCE_REFRESH to force the OS to refresh the media after the lock/unlock.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOAINCONTROL
The AIN control did not activate, typically because PrimoSDK is running under WinASPI instead of PxHelper.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_UnitLock | go: top | section |
PrimoSDK_UnitLock locks or unlocks the tray or the caddy on the drive specified with the parameter pdwUnit. The call is generally used to lock units before starting to record and to unlock them when the writing operations are finished (sucessfully or otherwise).
In a typical pre-write or verify sequence (see Drive Control Sequence above), PrimoSDK_UnitLock is called after PrimoSDK_UnitAIN; this order is reversed after the write or verify operation is completed.
Syntax
DWORD WINAPI PrimoSDK_UnitLock (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwFlags
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwFlags
A DWORD specifying the desired tray/caddy action:
- PRIMOSDK_LOCK to lock the tray/caddy;
- PRIMOSDK_UNLOCK to unlock the tray/caddy.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_Command | go: top | section |
PrimoSDK_Command sends a bare SCSI command to the SCSI or ATAPI unit specified with pdwUnit. While the target unit could be a CD or DVD drive, this function is primarily provided to enable the sending of commands to SCSI robotics or other special devices using the PrimoSDK ASPI layer/control (rather than having to install another layer in the system).
When used to address a drive, pdwUnit is format as described in PrimoSDK_UnitInfo. However, because robotics are not assigned a drive letter, they can only be addressed by SCSI Host/ID/LUN triple, and the least significant byte of the DWORD must be "00" (e.g. for the unit at Host 1, ID 3, Lun 0, pdwUnit points to "0x01030000"). This value does not change when the function returns.
! NOTE: Use this function with caution. The use of incorrect commands or target drives could have serious system-wide consequences.
Syntax
DWORD WINAPI PrimoSDK_Command (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwCmdLen,
PBYTE pCmd,
DWORD dwDataLen,
PBYTE pData,
DWORD dwFlag,
DWORD dwTimeOut,
PDWORD pdwSense,
PDWORD pdwASC,
PDWORD pdwASCQ
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwCmdLen
A DWORD specifying the length of the SCSI command (usually from 6 to 12 bytes).
pCmd
A pointer to the BYTE containing the actual SCSI command.
dwDataLen
A DWORD specifying the length of the data buffer, if any.
dwFlag
A DWORD giving one of the following values depending on whether or not data is transferred by the command:
- PRIMOSDK_DATAIN if data is transferred to the command from pData;
- PRIMOSDK_DATAOUT if data is transferred from the command to pData;
- PRIMOSDK_NODATA if no data is transferred.
dwTimeOut
A DWORD specifying the command timeout in milliseconds.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
pData
A pointer to the BYTE from which or to which data is transferred by the command (use a NULL pointer if no data is transferred).
Output
pdwSense
A pointer to a DWORD to be filled in with the unit's most recent Sense code.
pdwASC
A pointer to a DWORD to be filled in with the unit's most recent Additional Sense Code.
pdwASCQ
A pointer to a DWORD to be filled in with the unit's most recent Additional Sense Code Qualifier.
Returned values
PRIMOSDK_OK
The command completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_SCSIERROR
A communication error occurred or the command timed-out
PRIMOSDK_UNITERROR
The command returned a check condition (pSense, pASC, and pASCQ will point to the corresponding error triple).
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
6.4 Disc and Image Information | go: top |
This section covers the following calls:
PrimoSDK_DiscInfoEx, PrimoSDK_DiscInfo, PrimoSDK_DiscInfo2, PrimoSDK_GetDiscSpeedList, PrimoSDK_GetDiscSpeed, PrimoSDK_GetDVDType, PrimoSDK_GIInfoEx, PrimoSDK_GIInfo, PrimoSDK_TrackInfo
These calls are used to retrieve information about discs and global image files.
PrimoSDK_DiscInfoEx | go: top | section |
PrimoSDK_DiscInfoEx retrieves information about the media inside the drive specified with the parameter pdwUnit, including the type and format of the media, its erasability, the number of tracks it contains, and the number of sectors used and available. Additional information not covered by this call may be retrieved with PrimoSDK_DiscInfo2.
This function should be called before starting any recording operation to check the presence of blank discs in all the engaged recorders.
NOTES:
» This call is a fuller-featured replacement for PrimoSDK_DiscInfo, which is included in this version of PrimoSDK only to ensure backward compatibility.
» For DVD+RW media in a DVD+RW drive, the value of pdwMediumFormat will be output as PRIMOSDK_F8.
Syntax
DWORD WINAPI PrimoSDK_DiscInfoEx (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwFlags,
PDWORD pdwMediumType,
PDWORD pdwMediumFormat,
PDWORD pdwErasable,
PDWORD pdwTracks,
PDWORD pdwUsed,
PDWORD pdwFree
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwFlags
A DWORD specifying the drive mode for which to retrieve the number of free sectors available on the disc. If not given as "0," sets the drive mode to incremental or TAO instead of DAO.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
pdwMediumType
A pointer to the DWORD that is to be filled in with the type of the medium (to have PrimoSDK skip retrieval of this information, pass a NULL pointer):
- PRIMOSDK_SILVER if the disc is not recordable;
- PRIMOSDK_COMPLIANTGOLD if the disc is recordable by PrimoSDK;
- PRIMOSDK_OTHERGOLD if the disc is recordable but not usable by PrimoSDK (an unclosed disc of a different type);
- PRIMOSDK_BLANK if the disc is recordable and blank.
pdwErasable
A pointer to the DWORD that is to be filled in to indicate the media's erasability:
- if output as "1," the media can be erased by the drive in which it resides;
- if output as "0," the media cannot be erased.
pdwMediumFormat
A pointer to the DWORD that is to be filled in with the format of the media (to have PrimoSDK skip retrieval of this information, pass a NULL pointer):
PRIMOSDK_B1: Blank disc
PRIMOSDK_D1: Data Mode 1 DAO (e.g. most data CD-ROMs or typical DOS games)
PRIMOSDK_D2: Kodak Photo CD - Data multisession Mode 2 TAO
PRIMOSDK_D3: Gold Data Mode 1 - Data multisession Mode 1, closed
PRIMOSDK_D4: Gold Data Mode 2 - Data multisession Mode 2, closed
PRIMOSDK_D5: Data Mode 2 DAO (silver mastered from Corel or Toast gold)
PRIMOSDK_D6: CDRFS - Fixed packet (from Sony packet-writing solution)
PRIMOSDK_D7: Packet writing
PRIMOSDK_D8: Gold Data Mode 1 - Data multisession Mode 1, open
PRIMOSDK_D9: Gold Data Mode 2 - Data multisession Mode 2, open
PRIMOSDK_A1: Audio DAO/SAO/TAO, like most silver music discs, or a Closed Gold audio
PRIMOSDK_A2: Audio Gold disc with session not closed (TAO or SAO)
PRIMOSDK_A3: First type of Enhanced CD (aborted)
PRIMOSDK_A4: CD Extra, Blue Book standard
PRIMOSDK_A5: Audio TAO with session not written (in-progress compilation)
PRIMOSDK_M1: First track data, others audio
PRIMOSDK_M2: Mixed-mode made TAO
PRIMOSDK_M3: Kodak Portfolio (as per the Kodak standard)
PRIMOSDK_M4: Video CD (as the White Book standard)
PRIMOSDK_M5: CD-i (as the Green Book standard)
PRIMOSDK_M6: PlayStation (Sony games)
PRIMOSDK_F1: Obsolete
PRIMOSDK_F2: Obsolete for restricted overwrite DVD (DLA DVD-RW)
PRIMOSDK_F3: Completed (non-appendable) DVD (DVD-ROM or closed recordable)
PRIMOSDK_F4: Incremental DVD with appendable zone (DLA DVD-R and DVD+RW)
PRIMOSDK_F5: Layer Jump DVD-R9 Disc
PRIMOSDK_F8: Recordable DVD-R, open
PRIMOSDK_FA: DVD-RAM cartridge
PRIMOSDK_GENERICCD: Other type of CD.
pdwTracks
A pointer to the DWORD that is to be filled in with the number of tracks in the disc (to have PrimoSDK skip retrieval of this information, pass a NULL pointer). If the value at pdwMediumType is PRIMOSDK_BLANK, then the value at pdwTracks will be "0."
pdwUsed
A pointer to the DWORD that is to be filled in with the total number of sectors used on the disc (to have PrimoSDK skip retrieval of this information, pass a NULL pointer).
pdwFree
A pointer to the DWORD that is to be filled in with the total number of free sectors on the disc (to have PrimoSDK skip retrieval of this information, pass a NULL pointer). If the value at pdwMediumType is PRIMOSDK_COMPLIANTGOLD, then one sector = 2048 bytes.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_UNITERROR
The unit reported a reading error.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_DiscInfo | go: top | section |
! This call has been superceded by PrimoSDK_DiscInfoEx, and is included in PrimoSDK only to ensure backward compatibility.
PrimoSDK_DiscInfo retrieves information about the media inside the drive specified with the parameter pdwUnit, including the type and format of the media, its erasability, the number of tracks it contains, and the number of sectors used and available. Additional information not covered by this call may be retrieved with PrimoSDK_DiscInfo2.
This function should be called before starting any recording operation to check the presence of blank discs in all the engaged recorders.
NOTE: For DVD+RW media in a DVD+RW drive, the value of pdwMediumFormat will be output as PRIMOSDK_F8.
Syntax
DWORD WINAPI PrimoSDK_DiscInfo (
DWORD dwHandle,
PDWORD pdwUnit,
PDWORD pdwMediumType,
PDWORD pdwMediumFormat,
PDWORD pdwErasable,
PDWORD pdwTracks,
PDWORD pdwUsed,
PDWORD pdwFree
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Output
pdwMediumType
A pointer to the DWORD that is to be filled in with the type of the medium (to have PrimoSDK skip retrieval of this information, pass a NULL pointer):
- PRIMOSDK_SILVER if the disc is not recordable;
- PRIMOSDK_COMPLIANTGOLD if the disc is recordable by PrimoSDK;
- PRIMOSDK_OTHERGOLD if the disc is recordable but not usable by PrimoSDK (an unclosed disc of a different type);
- PRIMOSDK_BLANK if the disc is recordable and blank.
pdwErasable
A pointer to the DWORD that is to be filled in to indicate the media's erasability:
- if output as "1," the media can be erased by the drive in which it resides;
- if output as "0," the media cannot be erased.
pdwMediumFormat
A pointer to the DWORD that is to be filled in with the format of the media (to have PrimoSDK skip retrieval of this information, pass a NULL pointer):
- PRIMOSDK_B1: Blank Disc
- PRIMOSDK_D1: Data Mode 1 DAO (like MSVC++ or a typical DOS game)
- PRIMOSDK_D2: Kodak Photo CD: Data multisession Mode 2 TAO
- PRIMOSDK_D3: Gold Data Mode 1: Data multisession Mode 1, closed
- PRIMOSDK_D4: Gold Data Mode 2: Data multisession Mode 2, closed
- PRIMOSDK_D5: Data Mode 2 DAO (silver mastered from Corel or Toast gold)
- PRIMOSDK_D6: CDRFS: Fixed packet (from Sony packet-writing solution)
- PRIMOSDK_D7: Packet writing
- PRIMOSDK_D8: Gold Data Mode 1: Data multisession Mode 1, open
- PRIMOSDK_D9: Gold Data Mode 2: Data multisession Mode 2, open
- PRIMOSDK_A1: Audio DAO Silver, like almost any music disc, or Closed Gold
- PRIMOSDK_A2: Audio Gold disc not closed (TAO or SAO)
- PRIMOSDK_A3: First type of Enhanced CD (aborted)
- PRIMOSDK_A4: CD Extra, Blue Book standard
- PRIMOSDK_A5: Audio TAO tracks with session not closed
- PRIMOSDK_M1: First track Data and other audio
- PRIMOSDK_M2: Gold TAO (like the ones made with Easy-CD 16 or 32 versions)
- PRIMOSDK_M3: Kodak Portfolio (as per the Kodak standard)
- PRIMOSDK_M4: Video CD (as per the White Book standard)
- PRIMOSDK_M5: CD-i (as per the Green Book standard)
- PRIMOSDK_M6: PlayStation (Sony games)
- PRIMOSDK_F1: DVD-ROM
- PRIMOSDK_F3: Recordable DVD-R, closed
- PRIMOSDK_F8: Recordable DVD-R, open
- PRIMOSDK_FA: DVD-RAM cartridge
- PRIMOSDK_GENERICCD: Other
pdwTracks
A pointer to the DWORD that is to be filled in with the number of tracks in the disc (to have PrimoSDK skip retrieval of this information, pass a NULL pointer). If the value at pdwMediumType is PRIMOSDK_BLANK, then the value at pdwTracks will be "0."
pdwUsed
A pointer to the DWORD that is to be filled in with the total number of sectors used on the disc (to have PrimoSDK skip retrieval of this information, pass a NULL pointer).
pdwFree
A pointer to the DWORD that is to be filled in with the total number of free sectors on the disc (to have PrimoSDK skip retrieval of this information, pass a NULL pointer). If the value at pdwMediumType is PRIMOSDK_COMPLIANTGOLD, then one sector = 2048 bytes.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_UNITERROR
The unit reported a reading error.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_DiscInfo2 | go: top | section |
PrimoSDK_DiscInfo2 retrieves additional information (not covered by PrimoSDK_DiscInfoEx) about the media inside the drive specified with the parameter pdwUnit. This information may include the physical media type, as well as whether the disc has been formatted with packet-writing software and whether it is a DVD containing copy-protected content.
NOTES:
» If the disc is a Double Density CD, pdwMedium will output a pointer to the value PRIMOSDK_OTHER, while pdwMediumEx will output a pointer to either PRIMOSDK_DDCDROM, PRIMOSDK_DDCDR, or PRIMOSDK_DDCDRW. In all other circumstances the values pointed to by the two parameters will both have the same value.
» If pdwMedium is passed a NULL pointer, then pdwMediumEx must also be passed a NULL pointer.
Syntax
DWORD WINAPI PrimoSDK_DiscInfo2 (
DWORD dwHandle,
PDWORD pdwUnit,
PDWORD pdwMedium,
PDWORD pdwProtectedDVD,
PDWORD pdwFlags,
PDWORD pdwMediumEx,
PDWORD pdwRFU3
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Output
pdwMedium
A pointer to the DWORD that is to be filled in with the physical type of the media (to have PrimoSDK skip retrieval of this information, pass a NULL pointer):
- PRIMOSDK_CDROM for CD-ROM, including DDCD-ROM
- PRIMOSDK_CDR for CD-R, including DDCD-R
- PRIMOSDK_CDRW for CD-RW, including DDCD-RW
- PRIMOSDK_DVDR for DVD-R
- PRIMOSDK_DVDROM for DVD-ROM (any type)
- PRIMOSDK_DVDRAM for DVD-RAM
- PRIMOSDK_DVDRW for DVD-RW
- PRIMOSDK_DVDPRW for DVD+RW
- PRIMOSDK_DVDPR for DVD+R
- PRIMOSDK_DVDPR9 for dual-layer DVD+R
- PRIMOSDK_OTHER for other types
pdwProtectedDVD
A pointer to the DWORD that is to be filled in to indicate whether or not the media is a DVD containing copy-protected content (to have PrimoSDK skip retrieval of this information, pass a NULL pointer):
- If output as "1," the media is a DVD containing copy-protected content;
- If output as "0," the media is not a DVD containing copy-protected content.
pdwFlags
A pointer to the DWORD that is to be filled in with the following flags (to have PrimoSDK skip retrieval of this information, pass a NULL pointer):
- PRIMOSDK_PACKETWRITTEN if the media is formatted by packet writing software (currently applies only to DVD-RW).
pdwMediumEx
A pointer to the DWORD that is to be filled in with the physical type of the medium (to have PrimoSDK skip retrieval of this information, pass a NULL pointer):
- PRIMOSDK_CDROM for CD-ROM
- PRIMOSDK_CDR for CD-R
- PRIMOSDK_CDRW for CD-RW
- PRIMOSDK_DVDR for DVD-R
- PRIMOSDK_DVDROM for DVD-ROM (any type)
- PRIMOSDK_DVDRAM for DVD-RAM
- PRIMOSDK_DVDRW for DVD-RW
- PRIMOSDK_DVDPRW for DVD+RW
- PRIMOSDK_DVDPR for DVD+R
- PRIMOSDK_DDCDROM for DDCD-ROM
- PRIMOSDK_DDCDR for DDCD-R
- PRIMOSDK_DDCDRW for DDCD-RW
- PRIMOSDK_DVDPR9 for dual-layer DVD+R
- PRIMOSDK_OTHER for other types
pdwRFU3
Reserved for future use.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_UNITERROR
The unit reported a reading error.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_GetDiscSpeedList | go: top | section |
PrimoSDK_GetDiscSpeedList retrieves a list of the compatible record speeds supported by the disc in the drive specified with the parameter pdwUnit. The list is output with the DWORD vector pdwSpeedList100thX. The vector's size is allocated with dwNumSpeeds, while the actual number of speeds retrieved in the vector is output with pdwNumSpeeds.
Speeds are expressed in hundredths of "x." For example, a disc supporting nominal recording speeds of 1x, 2x, and 4x would result in output of the corresponding values 100, 200, and 400.
NOTES:
» The recommended value for dwNumSpeeds is 32.
» The speeds actually reported by a drive may differ slightly from the disc's nominal speeds. The host application is responsible for rounding, if desired.
Syntax
DWORD WINAPI PrimoSDK_GetDiscSpeedList (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwNumSpeeds,
PDWORD pdwNumSpeeds,
PDWORD pdwSpeedList100thX
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwNumSpeeds
A DWORD specifying the number of DWORDs allocated for pdwSpeedList100thX (recommended value = 32).
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Output
pdwNumSpeeds
A pointer to the DWORD that is to be filled in with the actual number of speeds returned.
pdwSpeedList100thX
A pointer to a DWORD vector that is to be filled in with the disc speeds.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_UNITERROR
The unit reported an error.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_GetDiscSpeed | go: top | section |
PrimoSDK_GetDiscSpeed retrieves the actual speed at which the drive drive specified with the parameter pdwUnit will write in response to a given requested speed. Both speeds are given in hundredths of × (the speed of a 1x drive is expressed as "100"). The requested speed is passed with dwRequestedSpeed100thX, while the actual speed is retrieved with pdwGottenSpeed100thX. If, for example, the caller specifies the requested speed as "1200" (12.00x) for a drive that writes at either 10.40x or 14.00x, pdwGottenSpeed100thX would be output as "1040" (10.40x).
NOTE: This call does not actually initiate a write operation or set the write speed of the drive.
Syntax
DWORD WINAPI PrimoSDK_GetDiscSpeed (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwRequestedSpeed100thX,
pdwGottenSpeed100thX
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
pwRequestedSpeed100thX
The requested speed in 100ths of x.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Output
pdwGottenSpeed100thX
A pointer to the DWORD that is to be filled in with the actual speed (expressed in hundredths of x) at which the specified drive would write in response to the requested speed.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_UNITERROR
The unit reported an error.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_GetDVDType | go: top | section |
PrimoSDK_GetDVDType retrieves the type of DVD media inside the drive specified with the parameter pdwUnit, and outputs it with pdwType.
NOTE: An error will result if the specified drive is locked via PrimoSDK_UnitAIN.
Syntax
DWORD WINAPI PrimoSDK_GetDVDType (
DWORD dwHandle,
PDWORD pdwUnit,
LPDWORD pdwType,
LPDWORD pdwRFU
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Output
pdwType
A pointer to the DWORD that is to be filled in with the type of DVD media in the specified unit (if both DVD-Video and DVD-Audio apply, the retrieved values will be ORed together):
- PRIMOSDK_DVDUNKNOWN if the disc type is unknown or if the media is not a DVD;
- PRIMOSDK_DVDDATA if the disc is a DVD data disc (no DVD-Video or DVD-Audio content);
- PRIMOSDK_DVDAUDIO if the disc has a DVD-Audio zone (AUDIO_TS directory);
- PRIMOSDK_DVDVIDEO if the disc has a DVD-Video zone (VIDEO_TS directory);
- PRIMOSDK_DVDSTREAM if the disc is a DVD-SR (Stream Recording).
pdwRFU
Reserved for future use.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_UNITERROR
The unit reported a reading error.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_GIInfoEx | go: top | section |
PrimoSDK_GIInfoEx retrieves format, track, sector, and media type information about the Global Image file (.GI) specified with the parameter szGIFileName.
NOTES:
» This call is a fuller-featured replacement for PrimoSDK_GIInfo, which is included in this version of PrimoSDK only to ensure backward compatibility.
» Before starting any recording operation, the caller should check the presence of blank discs in all engaged recorders.
Syntax
DWORD WINAPI PrimoSDK_GIInfoEx (
DWORD dwHandle,
PBYTE szGIFileName,
PDWORD pdwMediumFormat,
PDWORD pdwTracks,
PDWORD pdwUsed,
PDWORD pdwMediaType,
PDWORD pdwMediaTypeEx
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
szGIFileName
A pointer to a BYTE giving either the full path or the name of the Global Image file. If the full path is not specified, PrimoSDK will assume that the file is in the current working directory.
Output
pdwMediumFormat
A pointer to the DWORD that is to be filled in with the image's format, expressed as one of the values listed under pdwMediumFormat in PrimoSDK_DiscInfoEx (to have PrimoSDK skip retrieval of this information, pass a NULL pointer).
pdwTracks
A pointer to the DWORD that is to be filled in with the number of tracks in the disc (to have PrimoSDK skip retrieval of this information, pass a NULL pointer).
pdwUsed
A pointer to the DWORD that is to be filled in with the total number of sectors used on the disc (to have PrimoSDK skip retrieval of this information, pass a NULL pointer).
pdwMediaType
A pointer to the DWORD that is to be filled in with one of the following (to have PrimoSDK skip retrieval of this information, pass a NULL pointer):
- if the Global Image was created from a disc (see PrimoSDK_ReadGI), the media type (see PrimoSDK_DiscInfo) of the source disc;
- if the Global Image was created from a file set (see PrimoSDK_SaveGI), the media type specified for the image with the dwFlags parameter of PrimoSDK_NewImage or PrimoSDK_NewImageWCS.
pdwMediaTypeEx
A pointer to the DWORD that is to be filled in with one of the physical media type values listed for this parameter under PrimoSDK_DiscInfo2 (to have PrimoSDK skip retrieval of this information, pass a NULL pointer).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_FILEERROR
The file specified with szGIFileName is not found.
PRIMOSDK_INVALIDSOURCE
The file specified with szGIFileName is not a valid global image file.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_GIInfo | go: top | section |
! This call has been superceded by PrimoSDK_GIInfoEx, and is included in PrimoSDK only to ensure backward compatibility.
PrimoSDK_GIInfo retrieves format, track, and sector information about the Global Image file (.GI) specified with the parameter szGIFileName.
Syntax
DWORD WINAPI PrimoSDK_GIInfo (
DWORD dwHandle,
PBYTE szGIFileName,
PDWORD pdwMediumFormat,
PDWORD pdwTracks,
PDWORD pdwUsed
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
szGIFileName
A pointer to a BYTE giving either the full path or the name of the Global Image file. If the full path is not specified, PrimoSDK will assume that the file is in the current working directory.
Output
pdwMediumFormat
A pointer to the DWORD that is to be filled in with the image's format, expressed as one of the values listed under pdwMediumFormat in PrimoSDK_DiscInfoEx (to have PrimoSDK skip retrieval of this information, pass a NULL pointer).
pdwTracks
A pointer to the DWORD that is to be filled in with the number of tracks in the image (to have PrimoSDK skip retrieval of this information, pass a NULL pointer).
pdwUsed
A pointer to the DWORD that is to be filled in with the total number of sectors used by the image (to have PrimoSDK skip retrieval of this information, pass a NULL pointer).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_FILEERROR
The file specified with szGIFileName is not found.
PRIMOSDK_INVALIDSOURCE
The file specified with szGIFileName is not a valid global image file.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_TrackInfo | go: top | section |
PrimoSDK_TrackInfo retrieves information about a specific track in a disc or global image whose information has been previously retrieved with a disc information (PrimoSDK_DiscInfoEx) or track information(PrimoSDK_GIInfo) operation. The parameter dwHandle is used to identify the operation, while dwTrackNumber is used to specify the track. The remaining parameters are used to output the track information, including the session number, track type, pre-gap, start position, and sector length.
Syntax
DWORD WINAPI PrimoSDK_TrackInfo (
DWORD dwHandle,
DWORD dwTrackNumber,
PDWORD pdwSessionNumber,
PDWORD pdwTrackType,
PDWORD pdwPreGap,
PDWORD pdwStart,
PDWORD pdwLength
);
Parameters
Input
dwHandle
A DWORD specifying the handle (see PrimoSDK_GetHandle) used in the PrimoSDK_DiscInfoEx call or PrimoSDK_GIInfo call for the disc or image containing the track.
dwTrackNumber
A DWORD specifying the number of the track (first track = "1") about which to retrieve information.
Output
pdwSessionNumber
A pointer to the DWORD that is to be filled in with the number of the session that contains the track.
pdwTrackType
A pointer to the DWORD that is to be filled in with the type of the track:
- if "0," the type is Audio;
- if "1," the type is Data Mode1;
- if "2," the type is Data Mode2.
pdwPreGap
A pointer to the DWORD that is to be filled in with the number of sectors in the track's pre-gap.
pdwStart
A pointer to the DWORD that is to be filled in with the physical sector number at which the track begins.
pdwLength
A pointer to the DWORD that is to be filled in with the total number of sectors in the track.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized or PrimoSDK_DiscInfoEx/PrimoSDK_GIInfo has not yet been called.
PRIMOSDK_BADPARAM
dwTrackNumber is incorrect.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
6.5 Reading and Extracting from Disc | go: top |
This section covers the following calls:
PrimoSDK_ReadGI, PrimoSDK_OpenReadDisc, PrimoSDK_ReadDisc, PrimoSDK_CloseReadDisc, PrimoSDK_ExtractAudioTrack, PrimoSDK_ExtractAudioToBuffer, PrimoSDK_NextExtractAudioBuffer, PrimoSDK_CDTextInfo, PrimoSDK_CDTextInfoEJ
These calls are used to obtain data, extract audio, or retrieve CD Text information from an existing disc.
NOTE: Additional functionality for retrieving information related to tracks on Audio CDs is available via PrimoSDK's Advanced Audio calls (licensed separately from the standard version of PrimoSDK), which are documented in the Advanced Audio Addendum.
The following is a typical workflow for reading data from specific sectors of a disc:
Alternatively, PrimoSDK_ReadGI may be used to simply copy an entire source disc to a Global Image (.GI) file without first opening a read session and specifying the sectors to read.
The following is a typical workflow for extracting audio data from specific sectors on an Audio CD to a buffer:
Alternatively, PrimoSDK_ExtractAudioTrack may be used to extract an entire audio track to a Wave (.WAV) file.
PrimoSDK_ReadGI | go: top | section |
PrimoSDK_ReadGI copies an entire source disc to a Global Image (.GI) file. The source disc is specified with the parameter pdwUnitSource, and must contain a valid, unencrypted disc to copy (see PrimoSDK_DiscInfo2). The image may be copied with or without audio track pre-gaps, as specified with dwFlags. The full path or name of the destination file is specified with szGIFileName.
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
NOTE: If the file specified with szGIFileName already exists, it will be overwritten.
Syntax
DWORD WINAPI PrimoSDK_ReadGI (
DWORD dwHandle,
PDWORD pdwUnitSource,
PBYTE szGIFileName,
DWORD dwFlags
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
szGIFileName
A pointer to the BYTE specifying either the full path or the name of the newly-created Global Image file. If the full path is not specified, PrimoSDK will write the file in the current working directory.
dwFlags
A DWORD specifying whether or not to read the pre-gap of audio tracks:
- PRIMOSDK_COPYPREGAP to read the pre-gaps of audio tracks;
- PRIMOSDK_NOPREGAP to not read the pre-gaps.
Input/Output
pdwUnitSource
A pointer to a DWORD identifying the source drive by drive letter and/or SCSI Host/ID/LUN triple (see PrimoSDK_UnitInfo for the internal format of the DWORD).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or another operation is already in progress using the same handle.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOTREADY
The source drive is not ready.
PRIMOSDK_INVALIDSOURCE
The source drive does not contain a valid disc to read.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_OpenReadDisc | go: top | section |
PrimoSDK_OpenReadDisc opens a read session, preparing PrimoSDK to read sectors from a disc in the drive specified with the parameter pdwUnit. The track from which the sectors will be read is specified with dwTrack.
The read operation itself is performed by PrimoSDK_ReadDisc, after which the read session is closed with PrimoSDK_CloseReadDisc.
Syntax
DWORD WINAPI PrimoSDK_OpenReadDisc (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwTrack
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwTrack
A DWORD specifying the number of the track from which sectors will be read.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Returned values
PRIMOSDK_OK
The command completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The parameters are incorrect (e.g. the track specified with dwTrack doesn't exist).
PRIMOSDK_INTERR
An internal error occurred.
PrimoSDK_ReadDisc | go: top | section |
PrimoSDK_ReadDisc reads sectors from the track specified with the parameter dwTrack on a disc in the drive specified with pdwUnit. The starting sector is specified with dwSector, while the number of sectors to read is specified with dwSectorCount. The data is read to the buffer specified with pBf.
Before PrimoSDK_ReadDisc can be used, PrimoSDK_OpenReadDisc must be called to open a read session; the parameters pdwUnit and dwTrack must be identical for both calls. PrimoSDK_CloseReadDisc is called after the session is completed.
NOTE: This call does not return until the data is read off the disc.
Syntax
DWORD WINAPI PrimoSDK_ReadDisc (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwTrack,
DWORD dwSector,
DWORD dwSectorCount,
PBYTE pBf
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwTrack
A DWORD specifying the track number that will be read from (must be the same track as specified in PrimoSDK_OpenReadDisc when the session was opened).
dwSector
A DWORD specifying the sector index at which to start reading.
dwSectorCount
A DWORD specifying the number of sectors to read.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo). The unit must be the same as that specified in PrimoSDK_OpenReadDisc when the session was opened.
Output
pBf
A pointer to the BYTE that is the buffer for the read data.
Returned values
PRIMOSDK_OK
The command completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The parameters are incorrect (e.g. the track specified with dwTrack doesn't exist).
PRIMOSDK_INTERR
An internal error occurred.
PrimoSDK_CloseReadDisc | go: top | section |
PrimoSDK_CloseReadDisc terminates a disc read session that was opened with PrimoSDK_OpenReadDisc and frees the allocated structures. The parameters pdwUnit and dwTrack must be the same as in the PrimoSDK_OpenReadDisc call that opened the session.
Syntax
DWORD WINAPI PrimoSDK_CloseReadDisc (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwTrack
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwTrack
A DWORD specifying the track number that will be read from (must be the same track as specified in PrimoSDK_OpenReadDisc when the session was opened).
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo). The unit must be the same as that specified in PrimoSDK_OpenReadDisc when the session was opened.
Returned values
PRIMOSDK_OK
The command completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The parameters are incorrect (e.g. the track specified with dwTrack doesn't exist).
PRIMOSDK_INTERR
An internal error occurred.
PrimoSDK_ExtractAudioTrack | go: top | section |
PrimoSDK_ExtractAudioTrack extracts a track from an audio disc in the drive specified with the parameter pdwUnit. The track to extract is specified with dwNum, while the Wave file (.WAV) to which the data will be written is specified with szWaveFile. The number of sectors in the track is output with pdwSize.
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
NOTE: If the operation is aborted, the portion of the file that is already written will not be deleted.
Syntax
DWORD WINAPI PrimoSDK_ExtractAudioTrack (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwNum,
PBYTE szWaveFile,
PDWORD pdwSize
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwNum
A DWORD specifying the number of the track to extract (the first track is number 1).
szWaveFile
A pointer to the BYTE specifying the full path or name of the Wave file to which the extracted audio data is to be written. Unless the full path is given, PrimoSDK will assume that the file is in the current working directory.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Output
pdwSize
A pointer to a DWORD that will be filled in with the total number of sectors in the track.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOTREADY
The unit is not ready.
PRIMOSDK_NOSPACE
The disk does not have enough free sectors.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_ExtractAudioToBuffer | go: top | section |
PrimoSDK_ExtractAudioToBuffer is used in conjunction with PrimoSDK_NextExtractAudioBuffer to extract audio from an Audio CD to a buffer. PrimoSDK_ExtractAudioToBuffer initializes the extraction operation, using the parameter pdwUnit to specify the drive in which the CD resides. dwStartSector and dwTotalSectors identify the audio wanted from the CD, while the drive's speed during extraction is specified with dwReadSpeed.
Once the extraction has been initialized, PrimoSDK_NextExtractAudioBuffer is called as needed to pass to the process one or more buffers that have been created for the extracted audio.
This function returns immediately. To check on the progress of the operation, see PrimoSDK_RunningStatus.
Syntax
DWORD WINAPI PrimoSDK_ExtractAudioToBuffer (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwStartSector,
DWORD dwTotalSectors,
DWORD dwReadSpeed,
DWORD dwReserved1,
DWORD dwReserved2,
DWORD dwReserved3
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwStartSector
A DWORD specifying the first sector on the CD to read from.
dwTotalSectors
A DWORD specifying the number of sectors to read.
dwReadSpeed
A DWORD specifying the read speed as one of the following:
- PRIMOSDK_MAX for the highest speed supported by the drive;
- n for the actual number of the desired speed (e.g. 8 for 8x).
dwReserved1
Reserved for future use. Pass 0 for this parameter.
dwReserved2
Reserved for future use. Pass 0 for this parameter.
dwReserved3
Reserved for future use. Pass 0 for this parameter.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Returned values
PRIMOSDK_OK
The command completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or the function was called out of order.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_INTERR
An internal error occurred.
PRIMOSDK_USERABORT
The audio extraction was aborted.
PrimoSDK_NextExtractAudioBuffer | go: top | section |
PrimoSDK_NextExtractAudioBuffer is used in conjunction with PrimoSDK_ExtractAudioToBuffer to extract audio from an Audio CD to a buffer. PrimoSDK_ExtractAudioToBuffer initializes the extraction operation, after which PrimoSDK_NextExtractAudioBuffer is used to pass to the process buffers that have been created for the extracted audio.
One buffer, specified with the parameter pBuffer, is passed each time the function is called. The size of that buffer is specified with dwBufSize.
To allow efficient read streaming, the function may be called multiple times while waiting for buffers from previous calls to be filled. When the buffer specified with pBuffer is filled, the value of curSector as output by PrimoSDK_RunningStatus will exceed the value of pTargetSector as output by this function.
Syntax
DWORD WINAPI PrimoSDK_NextExtractAudioBuffer (
DWORD dwHandle,
PBYTE pBuffer,
DWORD dwBufSize,
PDWORD pExpectedSize,
PDWORD pTargetSector
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
pBuffer
A pointer to a BYTE specifying the buffer into which data is to be read.
dwBufSize
A DWORD specifying the size of pBuffer, which must be a multiple of 2352 (audio sector size).
Output
pExpectedSize
A pointer to a DWORD that will be filled in with the amount of data expected in pBuffer when it is filled. This should equal dwBufSize except for the last read of the extraction, when the value may be anything between 0 and dwBufSize.
pTargetSector
A pointer to a DWORD that will be filled in with the number of the last sector that will be read into the buffer specified with pBuffer.
Returned values
PRIMOSDK_OK
The command completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized. or called out of order
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid. (example: Buffer size not multiple of 2352)
PRIMOSDK_INTERR
An internal error occurred.
PRIMOSDK_USERABORT
The audio extraction was aborted.
PrimoSDK_CDTextInfo | go: top | section |
PrimoSDK_CDTextInfo, used after having called PrimoSDK_DiscInfoEx or PrimoSDK_GIInfo, retrieves English CD Text information for the entire disc in the drive specified with the parameter pdwUnit. The information is output with the parameters szTitle, szPerformer, and szComposer. If these three objects are empty after calling the function, the disc does not have CD Text.
NOTES:
» The recommended size for the buffers pointed to by szTitle, szPerformer, and szComposer is 2000 bytes each.
» To retrieve both English and Japanese CD Text, use PrimoSDK_CDTextInfoEJ.
Syntax
DWORD WINAPI PrimoSDK_CDTextInfo (
DWORD dwHandle,
PDWORD pdwUnit,
PBYTE szTitle,
PBYTE szPerformer,
PBYTE szComposer
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must be the same as that used when calling PrimoSDK_DiscInfoEx or PrimoSDK_GIInfo.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Output
szTitle
A pointer to a BYTE that will be filled in with a multiline string, where each line is delimited by <CR><LF>. The first line is the title for the disc, the second line is the title of the first track, the third line is the title of the second track, etc.
szPerformer
A pointer to a BYTE that will be filled in with a multiline string, where each line is delimited by <CR><LF>. The first line is the performer for the disc, the second line is the performer of the first track, the third line is the performer of the second track, etc.
szComposer
A pointer to a BYTE that will be filled in with a multiline string, where each line is delimited by <CR><LF>. The first line is the composer for the disc, the second line is the composer of the first track, the third line is the composer of the second track, etc.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or no Audio CD is started.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The specified drive does not support CD Text.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_CDTextInfoEJ | go: top | section |
PrimoSDK_CDTextInfoEJ, used after having called PrimoSDK_DiscInfoEx or PrimoSDK_GIInfo, retrieves English and Japanese CD Text information for the entire disc in the drive specified with the parameter pdwUnit.
The English information is output with the parameters szTitleE, szPerformerE, and szComposerE, while the Japanese CD Text is output in Shift JIS (double-byte) with szTitleJ, szPerformerJ, and szComposerJ. If either the English set or the Japanese set of parameters are empty after calling the function, then the disc does not contain CD Text in the corresponding language.
NOTES:
» The recommended size for the buffers pointed to by szTitleE, szPerformerE, szComposerE, szTitleJ, szPerformerJ, and szComposerJ is 2000 bytes each.
» To retrieve English CD Text only, use PrimoSDK_CDTextInfo.
Syntax
DWORD WINAPI PrimoSDK_CDTextInfoEJ (
DWORD dwHandle,
PDWORD pdwUnit,
PBYTE szTitleE,
PBYTE szPerformerE,
PBYTE szComposerE,
PBYTE szTitleJ,
PBYTE szPerformerJ,
PBYTE szComposerJ
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must be the same as that used when calling PrimoSDK_DiscInfoEx or the PrimoSDK_GIInfo.
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Output
szTitleE
A pointer to a BYTE that will be filled in with a multiline string in English, where each line is delimited by <CR><LF>. The first line is the title for the disc, the second line is the title of the first track, the third line is the title of the second track, etc.
szPerformerE
A pointer to a BYTE that will be filled in with a multiline string in English, where each line is delimited by <CR><LF>. The first line is the performer for the disc, the second line is the performer of the first track, the third line is the performer of the second track, etc.
szComposerE
A pointer to a BYTE that will be filled in with a multiline string in English, where each line is delimited by <CR><LF>. The first line is the composer for the disc, the second line is the composer of the first track, the third line is the composer of the second track, etc.
szTitleJ
Same as szTitleE, but in Japanese.
szPerformerJ
Same as szPerformerE, but in Japanese.
szComposerJ
Same as szComposerE, but in Japanese.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or no Audio CD is started.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The specified drive does not support CD Text.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
6.6 General Disc Write and Verify | go: top |
This section covers the following calls:
PrimoSDK_EraseMedium, PrimoSDK_CopyDisc, PrimoSDK_VerifyDisc, PrimoSDK_WriteGI, PrimoSDK_VerifyGI, PrimoSDK_WriteOtherCDImage, PrimoSDK_VerifyOtherCDImage
These calls are used for disc recording and verifying operations that are not specific to particular disc types. For calls related to image creation, writing, and verification for specific disc types, see the Data CD and DVD Images, Audio CD Images, and Video CD Images sections below.
PrimoSDK_EraseMedium | go: top | section |
PrimoSDK_EraseMedium erases a rewritable disc in the drive specified with the parameter pdwUnit. The type of erase operation to perform is specified with dwFlags.
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
Syntax
DWORD WINAPI PrimoSDK_EraseMedium (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwFlags
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwFlags
A DWORD specifying the type of erase operation to perform:
- PRIMOSDK_ERASEQUICK for a fast erase (TOC only);
- PRIMOSDK_ERASEFULL for a complete erase;
- PRIMOSDK_ERASELAST to erase the last session (if applicable).
Input/Output
pdwUnit
A pointer to a DWORD identifying the unit by drive letter and/or SCSI Host/ID/LUN triple (for the internal format of the DWORD, see PrimoSDK_UnitInfo).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_CopyDisc | go: top | section |
PrimoSDK_CopyDisc copies an entire source disc to one or more recording drives. The source disc is specified with the parameter pdwUnitSource, and must contain a valid, unencrypted disc to copy (see PrimoSDK_DiscInfo2). Options for the operation are specified with dwFlags.
The destination record drives are specified with a DWORD vector pointed to by pdwUnits. Each recorder must already contain a blank recordable/rewritable disc (see PrimoSDK_DiscInfoEx) with sufficient free sectors to accommodate the total used sectors of the source disc. If the number of sectors to be copied exceeds the sectors reported by PrimoSDK_DiscInfoEx as being available on the destination disc, PrimoSDK will attempt to continue writing. The write operation will fail unless there is additional unreported space on the media.
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
NOTES:
» This call is used as part of the recommended write operation sequence described in Drive Control Sequence above.
» If the source disc is "open" (not yet finalized), this function will normally make the destination disc open, as well. However, if dwFlags includes PRIMOSDK_CLOSEDISC, the destination disc will "closed," preventing the subsequent appending of additional sessions.
» If dwSpeed specifies a speed that is not supported by the destination drive, the drive will be set to record at the closest slower speed.
» The DVD+R, DVD+RW, and DVD+RAM formats do not support a "test write" mode. If a test write is attempted to a destination disc in one of those formats, this function will return PRIMOSDK_BADPARAM.
Syntax
DWORD WINAPI PrimoSDK_CopyDisc (
DWORD dwHandle,
PDWORD pdwUnits,
PDWORD pdwUnitSource,
DWORD dwFlags,
DWORD dwSpeed
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwFlags
A DWORD in which all of the following that apply are ORed together:
- PRIMOSDK_WRITE to make a real recording, or PRIMOSDK_TEST to run a test;
- PRIMOSDK_COPYPREGAP to copy the Pre-gaps of audio tracks, or PRIMOSDK_NOPREGAP to not copy the Pre-gaps
- PRIMOSDK_BURNPROOF to enable BURN-Proof (buffer underrun protection) if available on the destination drive;
- PRIMOSDK_VNR_WRITE to enable Verify-Not-Required functionality on BD-R media;
- PRIMOSDK_CLOSEDISC if the disc is to be closed so that no other session can be added.
dwSpeed
A DWORD specifying the recording speed as one of the following:
- PRIMOSDK_MAX for the highest speed supported by both the destination drive and destination media;
- n for the actual number of the desired speed (e.g. 8 for 8x);
- PRIMOSDK_BEST for drives that support Adjustable Write Speed. If the drive does not support AWS, the speed will revert to PRIMOSDK_MAX.
Input/Output
pdwUnits
A pointer to a DWORD vector identifying the destination drives by drive letter and/or SCSI Host/ID/LUN triple (see PrimoSDK_UnitInfo for the internal DWORD format).
pdwUnitSource
A pointer to a DWORD identifying the source drive by drive letter and/or SCSI Host/ID/LUN triple (see PrimoSDK_UnitInfo for the internal format of the DWORD).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized or another operation is already in progress using the same handle.
PRIMOSDK_BADUNIT
A unit specified with either pdwUnitSource or pdwUnits does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOTREADY
A drive (source or destination) is not ready
PRIMOSDK_INVALIDSOURCE
The source drive does not contain a valid disc to copy.
PRIMOSDK_INCOMPATIBLE
The destination drive contains a type of disc that is not compatible with the capabilities of the recorder.
PRIMOSDK_ITSADEMO
The operation exceeds the limits allowed by the Demo version of PrimoSDK.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_VerifyDisc | go: top | section |
PrimoSDK_VerifyDisc verifies one or more written discs against the source disc specified with the parameter pdwUnitSource. The drives containing the discs to be verified are specified with a DWORD vector pointed to by pdwUnits, while the verification speed is set with dwSpeed.
During verification, disc geometry is verified first, followed with byte-by-byte verification of every track. For audio tracks, where absolute verification is not supported by the error correction algorithms of the Red Book standard, a special proprietary algorithm is applied.
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
NOTE:
» This call is used as part of the recommended disc verify sequence described in Drive Control Sequence above.
» To check on the result of an individual verification, use PrimoSDK_UnitStatus, which returns PRIMOSDK_UNITERROR if a disc fails the verification (in which case the parameters pCommand, pSense, pASC, and pASCQ will all be set to "0").
Syntax
DWORD WINAPI PrimoSDK_VerifyDisc (
DWORD dwHandle,
PDWORD pdwUnits,
PDWORD pdwUnitSource,
DWORD dwSpeed
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
dwSpeed
A DWORD specifying the recording speed as one of the following:
- PRIMOSDK_MAX for the highest speed supported by the drive;
- n for the actual number of the desired speed (e.g. 8 for 8x).
Input/Output
pdwUnits
A pointer to a DWORD vector identifying by drive letter and/or SCSI Host/ID/LUN triple the drives containing the discs to be verified (see PrimoSDK_UnitInfo for the internal DWORD format).
pdwUnitSource
A pointer to a DWORD identifying the source drive by drive letter and/or SCSI Host/ID/LUN triple (see PrimoSDK_UnitInfo for the internal format of the DWORD).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized. or another operation is already in progress using the same handle
PRIMOSDK_BADUNIT
Either the source unit specified with pdwUnitSource or a destination unit specified with pdwUnits does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOTREADY
The source drive is not ready, or a drive specified with pdwUnits is either not ready or contains a blank.
PRIMOSDK_INVALIDSOURCE
The source drive does not contain a valid disc to verify.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_WriteGI | go: top | section |
PrimoSDK_WriteGI writes (either actually or in "test write" mode) to one or more record drives from the Global Image file specified with the parameter szGIFileName. (To write images that are not in a Global Image file, see PrimoSDK_WriteOtherCDImage.) The destination drives are specified with a DWORD vector pointed to by pdwUnits. Each recorder must already contain a blank recordable/rewritable disc (see pdwMediumType under PrimoSDK_DiscInfoEx).
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
NOTES:
» This call is used as part of the recommended write operation sequence described in Drive Control Sequence above.
» The DVD+R, DVD+RW, and DVD+RAM formats do not support a "test write" mode. If a test write is attempted to a destination disc in one of those formats, this function will return PRIMOSDK_BADPARAM.
Syntax
DWORD WINAPI PrimoSDK_WriteGI (
DWORD dwHandle,
PDWORD pdwUnits,
PBYTE szGIFileName,
DWORD dwFlags,
DWORD dwSpeed
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
szGIFileName
A pointer to the BYTE specifying the name or full path of the source Global Image file. Unless the full path is given, PrimoSDK will assume that the file is in the current working directory.
dwFlags
A DWORD in which all of the following that apply are ORed together:
- PRIMOSDK_WRITE to make a real recording, or PRIMOSDK_TEST to run a test;
- PRIMOSDK_VNR_WRITE to enable Verify-Not-Required functionality on BD-R media;
- PRIMOSDK_BURNPROOF to enable BURN-Proof (buffer underrun protection) if available on the destination drive;
dwSpeed
A DWORD specifying the recording speed as one of the following:
- PRIMOSDK_MAX for the highest speed supported by both the destination drive and destination media;
- n for the actual number of the desired speed (e.g. 8 for 8x);
- PRIMOSDK_BEST for drives that support Adjustable Write Speed. If the drive does not support AWS, the speed will revert to PRIMOSDK_MAX.
Input/Output
pdwUnits
A pointer to a DWORD vector identifying the destination drives by drive letter and/or SCSI Host/ID/LUN triple (see PrimoSDK_UnitInfo for the internal DWORD format).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or another operation is already in progress using the same handle.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOTREADY
The recorder is not ready.
PRIMOSDK_FILEERROR
The file specified with szGIFileName was not found.
PRIMOSDK_INVALIDSOURCE
The file specified with szGIFileName is not a valid Global Image.
PRIMOSDK_INVALIDMEDIUM
The target disc is not blank.
PRIMOSDK_INCOMPATIBLE
The specified Global Image is from a type of disc that is not compatible with the capabilities of the recorder.
PRIMOSDK_ITSADEMO
The operation exceeds the limits allowed by the Demo version of PrimoSDK.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_VerifyGI | go: top | section |
PrimoSDK_VerifyGI verifies one or more written discs against the Global Image file (.GI) specified with the parameter szGIFileName. The drives containing the discs to be verified are specified with a DWORD vector pointed to by pdwUnits, while the verification speed is set with dwSpeed.
During verification, disc geometry is verified first, followed with byte-by-byte verification of every track. For audio tracks, where absolute verification is not supported by the error correction algorithms of the Red Book standard, a special proprietary algorithm is applied.
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
NOTE: To check on the result of an individual verification, use PrimoSDK_UnitStatus, which returns PRIMOSDK_UNITERROR if a disc fails the verification (in which case the parameters pCommand, pSense, pASC, and pASCQ will all be set to "0").
Syntax
DWORD WINAPI PrimoSDK_VerifyGI (
DWORD dwHandle,
PDWORD pdwUnits,
PBYTE szGIFileName,
DWORD dwSpeed
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
szGIFileName
A pointer to the BYTE specifying the name or full path of the source Global Image file. Unless the full path is given, PrimoSDK will assume that the file is in the current working directory.
dwSpeed
A DWORD specifying the verification speed as one of the following:
- PRIMOSDK_MAX for the highest speed supported by the drive;
- n for the actual number of the desired speed (e.g. 8 for 8x).
Input/Output
pdwUnits
A pointer to a DWORD vector identifying by drive letter and/or SCSI Host/ID/LUN triple the drives containing the discs to be verified (see PrimoSDK_UnitInfo for the internal DWORD format).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or another operation is already in progress using the same handle.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_BADPARAM
The parameters are incorrect; the destination media may not be compatible with the Global Image.
PRIMOSDK_INVALIDSOURCE
The file specified with szGIFileName is not a valid Global Image.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_NOTREADY
A drive specified with pdwUnits is either not ready or contains a blank.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_WriteOtherCDImage | go: top | section |
PrimoSDK_WriteOtherCDImage writes (either actually or in "test write" mode) to one or more record drives from a generic ISO CD image that was created with PrimoSDK_SaveImage. (To write images that are in a Global Image file, see PrimoSDK_WriteGI.) The source image is specified with the parameter szFileName, while the destination drives are specified with a DWORD vector pointed to by pdwUnits.
Unless PRIMOSDK_TAO is included in the flags specified with dwFlags, each recorder must already contain a blank recordable/rewritable disc (see pdwMediumType under PrimoSDK_DiscInfoEx). If PRIMOSDK_TAO is specified, then the target of the record operation need not be blank as long as the disc is open (not finalized), in which case the contents of the source file will be recorded as a new track.
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
NOTES:
» This call is used as part of the recommended write operation sequence described in Drive Control Sequence above.
» The value in dwFlags must be set to match the sector size of the source image file. The most common image file is CD or DVD data at 2048 bytes per sector, which would use the value PRIMOSDK_IMAGE_M1_2048.
» To append additional ISO tracks to a disc that is not blank but is open, include the PRIMOSDK_TAO flag in dwFlags.
» The DVD+R, DVD+RW, and DVD+RAM formats do not support a "test write" mode. If a test write is attempted to a destination disc in one of those formats, this function will return PRIMOSDK_BADPARAM.
Syntax
DWORD WINAPI PrimoSDK_WriteOtherCDImage (
DWORD dwHandle,
PDWORD pdwUnits,
PBYTE szFileName,
DWORD dwFlags,
DWORD dwSpeed
);
Parameters
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
szFileName
A pointer to the BYTE specifying the full path or the name of the source image file. If the full path is not specified, PrimoSDK will assume that the file is in the current working directory.
dwFlags
A DWORD in which all of the following that apply are ORed together:
- PRIMOSDK_WRITE to make a real recording, or PRIMOSDK_TEST to run a test;
- PRIMOSDK_BURNPROOF to enable BURN-Proof (buffer underrun protection) if available on the destination drive;
- PRIMOSDK_TAO to append additional ISO tracks to a disc that is not blank but is open;
- PRIMOSDK_VNR_WRITE to enable Verify-Not-Required functionality on BD-R media;
- PRIMOSDK_CLOSEDISC to close the disc so that sessions cannot be added later;
- PRIMOSDK_IMAGE_M1_2048 to record an image in Mode 1 with a block length of 2048 bytes, PRIMOSDK_IMAGE_M2_2336 to record an image in Mode 2 with a block length of 2336 bytes, or PRIMOSDK_IMAGE_M2_2352 to record an image in Mode 2 with a block length of 2352 bytes.
dwSpeed
A DWORD specifying the recording speed as one of the following:
- PRIMOSDK_MAX for the highest speed supported by both the destination drive and destination media;
- n for the actual number of the desired speed (e.g. 8 for 8x);
- PRIMOSDK_BEST for drives that support Adjustable Write Speed. If the drive does not support AWS, the speed will revert to PRIMOSDK_MAX.
Input/Output
pdwUnits
A pointer to a DWORD vector identifying the destination drives by drive letter and/or SCSI Host/ID/LUN triple (see PrimoSDK_UnitInfo for the internal DWORD format).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or another operation is already in progress using the same handle.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOTREADY
The recorder is not ready.
PRIMOSDK_FILEERROR
The file specified with szGIFileName is not found.
PRIMOSDK_INVALIDMEDIUM
The target disc is not blank.
PRIMOSDK_ITSADEMO
The operation exceeds the limits allowed by the Demo version of PrimoSDK.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_VerifyOtherCDImage | go: top | section |
PrimoSDK_VerifyOtherCDImage verifies one or more written discs against the generic CD image specified with the parameter szFileName. The drives containing the discs to be verified are specified with a DWORD vector pointed to by pdwUnits, while the verification speed is set with dwSpeed.
During verification, disc geometry is verified first, followed with byte-by-byte verification of every track. For audio tracks, where absolute verification is not supported by the error correction algorithms of the Red Book standard, a special proprietary algorithm is applied.
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
NOTE: To check on the result of an individual verification, use PrimoSDK_UnitStatus, which returns PRIMOSDK_UNITERROR if a disc fails the verification (in which case the parameters pCommand, pSense, pASC, and pASCQ will all be set to "0").
Syntax
DWORD WINAPI PrimoSDK_VerifyOtherCDImage (
DWORD dwHandle,
PDWORD pdwUnits,
PBYTE szFileName,
DWORD dwFlags,
DWORD dwSpeed
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
szFileName
A pointer to the BYTE specifying the name or full path of the source image file. Unless the full path is given, PrimoSDK will assume that the file is in the current working directory.
dwFlags
A DWORD specifying the mode and block length of the source image:
- PRIMOSDK_IMAGE_M1_2048 to verify an image in Mode 1 with a block length of 2048 bytes;
- PRIMOSDK_IMAGE_M2_2336 to verify an image in Mode 2 with a block length of 2336 bytes;
- PRIMOSDK_IMAGE_M2_2352 to verify an image in Mode 2 with a block length of 2352 bytes.
dwSpeed
A DWORD specifying the verification speed as one of the following:
- PRIMOSDK_MAX for the highest speed supported by the drive;
- n for the actual number of the desired speed (e.g. 8 for 8x).
Input/Output
pdwUnits
A pointer to a DWORD vector identifying by drive letter and/or SCSI Host/ID/LUN triple the drives containing the discs to be verified (see PrimoSDK_UnitInfo for the internal DWORD format).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or another operation is already in progress using the same handle.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOTREADY
A drive specified with pdwUnits is either not ready or contains a blank.
PRIMOSDK_FILEERROR
The file specified with szGIFileName is not found.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
6.7 Data CD and DVD Images | go: top |
This section covers the following calls:
PrimoSDK_NewImage, PrimoSDK_NewImageWCS, PrimoSDK_AddFolder, PrimoSDK_AddFolderWCS, PrimoSDK_AddFile, PrimoSDK_AddFileWCS, PrimoSDK_AddBootable, PrimoSDK_GetSpaceUsed, PrimoSDK_SaveGI, PrimoSDK_SaveImage, PrimoSDK_WriteImage, PrimoSDK_VerifyImage, PrimoSDK_CloseImage
These calls are used to create, save, write, and verify disc images for Data CDs and for DVDs.
NOTE: Additional functionality for data discs, including streaming-related file system capabilities, is available via PrimoSDK Realtime, a set of optional StreamFS functions (documented in the StreamFS Addendum).
The following is a typical workflow for building a data disc structure and writing it to disc:
Because PrimoSDK_AddFolder, PrimoSDK_AddFolderWCS, PrimoSDK_AddFile, and PrimoSDK_AddFileWCS add elements one-at-a-time, the addition of an entire folder of subfolders and files requires the coding of a function that "walks" all the subfolders ("traverses" a directory). This function needs to be a clean recursive procedure to avoid stack overflow when adding deep directory structures.
The PrimoSDK toolkit includes code that has already been written and tested for traversing a directory. This code is present in both of the sample applications provided with PrimoSDK: Sample_C for C/C++ and Sample_VB for Visual Basic. Licensed users of PrimoSDK are free to copy this sample code.
NOTE: For example code illustrating the basic creation and writing of a simple data disc, see Data CD Example Code in Chapter 3.
PrimoSDK_NewImage | go: top | section |
PrimoSDK_NewImage initiates the building of a file structure for a Data CD or a DVD. This call is essentially the same as PrimoSDK_NewImageWCS, except that the volume name is given as an ASCII string rather than a Unicode string.
The file structure is built in the file system specified with the parameter dwFlags. As outlined in Data CD and DVD Images above, the structure is subsequently populated with files and folders, at which point it may be written to a disc in the drive specified with pdwUnits or saved as a generic image or Global Image (.GI) file.
If written to disc, the file structure may either be written as a new image or appended to an existing image (assuming this is supported by the media type of the specified disc). The parameter dwTrackToLoad gives some control over how this will happen by indicating the session (for CD) or border (for DVD) from which the existing file system structure is to be read when appending. This allows the overwriting of sessions/borders that are contiguous to the end of the disc's existing content. The highest valid value for dwTrackToLoad equals the value of pdwTracks as output by PrimoSDK_DiscInfoEx.
The following table shows the value to use for dwTrackToLoad depending on the desired outcome and the format of the disc in the drive (see values for pdwMediumFormat in PrimoSDK_DiscInfoEx):
dwTrackToLoad | Single-border media: DVD-RAM, DVD+RW, and DVD-RW restricted overwrite |
Multi-session/border media: all other media types, including DVD-RW incremental sequential |
0 | - Create a fresh volume. - The disc's existing data (if any) is overwritten. |
- Create a fresh volume - The disc's existing data (if any) is overwritten. |
1 | - Append the data structure to the volume's existing data (all data is in border 1). - Existing file system must be UDF. |
- Append the data structure in a new session/border following session/border 1. - Any existing sessions/borders 2 or higher will be overwritten. |
2, 3, etc. | Not used. | - Append the data structure in a new session/border following the session/border corresponding to the number given (e.g. session/border 2, session/border 3, etc.). - Any existing sessions/borders higher than the number given will be overwritten. |
The parameter szVolumeName is used to specify the name to use for a new volume (if dwTrackToLoad = "0") or to rename an existing volume. Only the first 11 characters of the volume label will typically be displayed when a disc made from the structure is read.
dwSwapThreshold specifies the size below which files will be copied by PrimoSDK in a swap file, while szTemp specifies the user directory for those swap files. If all files are smaller than 2GB and dwSwapThreshold is set to "0xFFFFFFFF" then a complete image will exist on the hard disk before writing to disc.
In addition to determining the file system, dwFlags is also used to specify various options, including whether or not the structure will be checked for duplication each time a file or folder is added with PrimoSDK_AddFolder, PrimoSDK_AddFolderWCS, PrimoSDK_AddFile, and/or PrimoSDK_AddFileWCS:
If the data structure initiated with this function will be saved as an image file without being written to disc, no drives need be specified with pdwUnits (the terminator "0xFFFFFFFF" is still required). In this situation, if the flag PRIMOSDK_DVDIMAGE is included in dwFlags, the result of a call to PrimoSDK_SaveGI will be a DVD image; if it is not included the result will be a CD image.
Alternatively, if drives are specified with pdwUnits and those drives contain DVD media, calling PrimoSDK_SaveGI after the data structure is built will result in a DVD image. If the drives do not contain DVD media, the result will be a CD image.
NOTES:
» The optimal value of dwSwapThreshold may vary greatly from machine to machine. A fast PC can work without swap, but usually a swap from 2KB to 8KB is fine when in presence of a large number of files. Avoid using large values of dwSwapThreshold, as this could cause the cache file to exceed available hard-disk space.
» When appending to a DVD-RW in restricted overwrite mode, a DVD+RW, or a DVD-RAM, the File System flag in dwFlags must be set to PRIMOSDK_UDF or PRIMOSDK_UDF201. If the existing file system on the media is not UDF, the function will return PRIMOSDK_ERRORLOADING.
» After a successfully completed PrimoSDK_WriteImage operation, an additional image-writing operation on different units or with different volume names may be performed without having to rebuild the image by passing the flag PRIMOSDK_RESETDRIVES as the only value in dwFlags.
» The flag PRIMOSDK_MODE2 should not be used if writing to a DVD (if it is used, PRIMOSDK_MODE1 will be substituted automatically).
» Include the optional flag PRIMOSDK_TAO in dwFlags when the structure created with this call is to be written to DVD-R DL.
Syntax
DWORD WINAPI PrimoSDK_NewImage (
DWORD dwHandle,
PDWORD pdwUnits,
PBYTE szVolumeName,
DWORD dwTrackToLoad,
DWORD dwFlags,
DWORD dwSwapThreshold,
PBYTE szTemp
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
szVolumeName
A pointer to a BYTE specifying the label of the volume, as well as some optional Primary Volume Descriptor fields, in the following format: Volume[,Publisher[,DataPreparer[,ApplicationID]]]. The maximum field length is 32 bytes for Volume and 128 bytes for the other three fields.
dwTrackToLoad
A DWORD specifying the number of the session/border to which or after which the new data structure will be appended (see table above). If "0," the disc's existing data (if any) will not be retained.
dwSwapThreshold
A DWORD specifying in KB the size below which files will be copied by PrimoSDK in a swap file generated in szTemp (e.g. if "4," then all files under 4096 bytes will be copied). The maximum value is 256; a value of 0 means that no swap file is generated. The value 0xFFFFFFFF means that all files up to 2 GB will be cached; if all files are less than 2GB, then a complete image will exist on the hard disk before writing to CD/DVD. Swap files are destroyed by PrimoSDK_CloseImage.
szTemp
A pointer to a BYTE specifying the user directory in which to generate swap files.
dwFlags
A DWORD including one File System flag (see first list below); may also contain Optional flags (see second list below):
File System flag (use only one of the following values):
- PRIMOSDK_ISOLEVEL1 for an ISO 9660 Level 1 compliant CD with folder and file names in the 8+3 format using only the A-:-Z, 0-:-9 and "_" character set;
- PRIMOSDK_ISOLEVEL2 for an ISO 9660 Level 2 compliant CD (DOS OEM characters);
- PRIMOSDK_ISOLEVEL3 for an ISO 9660 Level 3 compliant CD (DOS OEM characters, long file names);
- PRIMOSDK_JOLIET for a Microsoft Joliet compliant CD with filenames up to 106 characters in all the Windows legal character set, double characters included (MBCS);
- PRIMOSDK_UDF for a UDF 1.02 bridge file system;
- PRIMOSDK_UDF201 for a UDF 2.01 bridge file system;
- PRIMOSDK_VERSIONLESS_ISO for a file system similar to ISO 9660 level 1 with no version numbers. This is a non-compliant file system included for use only with the ETFSBOOT.COM bootable CD loader.
Optional flags (except for PRIMOSDK_RESETDRIVES, used in combination with one File System flag from the list above):
- PRIMOSDK_ORIGDATE to maintain the original date/time for all files, or PRIMOSDK_USERTIMESET to supply a date/time for all streamed files (used only for files added with PrimoSDK_AddFileStreamWCS), or PRIMOSDK_SETNOW to have all files set to the date/time at which PrimoSDK_NewImage is called (these three flags are mutually exclusive);
- PRIMOSDK_MODE1 to make a CD-ROM Mode 1 disc or a DVD, or PRIMOSDK_MODE2 to make a CD-ROM Mode 2 XA disc (these two flags are mutually exclusive);
- PRIMOSDK_TAO if the disc is written Track At Once (must not be combined with PRIMOSDK_SAO; will result in PRIMOSDK_BADPARAM error). Required for DVD multi-border (DVD-RW, DVD-R, DVD+R), and for DVD-R DL layer jump. Optional for CD-R/RW, DDCD-R/RW;
- PRIMOSDK_SAO if the disc must be written Session At Once (must not be combined with PRIMOSDK_SAO). Combined with PRIMOSDK_CLOSEDISC, this flag lets you make any type of recording. When PRIMOSDK_SAO is not specified the recording is done Track At Once;
- PRIMOSDK_CLOSEDISC if the disc must be closed to prevent the addition of any subsequent sessions;
- PRIMOSDK_CHECKDUPLI if PrimoSDK_AddFolder, PrimoSDK_AddFolderWCS, PrimoSDK_AddFile, and PrimoSDK_AddFileWCS are to check the existing data structure before adding each file or folder. The check will return an error if the file or folder already exists or the nested path has not already been created. The use of this flag could slow down the time needed to add files to the image;
- PRIMOSDK_RESETDRIVES (must be passed alone) is used only after a successfully completed PrimoSDK_WriteImage operation to prepare for an additional image-writing operation on different units or with different volume names; it allows the new operation without having to rebuild the image;
- PRIMOSDK_VIDEOCD enables the engine recognition of the VCD 2.0/SVCD directories;
- PRIMOSDK_DVDIMAGE set this if the image is to be written to a DVD. This flag is ignored if there are units in pdwUnits.
Input/Output
pdwUnits
A pointer to a DWORD vector identifying by drive letter and/or SCSI Host/ID/LUN triple the drives containing the discs to which the data structure is to be written (see PrimoSDK_UnitInfo for the internal DWORD format). The vector is terminated by 0xFFFFFFFF.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
A unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The parameters are incorrect (e.g. the track specified with dwTrackToLoad does not exist on the specified disc).
PRIMOSDK_NOTREADY
A unit is not ready.
PRIMOSDK_ERRORLOADING
Error reading the directory of the session/border specified with dwTrackToLoad.
PRIMOSDK_INVALIDMEDIUM
A target disc is neither blank nor appendable, or the appendable discs referenced with pdwUnits are not all identical.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_NewImageWCS | go: top | section |
PrimoSDK_NewImageWCS initiates the building of a file structure for a Data CD or a DVD. This call is essentially the same as PrimoSDK_NewImage, except that the volume name is given as a Unicode string rather than an ASCII string.
The file structure is built in the file system specified with the parameter dwFlags. As outlined in Data CD and DVD Images above, the structure is subsequently populated with files and folders, at which point it may be written to a disc in the drive specified with pdwUnits or saved as a generic image or Global Image (.GI) file.
If written to disc, the file structure may either be written as a new image or appended to an existing image (assuming this is supported by the media type of the specified disc). The parameter dwTrackToLoad gives some control over how this will happen by indicating the session (for CD) or border (for DVD) from which the existing file system structure is to be read when appending. This allows the overwriting of sessions/borders that are contiguous to the end of the disc's existing content. The highest valid value for dwTrackToLoad equals the value of pdwTracks as output by PrimoSDK_DiscInfoEx.
The following table shows the value to use for dwTrackToLoad depending on the desired outcome and the format of the disc in the drive (see values for pdwMediumFormat in PrimoSDK_DiscInfoEx):
dwTrackToLoad | Single-border media: DVD-RAM, DVD+RW, and DVD-RW restricted overwrite |
Multi-session/border media: all other media types, including DVD-RW incremental sequential |
0 | - Create a fresh volume. - The disc's existing data (if any) is overwritten. |
- Create a fresh volume - The disc's existing data (if any) is overwritten. |
1 | - Append the data structure to the volume's existing data (all data is in border 1). - Existing file system must be UDF. |
- Append the data structure in a new session/border following session/border 1. - Any existing sessions/borders 2 or higher will be overwritten. |
2, 3, etc. | Not used. | - Append the data structure in a new session/border following the session/border corresponding to the number given (e.g. session/border 2, session/border 3, etc.). - Any existing sessions/borders higher than the number given will be overwritten. |
The parameter szVolumeNameWCS is used to specify the name to use for a new volume (if dwTrackToLoad = "0") or to rename an existing volume. Only the first 11 characters of the volume label will typically be displayed when a disc made from the structure is read.
dwSwapThreshold specifies the size below which files will be copied by PrimoSDK in a swap file, while szTemp specifies the user directory for those swap files. If all files are smaller than 2GB and dwSwapThreshold is set to "0xFFFFFFFF" then a complete image will exist on the hard disk before writing to disc.
In addition to determining the file system, dwFlags is also used to specify various options, including whether or not the structure will be checked for duplication each time a file or folder is added with PrimoSDK_AddFolder, PrimoSDK_AddFolderWCS, PrimoSDK_AddFile, or PrimoSDK_AddFileWCS:
If the data structure initiated with this function will be saved as an image file without being written to disc, no drives need be specified with pdwUnits (the terminator "0xFFFFFFFF" is still required). In this situation, if the flag PRIMOSDK_DVDIMAGE is included in dwFlags, the result of a call to PrimoSDK_SaveGI will be a DVD image; if it is not included the result will be a CD image.
Alternatively, if drives are specified with pdwUnits and those drives contain DVD media, calling PrimoSDK_SaveGI after the data structure is built will result in a DVD image. If the drives do not contain DVD media, the result will be a CD image.
NOTES:
» The optimal value of dwSwapThreshold may vary greatly from machine to machine. A fast PC can work without swap, but usually a swap from 2KB to 8KB is fine when in presence of a large number of files. Avoid using large values of dwSwapThreshold, as this could cause the cache file to exceed available hard-disk space.
» When appending to a DVD-RW in restricted overwrite mode, a DVD+RW, or a DVD-RAM, the File System flag in dwFlags must be set to PRIMOSDK_UDF or PRIMOSDK_UDF201. If the existing file system on the media is not UDF, the function will return PRIMOSDK_ERRORLOADING.
» After a successfully completed PrimoSDK_WriteImage operation, an additional image-writing operation on different units or with different volume names may be performed without having to rebuild the image by passing the flag PRIMOSDK_RESETDRIVES as the only value in dwFlags.
» The flag PRIMOSDK_MODE2 should not be used if writing to a DVD (if it is used, PRIMOSDK_MODE1 will be substituted automatically).
» Include the optional flag PRIMOSDK_TAO in dwFlags when the structure created with this call is to be written to DVD-R DL.
Syntax
DWORD WINAPI PrimoSDK_NewImageWCS(
DWORD dwHandle,
PDWORD pdwUnits,
PWORD szVolumeNameWCS,
DWORD dwTrackToLoad,
DWORD dwFlags,
DWORD dwSwapThreshold,
PBYTE szTemp
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
szVolumeNameWCS
A pointer to a PWORD specifying the label of the volume, as well as some optional Primary Volume Descriptor fields, in one of the following formats:
- \nVolume[\nPublisher[\nDataPreparer[\nApplicationID[\nSystemID]]]]
- Volume[,Publisher[,DataPreparer[,ApplicationID]]].
The maximum field length is 32 bytes for Volume and 128 bytes for the other three fields.
dwTrackToLoad
A DWORD specifying the number of the session/border to which or after which the new data structure will be appended (see table above). If "0," the disc's existing data (if any) will not be retained.
dwSwapThreshold
A DWORD specifying in KB the size below which files will be copied by PrimoSDK in a swap file generated in szTemp (e.g. if "4," then all files under 4096 bytes will be copied). The maximum value is 256; a value of 0 means that no swap file is generated. The value 0xFFFFFFFF means that all files up to 2 GB will be cached; if all files are less than 2GB, then a complete image will exist on the hard disk before writing to CD/DVD. Swap files are destroyed by PrimoSDK_CloseImage.
szTemp
A pointer to a BYTE specifying the user directory in which to generate swap files.
dwFlags
A DWORD including one File System flag (see first list below); may also contain Optional flags (see second list below):
File System flag (use only one of the following values):
- PRIMOSDK_ISOLEVEL1 for an ISO 9660 Level 1 compliant CD with folder and file names in the 8+3 format using only the A-:-Z, 0-:-9 and "_" character set;
- PRIMOSDK_ISOLEVEL2 for an ISO 9660 Level 2 compliant CD (DOS OEM characters);
- PRIMOSDK_ISOLEVEL3 for an ISO 9660 Level 3 compliant CD (DOS OEM characters, long file names);
- PRIMOSDK_JOLIET for a Microsoft Joliet compliant CD with filenames up to 106 characters in all the Windows legal character set, double characters included (MBCS);
- PRIMOSDK_UDF for a UDF 1.02 bridge file system;
- PRIMOSDK_UDF201 for a UDF 2.01 bridge file system;
- PRIMOSDK_VERSIONLESS_ISO for a file system similar to ISO 9660 level 1 with no version numbers. This is a non-compliant file system included for use only with the ETFSBOOT.COM bootable CD loader.
Optional flags (except for PRIMOSDK_RESETDRIVES, used in combination with one File System flag from the list above):
- PRIMOSDK_ORIGDATE to maintain the original date/time for all files, or PRIMOSDK_USERTIMESET to supply a date/time for all streamed files (used only for files added with PrimoSDK_AddFileStreamWCS), or PRIMOSDK_SETNOW to have all files set to the date/time at which PrimoSDK_NewImage is called (these three flags are mutually exclusive);
- PRIMOSDK_MODE1 to make a CD-ROM Mode 1 disc or a DVD, or PRIMOSDK_MODE2 to make a CD-ROM Mode 2 XA disc (these two flags are mutually exclusive);
- PRIMOSDK_TAO if the disc is written Track At Once (must not be combined with PRIMOSDK_SAO; will result in PRIMOSDK_BADPARAM error). Required for DVD multi-border (DVD-RW, DVD-R, DVD+R), and for DVD-R DL layer jump. Optional for CD-R/RW, DDCD-R/RW;
- PRIMOSDK_SAO if the disc must be written Session At Once (must not be combined with PRIMOSDK_SAO). Combined with PRIMOSDK_CLOSEDISC, this flag lets you make any type of recording. When PRIMOSDK_SAO is not specified the recording is done Track At Once;
- PRIMOSDK_CLOSEDISC if the disc must be closed to prevent the addition of any subsequent sessions;
- PRIMOSDK_CHECKDUPLI if PrimoSDK_AddFolder, PrimoSDK_AddFolderWCS, PrimoSDK_AddFile, and PrimoSDK_AddFileWCS are to check the existing data structure before adding each file or folder. The check will return an error if the file or folder already exists or the nested path has not already been created. The use of this flag could slow down the time needed to add files to the image;
- PRIMOSDK_RESETDRIVES (must be passed alone) is used only after a successfully completed PrimoSDK_WriteImage operation to prepare for an additional image-writing operation on different units or with different volume names; it allows the new operation without having to rebuild the image;
- PRIMOSDK_VIDEOCD enables the engine recognition of the VCD 2.0/SVCD directories;
- PRIMOSDK_DVDIMAGE set this if the image is to be written to a DVD. This flag is ignored if there are units in pdwUnits.
Input/Output
pdwUnits
A pointer to a DWORD vector identifying by drive letter and/or SCSI Host/ID/LUN triple the drives containing the discs to which the data structure is to be written (see PrimoSDK_UnitInfo for the internal DWORD format). The vector is terminated by 0xFFFFFFFF.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
A unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The parameters are incorrect (e.g. the track specified with dwTrackToLoad does not exist on the specified disc).
PRIMOSDK_NOTREADY
A unit is not ready.
PRIMOSDK_ERRORLOADING
Error reading the directory of the session/border specified with dwTrackToLoad.
PRIMOSDK_INVALIDMEDIUM
A target disc is neither blank nor appendable, or the appendable discs referenced via pdwUnits are not all identical.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_AddFolder | go: top | section |
PrimoSDK_AddFolder adds a folder to a data structure. This call is essentially the same as PrimoSDK_AddFolderWCS, except that the folder name is given as an ASCII string rather than a Unicode string.
The data structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (PrimoSDK_NewImage or PrimoSDK_NewImageWCS). As outlined in Data CD and DVD Images above, after the structure is populated with folders and files it may be written to a disc or saved as a generic image or Global Image (.GI) file.
The name of the new folder is specified with szFolder. The folder's path must be fully specified except for the root, meaning that szFolder includes all parents in the path. A leading backslash is mandatory, while a trailing backslash is optional.
Only one level is added each time the function is called. If a given folder is added under another folder without first adding the higher-level folder, the operation has no effect. For instance, the folder " \Docs\Letters" cannot be added unless the folder " \Docs" has been added earlier.
The following example illustrates a sequence of calls to create two subfolders in a given folder, one of which has a sub-subfolder:
NOTES:
» If the structure already contains a folder at the path specified with szFolder, this call will have no effect. The error PRIMOSDK_ALREADYEXIST may be returned, but only if the parameter dwFlags in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call that created the structure included the flag PRIMOSDK_CHECKDUPLI.
» Valid characters for the value of szFolder are determined by the File System Flag used in the parameter dwFlags when the data structure was created with PrimoSDK_NewImage or PrimoSDK_NewImageWCS. For example, if dwFlags specified PRIMOSDK_ISOLEVEL1, the length of the folder name is limited to eight characters drawn from the ISO 9660 Level 1 character set.
Syntax
DWORD WINAPI PrimoSDK_AddFolder (
DWORD dwHandle,
PBYTE szFolder
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call with which the structure was created.
szFolder
A pointer to a BYTE specifying the folder path in MBCS. The name of the new folder must be allowed under the data structure's file system as specified in PrimoSDK_NewImage or PrimoSDK_NewImageWCS when the structure was created.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, the target data structure hasn't yet been started, or some folders in the path have not yet been added (only if PRIMOSDK_CHECKDUPLI was included in dwFlags when the structure was created with PrimoSDK_NewImage or PrimoSDK_NewImageWCS).
PRIMOSDK_BADPARAM
Folder name is incorrect or too long.
PRIMOSDK_ALREADYEXIST
The folder specified with szFolder has been already added (only if PRIMOSDK_CHECKDUPLI was included in dwFlags when the structure was created with PrimoSDK_NewImage or PrimoSDK_NewImageWCS).
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_NOSPACE
The data structure contains too many files for the system memory.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_AddFolderWCS | go: top | section |
PrimoSDK_AddFolderWCS adds a folder to a data structure. This call is essentially the same as PrimoSDK_AddFolder, except that the folder name is given as a Unicode string rather than an ASCII string.
The data structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (PrimoSDK_NewImage or PrimoSDK_NewImageWCS). As outlined in Data CD and DVD Images above, after the structure is populated with folders and files it may be written to a disc or saved as a generic image or Global Image (.GI) file.
The name of the new folder is specified with szFolder. The folder's path must be fully specified except for the root, meaning that szFolder includes all parents in the path. A leading backslash is mandatory, while a trailing backslash is optional.
Only one level is added each time the function is called. If a given folder is added under another folder without first adding the higher-level folder, the operation has no effect. For instance, the folder " \Docs\Letters" cannot be added unless the folder " \Docs" has been added earlier.
The following example illustrates a sequence of calls to create two subfolders in a given folder, one of which has a sub-subfolder:
NOTES:
» If the structure already contains a folder at the path specified with szFolder, this call will have no effect. The error PRIMOSDK_ALREADYEXIST may be returned, but only if the parameter dwFlags in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call that created the structure included the flag PRIMOSDK_CHECKDUPLI.
» Valid characters for the value of szFolder are determined by the File System Flag used in the parameter dwFlags when the data structure was created with PrimoSDK_NewImage or PrimoSDK_NewImageWCS. For example, if dwFlags specified PRIMOSDK_ISOLEVEL1, the length of the folder name is limited to eight characters drawn from the ISO 9660 Level 1 character set.
Syntax
DWORD WINAPI PrimoSDK_AddFolderWCS (
DWORD dwHandle,
PWORD szFolder
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call with which the structure was created.
szFolder
A pointer to a WORD specifying the folder path in MBCS. The name of the new folder must be allowed under the data structure's file system as specified in PrimoSDK_NewImage or PrimoSDK_NewImageWCS when the structure was created.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, the target data structure hasn't yet been started, or some folders in the path have not yet been added (only if PRIMOSDK_CHECKDUPLI was included in dwFlags when the structure was created with PrimoSDK_NewImage or PrimoSDK_NewImageWCS).
PRIMOSDK_BADPARAM
Folder name is incorrect or too long.
PRIMOSDK_ALREADYEXIST
The folder specified with szFolder has been already added (only if PRIMOSDK_CHECKDUPLI was included in dwFlags when the structure was created with PrimoSDK_NewImage or PrimoSDK_NewImageWCS).
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_NOSPACE
The data structure contains too many files for the system memory.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_AddFile | go: top | section |
PrimoSDK_AddFile adds a file to a data structure. This call is essentially the same as PrimoSDK_AddFileWCS, except that the source and destination paths are given as ASCII strings rather than Unicode strings.
The data structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (PrimoSDK_NewImage or PrimoSDK_NewImageWCS). As outlined in Data CD and DVD Images above, after the structure is populated with folders and files it may be written to a disc or saved as a generic image or Global Image (.GI) file.
The name of the source file is specified with szSourceFile. The file's path must be fully specified, including its root. The name of the file as it is to appear in the data structure is specified with the parameter szFileOnCD. The file's path must be fully specified except for the root; a leading backslash is mandatory.
Only one level is added each time the function is called. If a given file is added without first adding the folder that is to contain it, the operation has no effect. For instance, the file " \Docs\Letter1.txt" cannot be added unless the folder " \Docs" has been added earlier.
The following two examples illustrate typical uses of this function:
NOTE: If the structure already contains a file at the path specified with szFileOnCD, this call will have no effect. The error PRIMOSDK_ALREADYEXIST may be returned, but only if the parameter dwFlags in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call that created the structure included the flag PRIMOSDK_CHECKDUPLI.
Syntax
DWORD WINAPI PrimoSDK_AddFile (
DWORD dwHandle,
PBYTE szFileOnCD,
PBYTE szSourceFile
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call with which the structure was created.
szFileOnCD
A pointer to a BYTE specifying in MBCS the path of the file as it will appear in the data structure.
szSourceFile
A pointer to a BYTE specifying the complete path of the source file.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, the target data structure hasn't yet been started, or some folders in the path have not yet been added (only if PRIMOSDK_CHECKDUPLI was included in dwFlags when the structure was created with PrimoSDK_NewImage or PrimoSDK_NewImageWCS).
PRIMOSDK_BADPARAM
A file name is incorrect or too long.
PRIMOSDK_ALREADYEXIST
A file already exists at the path specified with szFileOnCD (only if PRIMOSDK_CHECKDUPLI was included in dwFlags when the structure was created with PrimoSDK_NewImage or PrimoSDK_NewImageWCS).
PRIMOSDK_NOTREADABLE
The source file specified with szSourceFile is not found or not readable.
PRIMOSDK_FILEERROR
The added file is invalid.
PRIMOSDK_FILETOOLARGE
The added file is bigger than 9.99 GB for UDF or 4 GB for ISO.
PRIMOSDK_NOSPACE
The data structure contains too many files for the system memory.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occurred.
PrimoSDK_AddFileWCS | go: top | section |
PrimoSDK_AddFileWCS adds a file to a data structure. This call is essentially the same as PrimoSDK_AddFile, except that the source and destination paths are given as Unicode strings rather than ASCII strings.
The data structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (PrimoSDK_NewImage or PrimoSDK_NewImageWCS). As outlined in Data CD and DVD Images above, after the structure is populated with folders and files it may be written to a disc or saved as a generic image or Global Image (.GI) file.
The name of the source file is specified with szSourceFile. The file's path must be fully specified, including its root. The name of the file as it is to appear in the data structure is specified with the parameter szFileOnCD. The file's path must be fully specified except for the root; a leading backslash is mandatory.
Only one level is added each time the function is called. If a given file is added without first adding the folder that is to contain it, the operation has no effect. For instance, the file " \Docs\Letter1.txt" cannot be added unless the folder " \Docs" has been added earlier.
The following two examples illustrate typical uses of this function:
NOTE: If the structure already contains a file at the path specified with szFileOnCD, this call will have no effect. The error PRIMOSDK_ALREADYEXIST may be returned, but only if the parameter dwFlags in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call that created the structure included the flag PRIMOSDK_CHECKDUPLI.
Syntax
DWORD WINAPI PrimoSDK_AddFileWCS (
DWORD dwHandle,
PWORD szFileOnCD,
PWORD szSourceFile
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call with which the structure was created.
szFileOnCD
A pointer to a WORD specifying in MBCS the path of the file as it will appear in the data structure.
szSourceFile
A pointer to a WORD specifying the complete path of the source file.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, the target data structure hasn't yet been started, or some folders in the path have not yet been added (only if PRIMOSDK_CHECKDUPLI was included in dwFlags when the structure was created with PrimoSDK_NewImage or PrimoSDK_NewImageWCS).
PRIMOSDK_BADPARAM
A file name is incorrect or too long.
PRIMOSDK_ALREADYEXIST
A file already exists at the path specified with szFileOnCD (only if PRIMOSDK_CHECKDUPLI was included in dwFlags when the structure was created with PrimoSDK_NewImage or PrimoSDK_NewImageWCS).
PRIMOSDK_NOTREADABLE
The source file specified with szSourceFile is not found or not readable.
PRIMOSDK_FILEERROR
The added file is invalid.
PRIMOSDK_FILETOOLARGE
The added file is bigger than 9.99 GB for UDF or 4 GB for ISO.
PRIMOSDK_NOSPACE
The data structure contains too many files for the system memory.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occurred.
PrimoSDK_AddBootable | go: top | section |
PrimoSDK_AddBootable adds to an existing data structure a separate boot image file compliant with the El Torito specification. The data structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (see PrimoSDK_NewImage or PrimoSDK_NewImageWCS).
The boot image file to add to the structure is specified with szBootImageFile. This file allows a computer whose system BIOS is capable of supporting a bootable CD-ROM to reboot from a disc made from the structure. The type of bootable image specified with dwFlags determines the behavior at the time of reboot:
Image type | Reboot behavior |
Floppy disk | - CD/DVD drive boots as drive A, original drive A will become drive B, and the original drive B will be unavailable; - "floppy image" stored on disc is booted. |
Hard disk | - CD/DVD drive boots as drive C and all hard disk drive letters will be shifted up one letter; - "hard disk image" stored on disc is booted. |
"No emulation" | - uses a private loader; - the boot image is loaded into memory and executed. |
This function must be called after all the desired folders and files to be included in the bootable floppy disk image have been added to the structure with PrimoSDK_AddFolder, PrimoSDK_AddFolderWCS, PrimoSDK_AddFile, and/or PrimoSDK_AddFileWCS. As with any other data structure, the structure may subsequently be written to a disc or saved as a generic image or Global Image (.GI) file.
Syntax
DWORD WINAPI PrimoSDK_AddBootable (
DWORD dwHandle,
PBYTE szBootImageFile,
DWORD dwFlags
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call with which the structure was created.
szBootImageFile
A pointer to a BYTE specifying a path for the boot image file to add to the structure.
dwFlags
A DWORD specifying one of the values for the type of bootable image:
- 144 for 1.44 floppy images;
- 288 for 2.88 floppy images;
- PRIMOSDK_HD for Hard Drive images;
- PRIMOSDK_NOEMULATION for a special boot image which uses a private loader.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized or the data structure hasn't yet been started.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOTREADABLE
The boot image file is not found or not readable.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_GetSpaceUsed | go: top | section |
PrimoSDK_GetSpaceUsed calculates the number of free sectors needed to write the current data structure to a disc. The data structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (PrimoSDK_NewImage or PrimoSDK_NewImageWCS).
The format (and thus the sector size) on which the call bases its calculations is determined by the settings that were used in dwFlags when the structure was created. The result of the calculation, output with pdwSize, reflects not only the space required for data within files but also for overhead (file system, lead in/out, etc.). By subtracting the value of pdwSize from the value of pdwFree as output by PrimoSDK_DiscInfoEx (or PrimoSDK_DiscInfo), it's possible to determine how much additional data, if any, may be added to the current data structure.
This call also outputs (with pdwLastSector) the last sector that would be written to if the current data structure were written to a disc. Since all drives that were specified with pdwUnits when the data structure was created must contain identical media, this sector number applies to all destination media. The destination media will be assumed to be blank if the drives are empty or if no drives were specified when the data structure was created (i.e. the structure is to be written to an image file).
Syntax
DWORD WINAPI PrimoSDK_GetSpaceUsed(
DWORD dwHandle,
PDWORD pdwSize,
PDWORD pdwLastSector
);
Parameters
Input
dwHandle
A DWORD specifying the operation handle
Output
pdwSize
A pointer to the DWORD that will be filled in with the number of sectors required to write the data structure to disc (data + metadata).
pdwLastSector
A pointer to the DWORD that will be filled in with the address of the last sector that would be written to if the data structure were written to disc.
Returned values
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, the target data structure hasn't yet been started, or some folders in the path have not yet been added (only if PRIMOSDK_CHECKDUPLI was included in dwFlags when the structure was created with PrimoSDK_NewImage or PrimoSDK_NewImageWCS).
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_SaveGI | go: top | section |
PrimoSDK_SaveGI writes a data structure to a Global Image file. The structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (see PrimoSDK_NewImage or PrimoSDK_NewImageWCS). The file to which the image is written is specified with szGIFileName, while the size (in sectors) that would be required to record the image to a blank disc (see PrimoSDK_WriteGI) is output with pdwSize.
The type (CD or DVD) of image saved by this call is determined by settings in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call that created the structure to be saved.
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
NOTE: This function does not engage any recorder.
Syntax
DWORD WINAPI PrimoSDK_SaveGI (
DWORD dwHandle,
PBYTE szGIFileName,
PDWORD pdwSize
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call with which the structure was created.
szGIFileName
A pointer to a BYTE giving either the full path or the name of the Global Image file. If the full path is not specified, PrimoSDK will assume that the file is in the current working directory.
Output
pdwSize
A pointer to the DWORD that is to be filled in with the total sectors required to record the newly-created Global Image to a blank disc.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, the data structure hasn't yet been started, or the data structure is empty.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOSPACE
The hard disk disk does not have enough free sectors for the file.
PRIMOSDK_TMPOVERFLOW
A temporary file went into overflow.
PRIMOSDK_DVDSTRUCTERROR
The data structure includes a VIDEO_TS or AUDIO_TS folder that is not compliant with DVD-Video or DVD-Audio rules (DVD version only).
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_SaveImage | go: top | section |
PrimoSDK_SaveImage writes the current data structure to a generic ISO image file. The structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (see PrimoSDK_NewImage or PrimoSDK_NewImageWCS). The file to which the image is written is specified with szGIFileName, while the size (in sectors) that would be required to record the image to a blank disc (see PrimoSDK_WriteOtherCDImage) is output with pdwSize.
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
NOTE: This function does not engage any recorder.
Syntax
DWORD WINAPI PrimoSDK_SaveImage (
DWORD dwHandle,
PBYTE szFileName,
PDWORD pdwSize
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call with which the structure was created.
szGIFileName
A pointer to a BYTE giving either the full path or the name of the generic image file. If the full path is not specified, PrimoSDK will assume that the file is in the current working directory.
Output
pdwSize
A pointer to the DWORD that is to be filled in with the total sectors required to record the newly-created generic image to a blank disc.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, the data structure hasn't yet been started, or the data structure is empty.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOSPACE
The hard disk disk does not have enough free sectors for the file.
PRIMOSDK_TMPOVERFLOW
A temporary file went into overflow.
PRIMOSDK_DVDSTRUCTERROR
The data structure includes a VIDEO_TS or AUDIO_TS folder that is not compliant with DVD-Video or DVD-Audio rules (DVD version only).
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_WriteImage | go: top | section |
PrimoSDK_WriteImage writes a data structure to one or more discs, either actually or in "test write" mode. The structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (see PrimoSDK_NewImage or PrimoSDK_NewImageWCS). The drives on which the discs will be recorded are those specified with pdwUnits in that same PrimoSDK_NewImage or PrimoSDK_NewImageWCS call. Each recorder must already contain a blank recordable/rewritable disc (see pdwMediumType under PrimoSDK_DiscInfoEx).
The "test write" mode is specified with dwFlags, and the record speed is specified with dwSpeed. The total sectors that will be used in recording the structure to disc is output with pdwSize.
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
NOTES:
» This call is used as part of the recommended write operation sequence described in Drive Control Sequence above.
» Until the data structure is terminated with PrimoSDK_CloseImage, this function may be called multiple times to record the image in multiple passes.
» If dwSpeed specifies a speed that is not supported by the destination drive, the drive will be set to record at the closest slower speed.
» The DVD+R, DVD+RW, and DVD+RAM formats do not support a "test write" mode. If a test write is attempted to a destination disc in one of those formats, this function will return PRIMOSDK_BADPARAM.
Syntax
DWORD WINAPI PrimoSDK_WriteImage (
DWORD dwHandle,
DWORD dwFlags,
DWORD dwSpeed,
PDWORD pdwSize
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call with which the structure was created.
dwFlags
A DWORD in which all of the following that apply are ORed together:
- PRIMOSDK_WRITE to make a real recording, or PRIMOSDK_TEST to run a test;
- PRIMOSDK_BURNPROOF to enable BURN-Proof (buffer underrun protection) if available on the destination drive;
- PRIMOSDK_DVDPRQUICK to not force a 30mm Lead Out when recording to DVD+R;
- PRIMOSDK_VNR_WRITE to enable Verify-Not-Required functionality on BD-R media;
- PRIMOSDK_ALLOW_NONSTANDARD_LAYER to allow non-compliant layer break on DVD Video.
- PRIMOSDK_DVDRWCOMPAT to close DVD-RW discs in most compatible mode.
dwSpeed
A DWORD specifying the recording speed as one of the following:
- PRIMOSDK_MAX for the highest speed supported by both the destination drive and destination media;
- n for the actual number of the desired speed (e.g. 8 for 8x);
- PRIMOSDK_BEST for drives that support Adjustable Write Speed. If the drive does not support AWS, the speed will revert to PRIMOSDK_MAX.
Input/Output
pdwSize
A pointer to the DWORD that is to be filled in with the total sectors required to record the image to disc.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, the data structure hasn't yet been started, or the data structure is empty.
PRIMOSDK_BADPARAM
The parameters in the function are incorrect, or no drives have been specified with pdwUnits in PrimoSDK_NewImage or PrimoSDK_NewImageWCS.
PRIMOSDK_NOTREADY
One or more units are not ready.
PRIMOSDK_TMPOVERFLOW
A temporary file went into overflow.
PRIMOSDK_DVDSTRUCTERROR
The data structure includes a VIDEO_TS or AUDIO_TS folder that is not compliant with DVD-Video or DVD-Audio rules (DVD version only).
PRIMOSDK_ITSADEMO
The operation exceeds the limits allowed by the Demo version of PrimoSDK.
PRIMOSDK_FILEERROR
A file that was added to the data structure can no longer be found.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_VerifyImage | go: top | section |
PrimoSDK_VerifyImage verifies one or more written discs against the current data structure. The structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (see PrimoSDK_NewImage or PrimoSDK_NewImageWCS). The drives containing the discs to be verified are those specified with pdwUnits in that same PrimoSDK_NewImage or PrimoSDK_NewImageWCS call. The verification speed is set with dwSpeed.
This function is used after PrimoSDK_WriteImage and before the data structure is terminated with PrimoSDK_CloseImage. The call returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus.
NOTE: To check on the result of an individual verification, use PrimoSDK_UnitStatus, which returns PRIMOSDK_UNITERROR if a disc fails the verification (in which case the parameters pCommand, pSense, pASC, and pASCQ will all be set to "0").
Syntax
DWORD WINAPI PrimoSDK_VerifyImage (
DWORD dwHandle,
DWORD dwSpeed
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewImage or PrimoSDK_NewImageWCS call with which the structure was created.
dwSpeed
A DWORD specifying the verification speed as one of the following:
- PRIMOSDK_MAX for the highest speed supported by the drive;
- n for the actual number of the desired speed (e.g. 8 for 8x).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, the data structure hasn't yet been started, or the data structure is empty.
PRIMOSDK_BADPARAM
The parameters in the function are incorrect, or no drives have been specified with pdwUnits in PrimoSDK_NewImage or PrimoSDK_NewImageWCS.
PRIMOSDK_NOTREADY
The unit is not ready.
PRIMOSDK_TMPOVERFLOW
A temporary file went into overflow.
PRIMOSDK_DVDSTRUCTERROR
The data structure includes a VIDEO_TS or AUDIO_TS folder that is not compliant with DVD-Video or DVD-Audio rules (DVD version only).
PRIMOSDK_FILEERROR
A file that was added to the data structure can no longer be found.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_CloseImage | go: top | section |
PrimoSDK_CloseImage is required to terminate and free the resources allocated to a data structure created with PrimoSDK_NewImage or PrimoSDK_NewImageWCS when that structure is no longer needed. The structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created.
Syntax
DWORD WINAPI PrimoSDK_CloseImage (
DWORD dwHandle
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in thePrimoSDK_NewImage or PrimoSDK_NewImageWCS call with which the structure was created.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or the data structure hasn't yet been started.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
6.8 Audio CD Images | go: top |
This section covers the following calls:
PrimoSDK_NewAudio, PrimoSDK_AddAudioTrack, PrimoSDK_AddCDText, PrimoSDK_AddCDTextEJ, PrimoSDK_WriteAudio, PrimoSDK_CloseAudio, PrimoSDK_WriteAudioTrack
These calls are used to create Audio CDs.
NOTE: Additional functionality related to Audio CDs is available via PrimoSDK's Advanced Audio calls (licensed separately from the standard version of PrimoSDK), which are documented in the Advanced Audio Addendum.
PrimoSDK supports two methods for creating audio CDs:
The following is a typical workflow for a Disc-at-Once Audio CD:
As shown in the following table, the calls used to start an Audio CD structure and populate it with individual tracks vary depending on both the PrimoSDK version used (see PrimoSDK Options in Chapter 1) and the format of the source audio files that will be included on the CD:
PrimoSDK | PrimoSDKPlus | PrimoSDK with Advanced Audio | PrimoSDKPlus with Advanced Audio | |
.WAV | start structure: PrimoSDK_NewAudio add tracks: PrimoSDK_AddAudioTrack |
start structure: PrimoSDK_NewAudio add tracks: PrimoSDK_AddAudioTrack |
start structure: PrimoSDK_NewAudio or PrimoSDK_NewAudioPlaylist add tracks: PrimoSDK_AddAudioTrackEx or PrimoSDK_AddAudioTrack |
start structure: PrimoSDK_NewAudio or PrimoSDK_NewAudioPlaylist add tracks: PrimoSDK_AddAudioTrackEx or PrimoSDK_AddAudioTrack |
.M4A | N.A. | start structure: PrimoSDK_NewAudio add tracks: PrimoSDK_AddAudioTrack |
start structure: PrimoSDK_NewAudio or PrimoSDK_NewAudioPlaylist add tracks: PrimoSDK_AddAudioTrackEx or PrimoSDK_AddAudioTrack |
start structure: PrimoSDK_NewAudio or PrimoSDK_NewAudioPlaylist add tracks: PrimoSDK_AddAudioTrackEx or PrimoSDK_AddAudioTrack |
.MP3 | N.A. | start structure: PrimoSDK_NewAudio add tracks: PrimoSDK_AddAudioTrack |
N.A. | start structure: PrimoSDK_NewAudio or PrimoSDK_NewAudioPlaylist add tracks: PrimoSDK_AddAudioTrackEx or PrimoSDK_AddAudioTrack |
.WMA (no DRM) |
N.A. | start structure: PrimoSDK_NewAudio add tracks: PrimoSDK_AddAudioTrack |
start structure: PrimoSDK_NewAudio or PrimoSDK_NewAudioPlaylist add tracks: PrimoSDK_AddAudioTrackEx or PrimoSDK_AddAudioTrack |
start structure: PrimoSDK_NewAudio or PrimoSDK_NewAudioPlaylist add tracks: PrimoSDK_AddAudioTrackEx or PrimoSDK_AddAudioTrack |
.WMA (with DRM) |
N.A. | N.A. | start structure: PrimoSDK_NewAudioPlaylist add tracks: PrimoSDK_AddAudioTrackEx or PrimoSDK_AddAudioTrack |
start structure: PrimoSDK_NewAudioPlaylist add tracks: PrimoSDK_AddAudioTrackEx or PrimoSDK_AddAudioTrack |
NOTES:
» QuickTime is required for .M4A support.
» If using PrimoSDK's Advanced Audio functions (licensed separately from the standard version of PrimoSDK) audio may also be added to a CD Audio structure from a stream rather than a file; see PrimoSDK_AddAudioStream.
» For example code illustrating the creation and writing of a simple audio disc, see Audio CD Example Code in Chapter 3.
PrimoSDK_NewAudio | go: top | section |
PrimoSDK_NewAudio initiates the building of a structure for an Audio CD image. As outlined in Audio CD Workflow, the structure is subsequently populated with audio tracks, at which point it may be written to a disc in the drive specified with pdwUnits.
NOTES:
» Some versions of PrimoSDK also allow an Audio CD structure to be created with PrimoSDK_NewAudioPlaylist, which supports Windows Media Digital Rights Management when using .WMA source files (see Audio CD Workflow).
» To record an Audio CD track-by-track without first building a structure for the disc, see PrimoSDK_WriteAudioTrack.
Syntax
DWORD WINAPI PrimoSDK_NewAudio (
DWORD dwHandle,
PDWORD pdwUnits
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
Input/Output
pdwUnits
A pointer to a DWORD vector identifying the destination drives by drive letter and/or SCSI Host/ID/LUN triple (see PrimoSDK_UnitInfo for the internal DWORD format).
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
A unit specified with pdwUnit does not exist.
PRIMOSDK_NOTREADY
A unit is not ready.
PRIMOSDK_INVALIDMEDIUM
One or more target discs is not a blank CD-R or CD-RW.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_AddAudioTrack | go: top | section |
PrimoSDK_AddAudioTrack adds a track to an Audio CD structure. A fuller-featured alternative to this call is PrimoSDK_AddAudioTrackEx, available to licensees of PrimoSDK's Advanced Audio functions (see Advanced Audio Addendum Chapter 7).
The Audio CD structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created. Audio CD structures are created either with PrimoSDK_NewAudio or, for support of Windows Media Digital Rights Management when using .WMA source files, with PrimoSDK_NewAudioPlaylist (available only if the PrimoSDK license includes Advanced Audio).
As outlined in Audio CD Workflow, after the structure is populated with tracks it may be written to a disc, with the tracks sequenced in the order they were added.
The audio file to add to the Audio CD structure is specified with szTrack. If the PrimoSDK DLL is PrimoSDK.DLL, this file must be a Wave (.WAV) file. If the PrimoSDK DLL is PXSDKPLS.DLL, the file may be in Wave (.WAV), MPEG-1 Layer 3 (.mp3), or Windows Media Audio (.wma) format.
The pregap for the track is specified with dwPregap. When the call executes, the size (in sectors) of the added track is output with pdwSize.
NOTE: If your license includes PrimoSDK's Advanced Audio functions, see PrimoSDK_AddAudioTrackEx instead of this call.
Syntax
DWORD WINAPI PrimoSDK_AddAudioTrack (
DWORD dwHandle,
PBYTE szTrack,
DWORD dwPreGap,
PDWORD pdwSize
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewAudio call with which the Audio CD structure was created.
szTrack
A pointer to a BYTE specifying the complete path of the audio source file for the track.
dwPregap
A DWORD specifying the track's pregap in sectors. The entire pregap is silent. The first track (first song) will always have a pregap of 150 blocks (regardless of the value passed with this parameter).
Output
pdwSize
A pointer to the DWORD that is to be filled in with the size in sectors of the file specified with szTrack.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or no Audio CD structure has been started.
PRIMOSDK_BADPARAM
The file path specified with szTrack is incorrect, or the file is not valid.
PRIMOSDK_FILEERROR
The file specified with szTrack was not found.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_AddCDText | go: top | section |
PrimoSDK_AddCDText adds English-only CD Text information (title, performer, and composer) to an Audio CD stucture. The structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created. Audio CD structures are created either with PrimoSDK_NewAudio or, for support of Windows Media Digital Rights Management when using .WMA source files, with PrimoSDK_NewAudioPlaylist (available only if the PrimoSDK license includes Advanced Audio).
The CD Text information, specified with szTitle, szPerformer, and szComposer, covers both the disc-level information and the information for each individual track.
As outlined in Audio CD Workflow above, this function is called after the structure is populated with tracks and before it is written to a disc.
NOTE: The maximum size of szTitle, szPerformer, and szComposer is 2000 bytes each.
Syntax
DWORD WINAPI PrimoSDK_AddCDText (
DWORD dwHandle,
DWORD dwFlags,
PBYTE szTitle,
PBYTE szPerformer,
PBYTE szComposer
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewAudio call with which the Audio CD structure was created.
dwFlags
Reserved for future use. Pass 0 for this parameter.
szTitle
A pointer to a BYTE containing a multiline string in English, where each line is delimited by <CR><LF>. The first line is the title for the disc, the second line is the title of the first track, the third line is the title of the second track, etc.
szPerformer
A pointer to a BYTE containing a multiline string in English, where each line is delimited by <CR><LF>. The first line is the performer for the disc, the second line is the performer of the first track, the third line is the performer of the second track, etc.
szComposer
A pointer to a BYTE containing a multiline string in English, where each line is delimited by <CR><LF>. The first line is the composer for the disc, the second line is the composer of the first track, the third line is the composer of the second track, etc.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or no Audio CD structure has been started.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_AddCDTextEJ | go: top | section |
PrimoSDK_AddCDTextEJ adds English and Japanese CD Text information (title, performer, and composer) to an Audio CD stucture. The structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created. Audio CD structures are created either with PrimoSDK_NewAudio or, for support of Windows Media Digital Rights Management when using .WMA source files, with PrimoSDK_NewAudioPlaylist (available only if the PrimoSDK license includes Advanced Audio).
The CD Text information covers both the disc-level information and the information for each individual track. English information is specified with szTitleE, szPerformerE, and szComposerE, each of which is limited to 2000 bytes. Japanese information is specified with szTitleJ, szPerformerJ, and szComposerJ. The Japanese strings, each of which is limited to 2000 bytes, must be passed in Shift JIS (double-byte).
As outlined in Audio CD Workflow above, this function is called after the structure is populated with tracks and before it is written to a disc.
Syntax
DWORD WINAPI PrimoSDK_AddCDTextEJ (
DWORD dwHandle,
DWORD dwFlags,
PBYTE szTitleE,
PBYTE szPerformerE,
PBYTE szComposerE,
PBYTE szTitleJ,
PBYTE szPerformerJ,
PBYTE szComposerJ
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewAudio call with which the Audio CD structure was created.
dwFlags
Reserved for future use. Pass 0 for this parameter.
szTitleE
A pointer to a BYTE containing a multiline string in English, where each line is delimited by <CR><LF>. The first line is the title for the disc, the second line is the title of the first track, the third line is the title of the second track, etc.
szPerformerE
A pointer to a BYTE containing a multiline string in English, where each line is delimited by <CR><LF>. The first line is the performer for the disc, the second line is the performer of the first track, the third line is the performer of the second track, etc.
szComposerE
A pointer to a BYTE containing a multiline string in English, where each line is delimited by <CR><LF>. The first line is the composer for the disc, the second line is the composer of the first track, the third line is the composer of the second track, etc.
szTitleJ
Same as szTitleE, but in Japanese.
szPerformerJ
Same as szPerformerE, but in Japanese.
szComposerJ
Same as szComposerE, but in Japanese.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or no Audio CD structure has been started.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_WriteAudio | go: top | section |
PrimoSDK_WriteAudio writes an Audio CD structure in Disc-at-Once mode to one or more discs, either actually or in "test write" mode. A fuller-featured alternative to this call is PrimoSDK_WriteAudioEx, available to licensees of PrimoSDK's Advanced Audio functions (see Advanced Audio Addendum Chapter 7).
As outlined in Audio CD Workflow above, this function is called after the Audio CD structure is populated with tracks and CD Text information (if any). The structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created. Audio CD structures are created either with PrimoSDK_NewAudio or, for support of Windows Media Digital Rights Management when using .WMA source files, with PrimoSDK_NewAudioPlaylist (available only if the PrimoSDK license includes Advanced Audio).
The drives on which the discs will be recorded are those specified with pdwUnits in that same PrimoSDK_NewAudio call. Each recorder must already contain a blank recordable/rewritable disc (see pdwMediumType under PrimoSDK_DiscInfoEx).
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus. After PrimoSDK_RunningStatus reports that the operation has completed (successful or otherwise), this function may be called again to record additional passes of the image on fresh media. When no further passes are required, PrimoSDK_CloseAudio may be called to release the structure.
NOTES:
» This call is used as part of the recommended write operation sequence described in Drive Control Sequence above.
» For normal audio discs, close the disc to further writing by passing PRIMOSDK_CLOSEDISC in dwFlags.
» An error will result if an attempt is made to write an Audio CD structure that is a playlist (see PrimoSDK_NewAudioPlaylist) containing a protected track (see PrimoSDK_CheckAudioPlaylist). To write the structure without the protected track(s), delete the structure with PrimoSDK_CloseAudio, then create a new structure with PrimoSDK_NewAudioPlaylist.
» To record an Audio CD track-by-track rather than from a completed Audio CD structure, see PrimoSDK_WriteAudioTrack.
Syntax
DWORD WINAPI PrimoSDK_WriteAudio (
DWORD dwHandle,
DWORD dwFlags,
DWORD dwSpeed
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewAudio call with which the Audio CD structure was created.
dwFlags
A DWORD in which all of the following that apply are ORed together:
- PRIMOSDK_WRITE to make a real recording, or PRIMOSDK_TEST to run a test;
- PRIMOSDK_BURNPROOF to enable BURN-Proof (buffer underrun protection) if available on the destination drive;
- PRIMOSDK_CLOSEDISC to close the disc to further writing (recommended for most Audio CD discs).
dwSpeed
A DWORD specifying the recording speed as one of the following:
- PRIMOSDK_MAX for the highest speed supported by both the destination drive and destination media;
- n for the actual number of the desired speed (e.g. 8 for 8x);
- PRIMOSDK_BEST for drives that support Adjustable Write Speed. If the drive does not support AWS, the speed will revert to PRIMOSDK_MAX.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, the Audio CD structure hasn't yet been started, or the Audio CD structure is empty.
PRIMOSDK_BADPARAM
The parameters in the function are incorrect, or no drives have been specified with pdwUnits in PrimoSDK_NewAudio.
PRIMOSDK_NOTREADY
One or more units are not ready.
PRIMOSDK_NOSPACE
One or more of the media do not have enough free sectors.
PRIMOSDK_ITSADEMO
The operation exceeds the limits allowed by the Demo version of PrimoSDK.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_CloseAudio | go: top | section |
PrimoSDK_CloseAudio is required to terminate and free the resources allocated to an Audio CD structure when that structure is no longer needed. The structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created. Audio CD structures are created either with PrimoSDK_NewAudio or, for support of Windows Media Digital Rights Management when using .WMA source files, with PrimoSDK_NewAudioPlaylist (available only if the PrimoSDK license includes Advanced Audio).
Syntax
DWORD WINAPI PrimoSDK_CloseAudio (
DWORD dwHandle
);
Parameters
Output
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewAudio call with which the Audio CD structure was created.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or the Audio CD structure hasn't yet been started.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_WriteAudioTrack | go: top | section |
PrimoSDK_WriteAudioTrack writes a single track from a source file to one or more discs in the recorders specified with pdwUnits. Unlike PrimoSDK_WriteAudio (which records in Disc-at-Once mode), the recording does not require advance creation of an Audio CD structure as described in Audio CD Workflow above. Instead, it is carried out in Track-at-Once (TAO) mode, with one track added each time the function is called. The destination disc(s) may be blank (if this is the first track added) or already contain one or more audio tracks.
The audio file to record to the Audio CD is specified with szTrack. If the PrimoSDK DLL is PrimoSDK.DLL, this file must be a Wave (.WAV) file. If the PrimoSDK DLL is PXSDKPLS.DLL, the file may be in Wave (.WAV), MPEG-1 Layer 3 (.mp3), or Windows Media Audio (.wma) format. The recording speed is specified with dwSpeed.
If this track is the last to be added to the CD, the parameter dwFlags should include the PRIMOSDK_CLOSEDISC flag so that the disc will be finalized, after which it will be playable in a CD-ROM drive or a consumer CD-Audio player. If the intent is to add additional tracks later; then that flag should not be set. dwFlags also determines whether or not the drives are in "test write" mode for this operation.
NOTE: This call is used as part of the recommended write operation sequence described in Drive Control Sequence above.
Syntax
DWORD WINAPI PrimoSDK_WriteAudioTrack (
DWORD dwHandle,
PDWORD pdwUnits,
PBYTE szTrack,
DWORD dwFlags,
DWORD dwSpeed
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
szTrack
A pointer to a BYTE specifying the complete path of the audio source file for the track.
dwFlags
A DWORD in which all of the following that apply are ORed together:
- PRIMOSDK_WRITE to make a real recording, or PRIMOSDK_TEST to run a test;
- PRIMOSDK_BURNPROOF to enable BURN-Proof (buffer underrun protection) if available on the destination drive;
- PRIMOSDK_CLOSEDISC to close the disc to further writing (recommended for most Audio CD discs).
dwSpeed
A DWORD specifying the recording speed as one of the following:
- PRIMOSDK_MAX for the highest speed supported by both the destination drive and destination media;
- n for the actual number of the desired speed (e.g. 8 for 8x);
- PRIMOSDK_BEST for drives that support Adjustable Write Speed. If the drive does not support AWS, the speed will revert to PRIMOSDK_MAX.
Input/Output
pdwUnits
A pointer to a DWORD vector identifying by drive letter and/or SCSI Host/ID/LUN triple the drives containing the discs to which the audio track is to be written (see PrimoSDK_UnitInfo for the internal DWORD format). The vector is terminated by 0xFFFFFFFF.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOTREADY
One or more units are not ready.
PRIMOSDK_NOSPACE
One or more of the media do not have enough free sectors.
PRIMOSDK_ITSADEMO
The operation exceeds the limits allowed by the Demo version of PrimoSDK.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
6.9 Video CD Images | go: top |
This section covers the following calls:
PrimoSDK_NewVideoCD, PrimoSDK_AddVideoCDStream, PrimoSDK_WriteVideoCD, PrimoSDK_CloseVideoCD
These calls are used to create a structure for a Video CD based on a standard basic template (the VCD.DTA file that is provided as part of the PrimoSDK toolkit) and to write that structure to disc. Alternatively, more sophisticated Video CDs may be authored independently of PrimoSDK, and then incorporated into a structure using PrimoSDK's calls for creating data discs (see Data CD and DVD Images).
The following is a typical workflow for building a template-based Video CD structure from a set of MPEG-1 stream files and then writing the image to disc (Disc-at-Once):
The following is a typical workflow for incorporating an independently-authored Video CD image into a data disc structure created with PrimoSDK:
PrimoSDK_NewVideoCD | go: top | section |
PrimoSDK_NewVideoCD initiates the building of a structure for a Video CD image. As outlined in Video CD Images above, the structure is subsequently populated with video streams, at which point it may be written to a disc in a drive specified with pdwUnits.
Immediately prior to the start of writing (see PrimoSDK_WriteVideoCD), PrimoSDK generates VCD-compatible versions of the source video files that have been added to the structure. szTemp specifies the temporary directory in which those versions are to be stored. The space available for the folder's contents must exceed 2336 (bytes per sector) times the sum of all the values of pdwSize that were output by PrimoSDK_AddVideoCDStream each time a stream was added to the structure.
szVideoCDTemplate specifies the path of the PrimoSDK accessory file Vcd.dta. This file is used only for creating Video CDs, and must be included in installations featuring Video CD creation. It is not included as a resource in the PrimoSDK DLL so that overhead is minimized for implementations that do not create Video CDs.
Syntax
DWORD WINAPI PrimoSDK_NewVideoCD (
DWORD dwHandle,
PDWORD pdwUnits,
PBYTE szTemp,
PBYTE szVideoCDTemplate
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
szTemp
A pointer to a BYTE specifying the directory in which VCD-compatible versions of video source files will be generated immediately before the start of recording. The space needed in this temporary folder 2336 times the sum of the sectors returned into pdwSize by all the calls to PrimoSDK_AddVideoCDStream.
szVideoCDTemplate
A pointer to a BYTE specifying the path of the accessory file Vcd.dta, which is provided with PrimoSDK.
Input/Output
pdwUnits
A pointer to a DWORD vector identifying by drive letter and/or SCSI Host/ID/LUN triple the drives containing the discs to which the audio track is to be written (see PrimoSDK_UnitInfo for the internal DWORD format). The vector is terminated by 0xFFFFFFFF.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized.
PRIMOSDK_BADUNIT
The unit specified with pdwUnit does not exist.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOTREADY
The unit is not ready.
PRIMOSDK_INVALIDMEDIUM
One or more target discs is not a blank CD-R or CD-RW.
PRIMOSDK_FILEERROR
The file specified with szVideoCDTemplate is not found.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_AddVideoCDStream | go: top | section |
PrimoSDK_AddVideoCDStream adds a stream to a Video CD structure. The structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (see PrimoSDK_NewVideoCD). As outlined in Video CD Images above, after the structure is populated with streams it may be written to a disc.
The MPEG video file to add to the Video CD structure is specified with szStream. The associated audio must be stereo at a sample rate of44.1 KHz. The video stream format must be one of the following:
Format | Resolution | Frame rate (fps) |
NTSC | 352 × 240 | 29.97 |
PAL | 352 × 288 | 25 |
Film | 352 × 240 | 29.97 |
When the call executes, the size in sectors of the added stream is output with pdwSize.
NOTE: PrimoSDK allows a maximum of 32 streams in a Video CD.
Syntax
DWORD WINAPI PrimoSDK_AddVideoCDStream (
DWORD dwHandle,
PBYTE szStream,
PDWORD pdwSize
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewVideoCD call with which the Video CD structure was created.
szStream
A pointer to a BYTE specifying the complete path of the MPEG-1 source file for the stream.
Output
pdwSize
A pointer to the DWORD that is to be filled in with the size in sectors of the stream specified with szStream.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or no Video CD structure has been started.
PRIMOSDK_BADPARAM
The file specified with szStream is not valid.
PRIMOSDK_FILEERROR
The file specified with szStream was not found.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PrimoSDK_WriteVideoCD | go: top | section |
PrimoSDK_WriteVideoCD writes a Video CD structure to one or more discs, either actually or in "test write" mode. As outlined in Video CD Images above, this function is called after the structure is populated with video streams.
The structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (see PrimoSDK_NewVideoCD). The drives on which the discs will be recorded are those specified with pdwUnits in that same PrimoSDK_NewVideoCD call. Each recorder must already contain a blank recordable/rewritable disc (see pdwMediumType under PrimoSDK_DiscInfoEx).
This function returns immediately and continues asynchronously. To check on or abort the operation, see PrimoSDK_RunningStatus. After PrimoSDK_RunningStatus reports that the operation has completed (successful or otherwise), this function may be called again to record additional passes of the image on fresh media. When no further passes are required, PrimoSDK_CloseVideoCD may be called to release the structure.
NOTES:
» This call is used as part of the recommended write operation sequence described in Drive Control Sequence above.
» A Video CD disc written with the call will always be closed (finalized).
Syntax
DWORD WINAPI PrimoSDK_WriteVideoCD (
DWORD dwHandle,
DWORD dwFlags,
DWORD dwSpeed
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewVideoCD call with which the Audio CD structure was created.
dwFlags
A DWORD in which all of the following that apply are ORed together:
- PRIMOSDK_WRITE to make a real recording, or PRIMOSDK_TEST to run a test;
- PRIMOSDK_BURNPROOF to enable BURN-Proof (buffer underrun protection) if available on the destination drive.
dwSpeed
A DWORD specifying the recording speed as one of the following:
- PRIMOSDK_MAX for the highest speed supported by both the destination drive and destination media;
- n for the actual number of the desired speed (e.g. 8 for 8x);
- PRIMOSDK_BEST for drives that support Adjustable Write Speed. If the drive does not support AWS, the speed will revert to PRIMOSDK_MAX.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, the Video CD structure hasn't yet been started, or the Video CD structure is empty.
PRIMOSDK_BADPARAM
The parameters in the function are incorrect, or no drives have been specified with pdwUnits in PrimoSDK_NewVideoCD.
PRIMOSDK_NOTREADY
One or more units are not ready.
PRIMOSDK_NOSPACE
One or more of the media do not have enough free sectors.
PRIMOSDK_ITSADEMO
The operation exceeds the limits allowed by the Demo version of PrimoSDK.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured
PrimoSDK_CloseVideoCD | go: top | section |
PrimoSDK_CloseVideoCD is required to terminate and free the resources allocated to a Video CD structure created with PrimoSDK_NewVideoCD when that structure is no longer needed. The structure is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created.
Syntax
DWORD WINAPI PrimoSDK_CloseVideoCD (
DWORD dwHandle
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewVideoCD call with which the Video CD structure was created.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or the video CD structure hasn't yet been started.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.