Microsoft DirectX 8.0

ITuningSpaceContainer Interface

The ITuningSpaceContainer interface is implemented on the SystemTuningSpaces object, which enables an application to access and modify all the Tuning Spaces defined on the local system.

MethodNameDescription
get_CountRetrieves the number of Tuning Spaces currently available on the local system.
get__NewEnumEnumeration method to support For...Each loops in Automation clients.
get_ItemRetrieves the Tuning Space object at the specified index.
put_ItemSaves the Tuning Space object at the specified index.
TuningSpacesForCLSIDRetrieves a collection of Tuning Spaces that match the specified CLSID string. (For use by Automation clients.)
_TuningSpacesForCLSIDRetrieves a collection of Tuning Spaces that match the specified CLSID. (For use by C++ clients.)
TuningSpacesForNameRetrieves a collection of Tuning Spaces that match the specified friendly name.
FindIDRetrieves the local unique ID number for the specified Tuning Space.
AddAdds a new, persistent, Tuning Space to the system.
get_EnumTuningSpacesRetrieves a collection of all Tuning Spaces available on the local system.
RemovePermanently removes a Tuning Space from the system.
put_MaxCountRetrieve the maximum number of tuning spaces allowed on the system.
get_MaxCountSet the maximum number of tuning spaces allowed on the system.

ITuningSpaceContainer::get_Count

ITuningSpaceContainer Interface

Retrieves the number of Tuning Spaces currently available on the local system.

Syntax

HRESULT get_Count(
    long *Count
    );

Parameters

Count
[out, retval] Pointer to a variable of type long that receives the number of Tuning Spaces.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

ITuningSpaceContainer::get_MaxCount

ITuningSpaceContainer Interface

Retrieves the maximum number of tuning spaces allowed on the system.

Syntax

HRESULT get_MaxCount(
    long *MaxCount
    );

Parameters

MaxCount
[out, retval] Pointer to a variable of type long that receivces the maximum number of tuning spaces.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

ITuningSpaceContainer::get__NewEnum

ITuningSpaceContainer Interface

Enumeration method to support For...Each loops in Automation clients.

Syntax

HRESULT get__NewEnum(
    IEnumVARIANT **NewEnum
    );

Parameters

NewEnum
[out, retval] Address of an IEnumVARIANT interface pointer that will be set to the returned collection.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

This method is provided to enable scripting and VB applications to iterate through the collection in a For...Each loop. C++ applications should use the get_EnumTuningSpaces method.

ITuningSpaceContainer::get_Item

ITuningSpaceContainer Interface

Retrieves an ITuningSpace object at the specified index.

Syntax

HRESULT get_Item(
    VARIANT varIndex,
    ITuningSpace **ppTuningSpace
    );

Parameters

varIndex
[in] Variable of type VARIANT specifying the index of the item to retrieve.
ppTuningSpace
[out, retval] Address of an ITuningSpace interface pointer that will be set to the returned interface.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

ITuningSpaceContainer::put_Item

ITuningSpaceContainer Interface

Saves the Tuning Space object at the specified index.

Syntax

HRESULT put_Item(
    VARIANT varIndex,
    ITuningSpace *pTuningSpace
    );

Parameters

varIndex
[in] Variable of type VARIANT specifying the index of the item to set.
pTuningSpace
[in] Pointer to the ITuningSpace interface on the object that will be persisted to the system.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

Using the methods of ITuningSpace, an application can modify an existing Tuning Space and then use ITuningSpaceContainer::put_Item to save the changes to disk.

ITuningSpaceContainer::TuningSpacesForCLSID

ITuningSpaceContainer Interface

Retrieves a collection of Tuning Spaces that match the CLSID string. (For use by Automation clients.)

Syntax

HRESULT TuningSpacesForCLSID(
    BSTR SpaceCLSID,
    ITuningSpaces **ppTuningSpaces
    );

Parameters

