This article describes how to make a Microsoft DirectShow filter self-registering. It contains the following sections.

• Layout of the Registry Keys
• Registering a Filter
• Unregistering a Filter

  This article does not describe how to create a DLL. For information on creating DLLs, see How to Create a DLL.

  Layout of the Registry Keys

  The DLL that contains the filter is registered as the filter's COM server. When an application calls CoCreateInstanceto create the filter, the Microsoft Windows COM library uses this registry entry to locate the DLL.

  The registry entry for the DLL is as follows. See %_WINCEROOT%\public\directx\oak\files\directx.reg for further examples.

  HKEY_CLASSES_ROOT CLSID 
  Filter CLSIDREG_SZ: (Default) = 
  Friendly name of filterREG_DWORD: Merit = 
  Filter merit value. Filters with higher merit are enumerated
  firstInprocServer32 REG_SZ: (Default) = File name of the DLL
  REG_SZ: ThreadingModel = Both Pins Pin Name REG_DWORD: Direction =
  {0|1} Input(0) or Output(1) REG_DWORD: IsRendered = {0|1} Pin
  Renders its Data REG_DWORD: AllowedZero = {0|1} Filter does not
  require pin to be connected REG_DWORD: AllowedMany = {0|1} Filter
  may have many such pins Types MajorType GUID SubType GUID Specifies
  the media types supported by the pin {MajorType GUID}\{SubType
  GUID}. If SubType is GUID_NULL ({0000-...-0000}), the pin may be
  queried to accept connections with any SubType within the
  MajorType. A pin may have several such entries and a filter may
  have several pin entries.

  The registry entry for the filter information is:

  HKEY_CLASSES_ROOT Filter Filter CLSID REG_SZ:
  (Default) = Friendly Name

  Filter CLSIDs listed under the Filter key will be enumerated as candidates in the intelligent connect process of RenderFilewhen the graph builder tries to assemble the correct filters to play back a given source media.

  Registering a Filter

  One can either register filters statically at image creation time by adding appropriate entries to the platform registry file or dynamically as follows. Note that if the registry on the device in not in non-volatile RAM and one is registering filters dynamically, that regsrv32.exe must be explicitly called everytime the registry information is lost or the filters will not be found by RenderFileand COM.

  To register a filter

  1. Declare filter information.
  2. In the factory template for the filter, include a pointer to the filter information.
  3. Implement the DllRegisterServerfunction.

     The sections that follow describe these steps in detail.

     Declare Filter Information

     The first step is to declare the filter information. DirectShow defines a set of structures for describing filters, pins, and media types:

     Structure	Description
     AMOVIESETUP_FILTER	Describes a filter
     AMOVIESETUP_PIN	Describes a pin
     AMOVIESETUP_MEDIATYPE	Describes a media type.

     These structures are nested. The AMOVIESETUP_FILTER structure has a pointer to an array of AMOVIESETUP_PIN structures, and each AMOVIESETUP_PIN structure has a pointer to an array of AMOVIESETUP_MEDIATYPE structures.

     The structures provide enough information for the IFilterMapperinterface to locate a filter. They are not a complete description of a filter. For example, if the filter creates multiple instances of the same pin, declare one AMOVIESETUP_PIN structure for that pin. Also, a filter is not required to support every combination of media types that it registers.

     Declare these structures as global variables within your DLL. The following example shows a filter with one output pin.

     static const WCHAR g_wszName[] = L"Some Filter";
     AMOVIESETUP_MEDIATYPE sudMediaTypes[] = { { &MEDIATYPE_Video,
     &MEDIASUBTYPE_RGB24 }, { &MEDIATYPE_Video,
     &MEDIASUBTYPE_RGB32 }, }; AMOVIESETUP_PIN sudOutputPin = {
     L"Output", // Pin string name. FALSE, // Is this pin rendered?
     TRUE, // Is it an output pin? FALSE, // Can the filter create zero
     instances? FALSE, // Does the filter create multiple instances?
     &GUID_NULL, // Connects to filter. NULL, // Connects to pin. 2,
     // Number of media types. sudMediaTypes // Pointer to media types.
     }; AMOVIESETUP_FILTER sudFilterReg = { &CLSID_SomeFilter, //
     Filter CLSID. g_wszName, // Filter name. MERIT_NORMAL, // Merit. 1,
     // Number of pin types. &sudPins // Pointer to pin information.
     };

     The filter name is declared as a static global variable, because it will be used again elsewhere.

     Your filter must also override the base class GetSetupData method to return the setup data structure as shown below:

     LPAMOVIESETUP_FILTER CSomeFilter::GetSetupData()
     { return (LPAMOVIESETUP_FILTER) & sudFilterReg; }

     Declare the Factory Template

     The next step is to declare the factory template for your filter. A factory template is a C++ class that contains information for the class factory. In your DLL, declare a global array of factory templates, one for each filter or COM component in your DLL. The array must be named g_Templates. For more information about factory templates, see How to Create a DLL.

     The m_pAMovieSetup_Filtermember of the factory template is a pointer to the AMOVIESETUP_FILTER structure described previously. The following example shows a factory template, using the structure given in the previous example.

     CFactoryTemplate g_Templates[] = { { g_wszName,
     // Name. &CLSID_SomeFilter, // CLSID.
     CSomeFilter::CreateInstance, // Creation function. NULL,
     &sudFilterReg // Pointer to filter information. } }; int
     g_cTemplates = sizeof(g_Templates) / sizeof(g_Templates[0]);

     Implement DllRegisterServer

     The final step is to implement the DllRegisterServerfunction. 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
     AMovieDLLRegisterServer(TRUE); }

     The DirectShow function AMovieDLLRegisterServercreates registry entries for every component declared in the g_Templatesarray.

     Filter categories introduced with AMovieDLLRegisterServer2are not currently supported on Windows CE.

     Unregistering a Filter

     To unregister a filter, implement the DllUnregisterServerfunction. Within this function, call the DirectShow AMovieDLLRegisterServerfunction with a value of FALSE.

     The following example shows how to unregister a filter.

     STDAPI DllUnregisterServer() { return
     AMovieDLLRegisterServer(FALSE); }

     
     

     ---

      Last updated on Tuesday, May 18, 2004

     © 2004 Microsoft Corporation. All rights reserved.