Implementing DllRegisterServer

Microsoft DirectShow 9.0

Implementing DllRegisterServer

The final step is to implement the DllRegisterServer function. The DLL that contains the component must export this function. The function will be called by a set-up application, or when the user runs the Regsvr32.exe tool.

The following example shows a minimal implementation of DlLRegisterServer:

STDAPI DllRegisterServer(void)
{
    return AMovieDllRegisterServer2(TRUE);
}

The AMovieDllRegisterServer2 function creates registry entries for every component in the g_Templates array. However, this function has some limitations. First, it assigns every filter to the "DirectShow Filters" category (CLSID_LegacyAmFilterCategory), but not every filter belongs in this category. Capture filters and compression filters, for example, have their own categories. Second, if your filter supports a hardware device, you might need to register two additional pieces of information that AMovieDLLRegisterServer2 does not handle: the medium and the pin category. A medium defines a method of communication in a hardware device, such as a bus. The pin category defines the function of a pin. For information on mediums, see KSPIN_MEDIUM in the Microsoft Windows Driver Development Kit (DDK). For a list of pin categories, see Pin Property Set.

If you want to specify a filter category, a medium, or a pin category, call the IFilterMapper2::RegisterFilter method from within DllRegisterServer. This method takes a pointer to a REGFILTER2 structure, which specifies information about the filter.

To complicate matters somewhat, the REGFILTER2 structure supports two different formats for registering pins. The dwVersion member specifies the format:

• If dwVersion is 1, the pin format is AMOVIESETUP_PIN (described previously).
• If dwVersion is 2, the pin format is REGFILTERPINS2.

The REGFILTERPINS2 structure includes entries for pin mediums and pin categories. Also, it uses bit flags for some items that AMOVIESETUP_PIN declares as Boolean values.

The following example shows how to call IFilterMapper2::RegisterFilter from inside DllRegisterServer:

REGFILTER2 rf2FilterReg = {
    1,              // Version 1 (no pin mediums or pin category).
    MERIT_NORMAL,   // Merit.
    1,              // Number of pins.
    &sudPins        // Pointer to pin information.
};

STDAPI DllRegisterServer(void)
{
    HRESULT hr;
    IFilterMapper2 *pFM2 = NULL;

    hr = AMovieDllRegisterServer2(TRUE);
    if (FAILED(hr))
        return hr;

    hr = CoCreateInstance(CLSID_FilterMapper2, NULL, CLSCTX_INPROC_SERVER,
            IID_IFilterMapper2, (void **)&pFM2);

    if (FAILED(hr))
        return hr;

    hr = pFM2->RegisterFilter(
        CLSID_SomeFilter,                // Filter CLSID. 
        g_wszName,                       // Filter name.
        NULL,                            // Device moniker. 
        &CLSID_VideoCompressorCategory,  // Video compressor category.
        g_wszName,                       // Instance data.
        &rf2FilterReg                    // Pointer to filter information.
    );
    pFM2->Release();
    return hr;
}