© Sonic Solutions. All Rights Reserved.

7  Advanced Audio Addendum

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 DRMgo:  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_SetAudioLibraryCallbackgo:  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_NewAudioPlaylistgo:  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_CheckAudioPlaylistgo:  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 Managementgo:  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_AddAudioTrackExgo:  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_AddAudioStreamgo:  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_AddAudioEffectgo:  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_WriteAudioTrackStreamgo:  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_GetAudioTrackInfogo:  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_GetISRCgo:  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 Discgo:  top

This section covers the following call:

PrimoSDK_WriteAudioEx

This call is used to write an Audio CD structure to disc.


PrimoSDK_WriteAudioExgo:  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 Controlgo:  top

This section covers the following calls:

PrimoSDK_GetPositionAudio, PrimoSDK_PlayAudio, PrimoSDK_PauseResumeAudio, PrimoSDK_StopAudio

These calls are used to control audio playback.


PrimoSDK_GetPositionAudiogo:  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_PlayAudiogo:  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_PauseResumeAudiogo:  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_StopAudiogo:  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.

Top