Windows Media Player BITS Job Convention
[The feature associated with this page, Windows Media Player SDK, is a legacy feature. It has been superseded by MediaPlayer. MediaPlayer has been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer instead of Windows Media Player SDK, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]
Windows Media Player can automatically download and add digital media items to the library if you use Background Intelligent Transfer Service (BITS). To take advantage of this feature, you must add your job to the BITS transfer queue and call IBackgroundCopyJob::SetDescription, providing a description string that uses the correct format.
Note
This section describes functionality designed for use by online stores. Use of this functionality outside the context of an online store is not supported.
Syntax
::WMP_JOB:1:serviceId:Provider:AlbumArtist:AlbumTitle:TrackNumber:Title:Duration:Rating
Parameters
-
serviceId
-
A randomly generated 32-bit value that Windows Media Player uses to identify the service.
-
Provider
-
The provider name. This value must match a valid online store key name.
-
AlbumArtist
-
The name of the primary artist for the album.
-
AlbumTitle
-
The title of the album.
-
TrackNumber
-
The CD track number.
-
Title
-
The title of the content.
-
Duration
-
The duration of the content.
-
Rating
-
The rating for the content.
Remarks
When Windows Media Player 10 or later uses BITS to download content, it enumerates the jobs in the transfer queue and inspects the description string for each job. If the description string matches the expected convention, Windows Media Player downloads the content.
You must add only one digital media file for download to each BITS job.
After you start a BITS job using this convention, you must let Windows Media Player complete the job. Windows Media Player will also remove the job from the BITS queue, move the downloaded file to the location where ripped music is saved, and add the downloaded file to the library.
The serviceId parameter must contain a nonzero 32-bit value. We recommend that you use the function CryptGenRandom to create this value.
The file name you specify using the localName parameter of IBackgroundCopyJob::AddFile must have a .wma, .wmv, .mp3, or .asf file name extension.
The remaining parameters are designed to contain metadata values related to the content. You can retrieve these values from your online store webpage by using DownloadItem.getItemInfo. You can retrieve the correct download collection by calling DownloadManager.getDownloadCollection and providing serviceId as the collectionId parameter.
Windows Media Player inspects the BITS queue periodically while the Player is running. To ensure that Windows Media Player checks the BITS queue for download jobs, you should create a value in the following registry subkey:
HKEY_CURRENT_USER\Software\Microsoft\MediaPlayer\Services
The value should be created as follows.
| Name | Type | Description |
|---|---|---|
| RefreshDownload | DWORD | Specifies whether Windows Media Player should inspect the BITS queue for download jobs. If the value is zero, the Player will not inspect the BITS queue. The Player must inspect the queue if the value is nonzero. |
You can use the following alternate syntax to add BITS jobs that Windows Media Player does not complete, but for which it simply shows status information:
::WMP_STATUS:1:serviceId:Provider:AlbumArtist:AlbumTitle:TrackNumber:Title:Duration:Rating
When you use the preceding syntax, you must write code to complete the BITS download, organize the content on the user's computer, and add the content to the library, if desired.
Related topics