© Sonic Solutions. All Rights Reserved.
This addendum documents additional audio-related functions offering Advanced Audio capabilities that are licensed separately from the standard version of PrimoSDK. These calls fall into the following categories:
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: For information on standard audio-related PrimoSDK calls, see Audio CD Images in Chapter 6. To find a specific call by name, see Chapter 5, Alphabetic Call List.
7.1 WMA Playlists and DRM | go: top |
This section covers the following calls:
PrimoSDK_SetAudioLibraryCallback, PrimoSDK_NewAudioPlaylist, PrimoSDK_CheckAudioPlaylist
This call is used to implement Windows Media Audio digital rights management (DRM).
PrimoSDK_SetAudioLibraryCallback | go: top | section |
PrimoSDK_SetAudioLibraryCallback passes a pointer to a callback that sets up Microsoft Windows Media Audio (WMA) digital rights management (DRM) libraries required for non-streaming audio operations. Usage of the callback, which is specified with the parameter pCallback, is shown in the following example routine:
HRESULT PrimoSDKLibSetupCallback(DWORD dwRights, void **ppReader)
{
return WMCreateReader(NULL, dwRights,(IWMReader**) ppReader);
}
NOTE: This function may be called anytime after PrimoSDK_Init and before PrimoSDK_NewAudio.
Syntax
DWORD WINAPI PrimoSDK_SetAudioLibraryCallback(
DWORD dwFlags,
PrimoSDK_CreateWmaReader pCallback
);
Parameters
Input
dwFlags
Set to 0 (reserved for future use).
pCallback
A pointer to a callback function of type PrimoSDK_CreateWmaReader.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_ERRORLOADING
Error when attempting to open the library.
PRIMOSDK_FEATURE_NOT_SUPPORTED
A call was made to a function that is not available (this call requires PXSDK Plus package).
PrimoSDK_NewAudioPlaylist | go: top | section |
PrimoSDK_NewAudioPlaylist initiates the building of a structure for an Audio CD image that can support Windows Media Digital Rights Management when using .WMA source files (see Audio CD Workflow). The structure is subsequently populated with audio tracks (see PrimoSDK_AddAudioTrackEx or PrimoSDK_AddAudioTrack), at which point it may be written to a disc in the drive specified with pdwUnits.
NOTES:
» An Audio CD structure may also be created with PrimoSDK_NewAudio if support is not needed for Windows Media Digital Rights Management when using .WMA source files.
» To record an Audio CD track-by-track without first building a structure for the disc, see PrimoSDK_WriteAudioTrack.
Syntax
DWORD WINAPI PrimoSDK_NewAudioPlaylist (
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_CheckAudioPlaylist | go: top | section |
PrimoSDK_CheckAudioPlaylist checks an Audio CD structure that has been created with PrimoSDK_NewAudioPlaylist to determine the Digital Rights Management (DRM) status of each playlist entry that has been added to the structure with PrimoSDK_AddAudioTrackEx or PrimoSDK_AddAudioTrack. The results of the check are output with an array pointed to by the parameter pdwResults. If the result for a given entry is PRIMOSDK_OK then the track referenced by that entry may be included when the structure is written to disc with PrimoSDK_WriteAudio. Alternatively, a result of PRIMOSDK_PROTECTEDWMA indicates that a given entry may not be included.
NOTE: An error will result in PrimoSDK_WriteAudio if an attempt is made to write an Audio CD structure for which any element in the array pdwResults is output as PRIMOSDK_PROTECTEDWMA. To write the structure without the protected track(s), delete the structure with PrimoSDK_CloseAudio, then create a new structure with PrimoSDK_NewAudioPlaylist.
Syntax
DWORD WINAPI PrimoSDK_CheckAudioPlaylist (
DWORD dwHandle,
DWORD dwBufferSizeBytes,
PDWORD pdwResults
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle), which must have the same value as in the PrimoSDK_NewAudioPlaylist call with which the Audio CD structure was created.
dwBufferSizeBytes
The buffer size of pdwResults (normally the size of DWORD times the number of entries in the playlist).
pdwResults
A pointer to an array of DWORDs in which each DWORD represents the result for each entry in the playlist. Possible results are PRIMOSDK_OK an entry with no DRM restrictions and PRIMOSDK_PROTECTEDWMA for a DRM-protected file.
Returned values
PRIMOSDK_OK
The call completed successfully, and none of the files in the playlist is protected.
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized, or no Audio CD structure has been started.
PRIMOSDK_PROTECTEDWMA
One of the files in the playlist is protected.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
7.2 Track Management | go: top |
This section covers the following calls:
PrimoSDK_AddAudioTrackEx, PrimoSDK_AddAudioStream, PrimoSDK_AddAudioEffect, PrimoSDK_WriteAudioTrackStream, PrimoSDK_GetAudioTrackInfo, PrimoSDK_GetISRC
These calls are used to add tracks to an Audio CD data structure, to add audio effects to tracks, and to get information about tracks.
PrimoSDK_AddAudioTrackEx | go: top | section |
PrimoSDK_AddAudioTrackEx adds to an Audio CD structure a track whose source is a 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_NewAudio). As outlined in Audio CD Images, 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 will be the sum of the values specified with dwPregapAudio and dwPreGapSilence; if both of these parameter specify zero duration there will be no pregap. Extended pregap (greater than 225 sectors) is not supported.
dwFlags is used to set the track's emphasis and copyright information, while pISRC assigns the track's identifying ISRC code. When the call executes, the size in sectors of the added track is output with pdwSize.
PrimoSDK_AddAudioTrackEx also allows the setting of index points, which are locations within a track that may be navigated to directly on CD players supporting the index feature of the Red Book (CD-Audio) specification. Index points may be specified with the array pointed to by pdwIndexArray; each DWORD in the array gives a sector offset from the end of the pregap. Because index point 0 is always the start of the pregap and point 1 is always the end of the pregap, the array begins with point 2 (e.g. pdwIndexArray[0] = sector offset of index point 2, pdwIndexArray[1] = sector offset of index point 3, etc.). The total number of elements in the array (98 maximum) is specified with dwIndexCount.
NOTES:
» This call is a fuller-featured alternative to PrimoSDK_AddAudioTrack.
» To add a track whose source is a stream provided by the host application (rather than a file specified with szTrack), see PrimoSDK_AddAudioStream.
» Tracks specified with this call and with PrimoSDK_AddAudioStream may be intermingled in an Audio CD structure.
» To record a track to an Audio CD Track-at-Once (without first building a structure for the entire disc), see PrimoSDK_WriteAudioTrack.
Syntax
DWORD WINAPI PrimoSDK_AddAudioTrackEx (
DWORD dwHandle,
PBYTE szTrack,
DWORD dwPreGapSilence,
DWORD dwPreGapAudio,
DWORD dwFlags,
PDWORD pdwSize,
PBYTE pISRC,
DWORD dwIndexCount,
PDWORD pdwIndexArray
);
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.
dwPreGapSilence
A DWORD specifying the number of sectors or frames in the track's pregap that contain silence.
dwPreGapAudio
A DWORD specifying the number of sectors or frames in the track's pregap that contain audio.
dwFlags
A DWORD in which all of the following that apply are ORed together:
- PRIMOSDK_EMPHASIS to enable emphasis recording;
- PRIMOSDK_COPYRIGHT to set the copyright bit.
pISRC
A pointer to a BYTE specifying the International Standard Recording Code (ISRC) that is to be assigned to the track.
dwIndexCount
A DWORD specifying the number of track indices (up to 98) in the array specified with pdwIndexArray.
pdwIndexArray
A pointer to an array of DWORDs, each of which specifies the location of one index point in the track (starting with index point 2) as an offset from the end of the pregap.
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_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_INTERR
An internal error occured.
PRIMOSDK_FEATURE_DISABLED
This function is not enabled under the license covering this installation of PrimoSDK.
PrimoSDK_AddAudioStream | go: top | section |
PrimoSDK_AddAudioStream adds to an Audio CD structure a track whose source is a stream provided directly by the host application. This allows DRM-enabled host applications to decode encrypted music on-the-fly and pass the resulting stream to the writing engine without first creating an unencrypted file, thereby making it more difficult for the content to be intercepted by end-users.
The structure to which the track is added is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (see PrimoSDK_NewAudio). As outlined in Audio CD Images, 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 stream, which must be stereo 16-bit/44.1KHz PCM, is provided by the host application to buffers created via the callback function pointed to by pFillerFn, which is defined as follows:
typedef DWORD (*PrimoSDK_StreamCallback)(PBYTE pBuffer, DWORD dwBytesRequested, PDWORD pdwBytesWritten, PVOID pContext);
This callback is called during a write operation (see PrimoSDK_WriteAudioEx) when the engine is ready to accept data to be written to the CD for the track defined by this call. The call also provides for a value, passed to the callback function with pContent, that may be used to identify which stream data is being requested.
The amount of disc space (in sectors) that will be required for the added track is specified with dwSize, while the track's pregap is specified with dwPregap.
NOTES:
» To add a track whose source is a file rather than a stream provided by the host application, see PrimoSDK_AddAudioTrackEx.
» Tracks specified with this call and with PrimoSDK_AddAudioTrackEx may be intermingled in an Audio CD structure.
» To record a track to an Audio CD Track-at-Once (without first building a structure for the entire disc), see PrimoSDK_WriteAudioTrack.
» This function is supported in PrimoSDK version 2.0 or higher.
Syntax
DWORD WINAPI PrimoSDK_AddAudioStream(
DWORD dwHandle,
PrimoSDK_StreamCallback pFillerFn,
PVOID pContext,
DWORD dwPreGap,
DWORD dwSize
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
pFillerFn
A pointer to a PrimoSDK_StreamCallback function, which fills buffers with audio data to be written to the CD.
pContext
A value, passed to the callback function, used to identify which stream data is being requested. PrimoSDK itself does not use this parameter.
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).
dwSize
A DWORD specifying the number of sectors that will be required to record the audio for this track onto the destination disc.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_FEATURE_DISABLED
This function is not enabled under the license covering this installation of PrimoSDK.
PrimoSDK_AddAudioEffect | go: top | section |
PrimoSDK_AddAudioEffect specifies an effect to apply to an audio track that has been added to an Audio CD structure with PrimoSDK_AddAudioTrackEx (or PrimoSDK_AddAudioTrack). The effect must be specified before the track is written to disc with PrimoSDK_WriteAudio.
The structure in which the track exists is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (see PrimoSDK_NewAudio). The number of the track is specified with dwTrack. Tracks are numbered, starting with 1, based on the order in which they are added.
The type of effect to be applied by the call is specified with dwEffectType. The only currently-defined value for this parameter is PRIMOSDK_NORMALIZE, which sets the call to scale the amplitude of every audio sample in the track to a percentage of the amplitude of the corresponding sample in the source file. The percentage is expressed as a number from 0 to 10000 (100.00 percent of the amplitude in the source file).
NOTE: Some effects require parameter information that must be retrieved with PrimoSDK_GetAudioTrackInfo before using this call.
Syntax
DWORD WINAPI PrimoSDK_AddAudioEffect(
DWORD dwHandle,
DWORD dwTrack,
DWORD dwEffectType,
DWORD dwParameterDwords,
PDWORD pdwParameters
);
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.
dwTrack
A DWORD specifying the number of the audio track to which an effect is to be applied.
dwEffectType
A DWORD specifying the type of the effect to be applied (currently PRIMOSDK_NORMALIZE only).
dwParameterDwords
A DWORD specifying the size (in DWORDs) to allocate for the pdwParameters array. If dwEffectType is PRIMOSDK_NORMALIZE, pass as 2.
pdwParameters
A pointer to an array of DWORDs, each of which is a parameter for the effect type specified with dwEffectType. If dwEffectType is PRIMOSDK_NORMALIZE, the DWORDs are used as follows:
- [0]: The peak level for this track as returned from PrimoSDK_GetAudioTrackInfo (0 - 10000).
- [1]: The percent of the source file amplitude to which the track amplitude is to be scaled (10000 = 100.00%).
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_WriteAudioTrackStream | go: top | section |
PrimoSDK_WriteAudioTrackStream writes a single track from a stream to one or more discs in the recorders specified with pdwUnits. Unlike PrimoSDK_WriteAudioEx (which records in Disc-at-Once mode), the recording does not require advance creation of an Audio CD structure as described in Audio CD Images. 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 data to write to the Audio CD is supplied by the callback function specified with pFillerFn. The size of the data is specified with dwSize, and the speed at which to record it is specified with dwSpeed. User data to be passed back when the callback is called may be provided with pContext; this data may be used to identify which stream data is being requested.
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.
Syntax
DWORD WINAPI PrimoSDK_WriteAudioTrackStream(
DWORD dwHandle,
PDWORD pdwUnits,
PrimoSDK_StreamCallback pFillerFn,
PVOID pContext,
DWORD dwSize,
DWORD dwFlags,
DWORD dwSpeed
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
pFillerFn
A pointer to the function to call to fill buffers with audio that is to be written to the CD. The audio must be stereo (2 channel), 44100Hz sample rate at 16-bits per sample.
pContext
An object whose value will be passed to the callback function by PrimoSDK when the callback is called.
dwSize
A DWORD specifying the size in sectors of the audio for this 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, or no Audio CD structure has been started, or the Audio CD is empty.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_NOTREADY
One or more units are not ready.
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_GetAudioTrackInfo | go: top | section |
PrimoSDK_GetAudioTrackInfo retrieves information about audio in the source file of an audio track that has been added to an Audio CD structure with PrimoSDK_AddAudioTrackEx (or PrimoSDK_AddAudioTrack). The information retrieved from this call may be used when modifying the track's audio using PrimoSDK_AddAudioEffect (before the track is written to disc with PrimoSDK_WriteAudio).
The structure in which the track exists is indentified by the parameter dwHandle, which must have the same value as in the call with which the structure was created (see PrimoSDK_NewAudio). The number of the track is specified with dwTrack. Tracks are numbered, starting with 1, based on the order in which they are added.
The type of the information to be retrieved by the call is specified with dwInfoType. The only currently-defined value for this parameter is PRIMOSDK_PEAK, which sets the call to output (with pdwResult) the peak level of the audio in the source file, expressed as a number from 0 to 10000 (100.00 percent of the maximum possible level for the track).
Depending on the duration of the source file, retrieving audio information may take some time, so the function does not always output information on the first call (instead returning PRIMOSDK_RUNNING). The following approach is recommended to handle this issue:
while ((rc = PrimoSDK_GetAudioTrackInfo(
...)) == PRIMOSDK_RUNNING)
{
// sleep or peek message
}
if (rc == PRIMOSDK_OK)
{
// info is valid
}
Syntax
DWORD WINAPI PrimoSDK_GetAudioTrackInfo(
DWORD dwHandle,
DWORD dwTrack,
DWORD dwInfoType,
DWORD dwResultDwords,
PDWORD pdwResult
);
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.
dwTrack
A DWORD specifying the number of the audio track for which information is to be retrieved.
dwInfoType
A DWORD specifying the type of information to be retrieved (currently PRIMOSDK_PEAK only).
dwResultDwords
A DWORD specifying the size (in DWORDs) allocated for the pdwResult array; must be at least 1.
Output
pdwResult
A pointer to the array of DWORDs that is to be filled in with the retrieved information.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_RUNNING
The operation is currently running (still calculating the requested information).
PRIMOSDK_CMDSEQUENCE
PrimoSDK is not yet initialized or no Audio CD has been started.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_FILEERROR
Primo cannot calculate the peaks in the specified audio file, possibly because the file is corrupt or invalid.
PrimoSDK_GetISRC | go: top | section |
PrimoSDK_GetISRC retrieves the International Standard Recording Code for a track on the Audio CD in the drive specified with the parameter pdwUnit. The track is specified with dwTrack, while the ISRC code is output with pISRC.
Syntax
DWORD WINAPI PrimoSDK_GetISRC (
DWORD dwHandle,
PDWORD pdwUnit,
DWORD dwTrack,
PBYTE pISRC
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
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).
dwTrack
A DWORD specifying the track from which to retrieve the ISRC.
Output
pISRC
A pointer to a 12-byte buffer that is to be filled in with the ISRC information The buffer is not NULL terminated. If no ISRC information is available for the track, the buffer will be filled with 0.
Returned values
PRIMOSDK_OK
The call completed successfully.
PRIMOSDK_BADHANDLE
dwHandle is not a valid handle.
PRIMOSDK_BADPARAM
dwTrack specifies an invalid track.
PRIMOSDK_READERROR
The drive reports an error reading the ISRC.
PRIMOSDK_FEATURE_DISABLED
This function is not enabled under the license covering this installation of PrimoSDK.
7.3 Write to Disc | go: top |
This section covers the following call:
This call is used to write an Audio CD structure to disc.
PrimoSDK_WriteAudioEx | go: top | section |
PrimoSDK_WriteAudioEx writes an Audio CD structure in Disc-at-Once mode to one or more discs, either actually or in "test write" mode. As outlined in Audio CD Images, this function is called after the 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 (see PrimoSDK_NewAudio or PrimoSDK_NewAudioPlaylist). 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 a fuller-featured alternative to PrimoSDK_WriteAudio.
» This call is used as part of the recommended write operation sequence described in Drive Control Sequence.
» 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.
» For normal audio discs, close the disc to further writing by passing PRIMOSDK_CLOSEDISC in dwFlags.
» To record an Audio CD track-by-track rather than from a completed Audio CD structure, see PrimoSDK_WriteAudioTrack.
Syntax
DWORD WINAPI PrimoSDK_WriteAudioEx (
DWORD dwHandle,
DWORD dwFlags,
DWORD dwSpeed,
PBYTE pMCN
);
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.
pMCN
A pointer to a BYTE specifying the Media Catalog Number (13 bytes will be BCD encoded to be placed into the Q channel).
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_FEATURE_DISABLED
This function is not enabled under the license covering this installation of PrimoSDK.
7.4 Playback Control | go: top |
This section covers the following calls:
PrimoSDK_GetPositionAudio, PrimoSDK_PlayAudio, PrimoSDK_PauseResumeAudio, PrimoSDK_StopAudio
These calls are used to control audio playback.
PrimoSDK_GetPositionAudio | go: top | section |
PrimoSDK_GetPositionAudio retrieves the current position (in sectors) of the Audio CD in the device specified with the parameter pdwUnit. The relative position is output with pdwRelPosition, while the absolute position is output with pdwAbsPosition.
Syntax
DWORD WINAPI PrimoSDK_GetPositionAudio(
DWORD dwHandle,
PDWORD pdwUnit,
PDWORD pdwRelPosition,
PDWORD pdwAbsPosition
);
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
pdwRelPosition
A pointer to a DWORD that is to be filled in with the CD's relative position in sectors.
pdwAbsPosition
A pointer to a DWORD that is to be filled in with the CD's absolute position in sectors.
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_SCSIERROR
A communication error occurred, or the command went in time-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.
PRIMOSDK_BADPARAM
The value of one or more parameters is invalid (e.g. pointers for the positions are NULL).
PrimoSDK_PlayAudio | go: top | section |
PrimoSDK_PlayAudio plays one or more sectors of audio data from the disc in the device specified with pdwUnit. The starting sector (logical block address) for playback is specified with StartLba. The number of sectors to play is specified with Length.
Syntax
DWORD WINAPI PrimoSDK_PlayAudio(
DWORD dwHandle,
PDWORD pdwUnit,
DWORD StartLba,
DWORD Length
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
StartLba
A DWORD specifying the logical block address of the sector at which playback is to begin.
Length
A DWORD specifying the number of sectors to play.
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 requested drive does not exist.
PRIMOSDK_SCSIERROR
A communication error occurred, or the command went in time-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.
PrimoSDK_PauseResumeAudio | go: top | section |
PrimoSDK_PauseResumeAudio pauses or resumes an audio playback operation (see PrimoSDK_PlayAudio) involving a disc in the drive specified with the parameter pdwUnit. If audio is currently playing, set bResume to FALSE to pause playback. If audio is currently paused, set bResume to TRUE to resume playback.
Syntax
DWORD WINAPI PrimoSDK_PauseResumeAudio(
DWORD dwHandle,
PDWORD pdwUnit,
BOOL bResume
);
Parameters
Input
dwHandle
A DWORD specifying the operation's handle (see PrimoSDK_GetHandle).
bResume
Boolean:
- if TRUE, continue playing;
- if FALSE, pause audio.
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_SCSIERROR
A communication error occurred, or the command went in time-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.
PrimoSDK_StopAudio | go: top | section |
PrimoSDK_StopAudio stops an audio playback operation (see PrimoSDK_PlayAudio) involving a disc in the drive specified with the parameter pdwUnit.
Syntax
DWORD WINAPI PrimoSDK_StopAudio(
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 call 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 went in time-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.