DMO Registration Functions

The DMO registration functions enable an application to register and enumerate Microsoft® DirectX® Media Objects (DMOs). These functions are declared in the file Dmoreg.h.

DMORegister Registers a DMO.

DMOUnregister Unregisters a DMO.

DMOEnum Enumerates registered DMOs.

DMOGetTypes Retrieves the media types registered for a DMO.

DMOGetName Retrieves the registered name of a DMO.

DMORegister

Registers a DMO.

Syntax

HRESULT DMORegister(
   LPCWSTR szName,
   REFCLSID clsidDMO,
   REFGUID guidCategory,
   DWORD dwFlags,
   DWORD cInTypes,
   const DMO_PARTIAL_MEDIATYPE *pInTypes,
   DWORD cOutTypes,
   const DMO_PARTIAL_MEDIATYPE *pOutTypes
);

Parameters

szName

NULL-terminated string that contains a descriptive name for the DMO. Names longer than 79 characters might be truncated.

clsidDMO

Class identifier (CLSID) of the DMO.

guidCategory

Category GUID that specifies the category of the DMO.

dwFlags

Bitwise combination of zero or more flags from the DMO_REGISTER_FLAGS enumeration.

cInTypes

Number of input media types to register. Can be zero.

pInTypes

Pointer to an array of DMO_PARTIAL_MEDIATYPE structures that specify the input media types. The size of the array is specified in the cInTypes parameter.

cOutTypes

Number of output media types to register.

pOutTypes

Pointer to an array of DMO_PARTIAL_MEDIATYPE structures that specify the output media types. The size of the array is specified in the cOutTypes parameter. Can be zero.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OK Success

E_FAIL Failure

E_INVALIDARG Invalid argument

Remarks

This function adds information about a DMO to the registry. Applications or software components can use this information to locate the DMOs they need to use, by calling the DMOEnum function. For example, to encode a video stream, you would search in the DMOCATEGORY_VIDEO_ENCODER category for a DMO whose media types matched your requirements.

The media types registered by this function are only for the purpose of finding the DMO. They do not necessarily match the types returned by the IMediaObject::GetInputType and IMediaObject::GetOutputType methods. For example, a decoder might register just its main input types. After the DMO is created and its input type has been set, its GetOutputType method will return all of the decompressed types it can generate.

DMOUnregister

DMO Registration Functions

Unregisters a DMO.

Syntax

HRESULT DMOUnregister(
   REFCLSID clsidDMO,
   REFGUID guidCategory
);

Parameters

clsidDMO

Class identifier (CLSID) of the DMO.

guidCategory

Category GUID that specifies the category from which to remove the DMO. Use GUID_NULL to unregister the DMO from every category.

Return Value

Returns an HRESULT value. Possible values include the following:

S_FALSE This CLSID was not registered in the specified category.

S_OK Success.

E_INVALIDARG Invalid argument.

DMOEnum

DMO Registration Functions

Enumerates registered DMOs. The caller can search by category, media type, or both.

Syntax

HRESULT DMOEnum(
    REFGUID guidCategory,
    DWORD dwFlags,
    DWORD cInTypes,
    const DMO_PARTIAL_MEDIATYPE *pInTypes,
    DWORD cOutTypes,
    const DMO_PARTIAL_MEDIATYPE *pOutTypes,
    IEnumDMO **ppEnum
);

Parameters

guidCategory

Category GUID that specifies which category of DMO to search. Use GUID_NULL to search every category.

dwFlags

Bitwise combination of zero or more flags from the DMO_ENUM_FLAGS enumeration.

cInTypes

Number of input media types to use in the search criteria. Use zero to match any input type.

pInTypes

Pointer to an array of DMO_PARTIAL_MEDIATYPE structures that contain the input media types. Specify the size of the array in the cInTypes parameter.

cOutTypes

Number of output media types to use in the search criteria. Use zero to match any output type.

pOutTypes

Pointer to an array of DMO_PARTIAL_MEDIATYPE structures that contain the output media types. Specify the size of the array in the cOutTypes parameter.

ppEnum

Address of a variable to receive the IEnumDMO interface of the enumerator.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OK Success

E_FAIL Failure

E_OUTOFMEMORY Insufficient memory

Remarks

This method returns a pointer to an enumerator object that supports the IEnumDMO interface. The application uses the IEnumDMO interface to enumerate over the set of DMOs that match the search criteria.

DMOGetTypes

DMO Registration Functions

Retrieves the media types registered for a DMO.

Syntax

HRESULT DMOGetTypes(
    REFCLSID clsidDMO,
    unsigned long ulInputTypesRequested,
    unsigned long *pulInputTypesSupplied,
    DMO_PARTIAL_MEDIATYPE *pInputTypes,
    unsigned long ulOutputTypesRequested,
    unsigned long *pulOutputTypesSupplied,
    DMO_PARTIAL_MEDIATYPE *pOutputTypes
);

Parameters

clsidDMO

Class identifier (CLSID) of the DMO.

ulInputTypesRequested

Size of the array passed in the pInputTypes parameter.

pulInputTypesSupplied

Pointer to a variable that receives the number of DMO_PARTIAL_MEDIATYPE structures in pInputTypes that the function fills in.

pInputTypes

Pointer to a caller-allocated array of DMO_PARTIAL_MEDIATYPE structures. The size of the array is given in the ulInputTypesRequested parameter. The function fills the array with the input types registered for the DMO.

ulOutputTypesRequested

Size of the array passed in the pOutputTypes parameter.

pulOutputTypesSupplied

Pointer to a variable that receives the number of DMO_PARTIAL_MEDIATYPE structures in pOutputTypes that the function fills in.

pOutputTypes

Pointer to a caller-allocated array of DMO_PARTIAL_MEDIATYPE structures. The size of the array is given in the ulOutputTypesRequested parameter. The function fills the array with the DMO output types registered for the DMO.

Return Value

Returns an HRESULT value. Possible values include the following:

S_FALSE Array too small

S_OK Success

E_FAIL Failure

Remarks

If one of the arrays is too small to hold all of the registered types, the function fills the array but returns S_FALSE.

If the DMO did not register any media types, the function returns S_OK and sets *pulInputTypesSupplied and *pulOutputTypesSupplied to zero.

DMOGetName

DMO Registration Functions

Retrieves the registered name of a DMO.

Syntax

HRESULT DMOGetName(
   REFCLSID clsidDMO,
   WCHAR szName[]
);

Parameters

clsidDMO

Class identifier (CLSID) of the DMO.

szName

Array of 80 Unicode characters that receives the name of the DMO. The caller must allocate the array. The name is a NULL-terminated string.

Return Value

Returns an HRESULT value. Possible values include the following:

S_FALSE No name was registered for this DMO, or the name has zero length.

S_OK Success.

E_FAIL Failure.

Remarks

If the method returns S_FALSE, szName is set to '\0'.

S_FALSE	This CLSID was not registered in the specified category.
S_OK	Success.
E_INVALIDARG	Invalid argument.

S_FALSE	No name was registered for this DMO, or the name has zero length.
S_OK	Success.
E_FAIL	Failure.