Implementing the Property Page for a DSP Plug-in
[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 display a property page for each DSP plug-in to enable users to set values that change the behavior of the plug-in. Users can access the property page from the Plug-ins tab of the Options dialog box by clicking the name of the DSP plug-in to select it and then clicking Properties.
The Windows Media Player Plug-in Wizard sample code provides a default implementation of a property page that includes a single edit box that receives from the user a value representing a scale factor for the audio volume. When the user clicks Apply, the property page passes this value to the plug-in object so the plug-in can change the value it uses to scale the volume during processing.
About the Property Page Object
The property page object is a COM object that implements the IPropertyPage interface. The sample code generated by the plug-in wizard uses the ATL implementation of IPropertyPage, which is documented in the Visual C++ documentation on MSDN. Your code at least should provide override implementations for IPropertyPage::OnInitDialog, which handles the event that occurs when the property page opens, and IPropertyPage::Apply, which handles the event that occurs when the user clicks Apply. The plug-in wizard generates sample code for each of these event handlers. The sample implementation of OnInitDialog retrieves a value from the registry so that it can display the current scale factor setting. The sample implementation of Apply validates the user input by testing to ensure that it falls within a specified range, then persists the value to the registry, and then passes the value (if valid) to the DSP plug-in property put method, named put_scale.
Additionally, you will need to add code to handle the event that occurs when the user changes a value in a control you provide in the property page. For example, the plug-in wizard implements a function named OnChangeScale, which simply enables the Apply button when the user changes the text in the edit box on the property page by calling the SetDirty method with an argument value of TRUE.
About the Property Page Dialog Resource
The user interface for the property page is stored as a dialog resource. You can easily view and edit the property page dialog in Visual Studio by selecting the ResourceView tab in the Project Workspace window, then opening the Dialog folder, and then double-clicking the property page resource name. The dialog resource editor in Visual Studio provides you with the tools you need to add controls to the property page dialog and to create event handlers that are mapped to the appropriate Windows messages. For details about how to use the resource editor in Visual Studio, refer to Visual Studio Help.
About ISpecifyPropertyPages
If a DSP plug-in provides a property page, the plug-in must implement the ISpecifyPropertyPages interface. This interface contains only one method: ISpecifyPropertyPages::GetPages. This is the method that associates the property page with the DSP plug-in. Windows Media Player calls this method when the user invokes the property page, passing a parameter of type CAUUID, which is a counted array of GUIDs. The sample plug-in implementation of GetPages fills this structure with a single GUID that is the class id of the plug-in property page object. Windows Media Player then uses the class id to create the property page object.
You might notice that the sample implementation of GetPages uses CoTaskMemAlloc to allocate memory for the GUID structure. It is the responsibility of the caller, in this case Windows Media Player, to use CoTaskMemFree to release the memory. For details about the CAUUID structure, see the Platform SDK documentation.
About the Proxy/Stub DLL
For a DSP plug-in to work in Windows Media Player 11 running on Windows Vista, you must provide a proxy/stub DLL for custom interfaces used to communicate changes in settings from a property page dialog box to the plug-in class. Method calls made through such interfaces must be marshaled when the calls are made across process or apartment boundaries. The latest version of the plug-in wizard creates a sample proxy/stub DLL project.
Related topics