SpaceCLSID
[in] String representation of the CLSID of the Tuning Space.
ppTuningSpaces
[out, retval] Address of an ITuningSpaces interface pointer that will be set to the returned collection.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

This method enables Automation clients to specify a CLSID with a BSTR; internally it simply calls _TuningSpacesForCLSID.

ITuningSpaceContainer::_TuningSpacesForCLSID

ITuningSpaceContainer Interface

Retrieves a collection of Tuning Spaces that match the specified CLSID. (For use by C++ clients.)

Syntax

HRESULT _TuningSpacesForCLSID(
    REFCLSID SpaceCLSID,
    ITuningSpaces **ppTuningSpaces
    );

Parameters

SpaceCLSID
[in] Variable of type REFCLSID specifying the type of Tuning Space to retrieve.
ppTuningSpaces
[out, retval] Address of an ITuningSpaces interface pointer that will be set to the returned collection.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

C++ applications should use this method, not TuningSpacesForCLSID.

ITuningSpaceContainer::TuningSpacesForName

ITuningSpaceContainer Interface

Retrieves a collection of Tuning Spaces that match the specified friendly name.

Syntax

HRESULT TuningSpacesForName(
    BSTR Name,
    ITuningSpaces **ppTuningSpaces
    );

Parameters

Name
[in] String representation of the friendly name for Tuning Space type.
ppTuningSpaces
[out, retval] Address of an ITuningSpaces interface pointer that will be set to the returned collection.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

ITuningSpaceContainer::FindID

ITuningSpaceContainer Interface

Retrieves the local unique ID number for the specified Tuning Space.

Syntax

HRESULT FindID(
    ITuningSpace *pTuningSpace,
    long *pID
    );

Parameters

pTuningSpace
[in] Pointer to the ITuningSpace interface on the object whose ID will be retrieved.
pID
[out, retval] Pointer to a variable of type long that will receive the ID number.

Return Value

Returns S_OK if successful or E_INVALIDARG if TuningSpace does not point to a valid object.

ITuningSpaceContainer::Add

ITuningSpaceContainer Interface

Adds a new, persistent, Tuning Space to the system.

Syntax

HRESULT Add(
    ITuningSpace *pTuningSpace,
    VARIANT *pNewIndex
    );

Parameters

pTuningSpace
[in] Pointer to the ITuningSpace interface on the new Tuning Space object to be added to the system.
pNewIndex
[out, retval] Pointer to a variable of type VARIANT that will receive the index number of the new Tuning Space in the current collection.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

The ITuningSpaceContainer::Add() method starts adding objects with an index of 1. The IComponentTypes::Add() method and all other collections begin at 0.

ITuningSpaceContainer::get_EnumTuningSpaces

ITuningSpaceContainer Interface

Retrieves a collection of all Tuning Spaces available on the local system.

Syntax

HRESULT get_EnumTuningSpaces(
    IEnumTuningSpaces **ppEnum
    );

Parameters

ppEnum
[out, retval] Address of an IEnumTuningSpaces interface pointer that will be set to the returned collection.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

Remarks

C++ applications use this method to get the initial list of Tuning Spaces defined on the local system.

ITuningSpaceContainer::put_MaxCount

ITuningSpaceContainer Interface

Sets the maximum number of tuning spaces allowed on the system.

Syntax

HRESULT put_MaxCount(
    long MaxCount
    );

Parameters

MaxCount
[in] Variable of type long that specifies the maximum number of tuning spaces.

Return Value

Returns S_OK if successful. If the method fails, error information can be retrieved using the standard COM IErrorInfo interface.

ITuningSpaceContainer::Remove

ITuningSpaceContainer Interface

Permanently removes a Tuning Space from the system.

Syntax

HRESULT Remove(
    VARIANT Index
    );

Parameters

Index
[in] Variable of type VARIANT specifying the index number of the Tuning Space to remove from the system.

Return Value

Returns S_OK if successful. If the specified Tuning Space was invalid or corrupted in the Registry, this method will delete whatever information is there and return S_FALSE.