Microsoft DirectX 8.0 |
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.
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.
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.
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.
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.
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'.