Main Page | Class Hierarchy | Class List | File List | Class Members | File Members

IDSSDataSourceEnumerator Interface Reference

List of all members.

Detailed Description

IDSSDataSourceEnumerator is the starting point of the client-server connection.

It enumerates all available MicroStrategy data sources so that the client can select DSS sources to use.

The IDSSDataSourceEnumerator interface returns a collection of DSSDataSource handles upon request from DSS applications such as the MicroStrategy Desktop.
To get to a repository and retrieve the necessary information to enumerate MicroStrategy data sources, the local machine registry, where the client process resides, is read. All information about MicroStrategy data sources is located in a predefined key of the registry.
In the future, information can be obtained from a remote machine's registry.


Public Member Functions

HRESULT _NewEnum ([out, retval] IUnknown pp_NewEnum)
 The standard property used to return the objects in a collection.
HRESULT Add ([in] BSTR DataSourceName,[out, retval] IDSSDataSource ppDataSource)
 Create a new data source and put it under this enumerator.
HRESULT AddDataSource ([in] IDSSDataSource *pDataSource,[in, optional] VARIANT_BOOL OverWritten)
 Add a data source into this enumerator.
HRESULT Count ([out, retval] Int32 *pCount)
 Get the number of MicroStrategy data sources under this enumerator.
HRESULT Item ([in] VARIANT *Index,[out, retval] IDSSDataSource ppDataSource)
 Get the selected IDSSDataSource interface.
HRESULT ItemByProjectName ([in] BSTR ProjectName,[out, optional] Int32 *pNumberOfDataSources,[out, retval] IDSSDataSource ppDataSource)
 Returns the project data source that points to a required project.
HRESULT LoadFromRegistry ()
 Read registry and create data sources.
HRESULT RemoveDataSource ([in] VARIANT *pIndex)
 Remove a data source.
HRESULT Reset ()
 Reset this enumerator by releasing all the data sources under it.
HRESULT SaveToRegistry ([in, optional] VARIANT_BOOL OverWritten)
 Save the properties of all the data source under this enumerator into the registry.

Member Function Documentation

HRESULT IDSSDataSourceEnumerator::_NewEnum (  [out, retval] IUnknown   pp_NewEnum  ) 
 

The standard property used to return the objects in a collection.

This is the standard property used to return the objects in a collection. It returns an enumerator object. Calling methods on the enumerator object retrieves the IDSSDataSource interfaces under this enumerator.

Parameters:
pp_NewEnum An IUnknown pointer to the enumerator object. The object is returned using the standard IEnumVARIANT interface.
Returns:
Usual COM result code:
  • S_OK
  • E_POINTER The memory of pp_NewEnum is not allocated before call this method.
  • E_OUTOFMEMORY The memory is full. The enumerator object cannot be created.

HRESULT IDSSDataSourceEnumerator::Add (  [in] BSTR  DataSourceName,
[out, retval] IDSSDataSource   ppDataSource
) 
 

Create a new data source and put it under this enumerator.

This method creates and returns a new data source if the Name is not used by any data source under this enumerator. If the Name is NULL or empty string or is used by one data source under this enumerator, an error is reported.

Parameters:
DataSourceName The name to be used as the name of the created data source.
ppDataSource The pointer to the IDSSDataSource interface of the created data source.
Returns:
Usual COM result code:
  • S_OK
  • DSSCOM_E_NULLSTRING The Name is empty.
  • CLNTCONN_E_DATASOURCE_EXIST The Name is used by another data source under this enumerator.
  • E_POINTER The memory of ppDataSource is not allocated before call this method.

HRESULT IDSSDataSourceEnumerator::AddDataSource (  [in] IDSSDataSource *  pDataSource,
[in, optional] VARIANT_BOOL  OverWritten
) 
 

Add a data source into this enumerator.

This method adds a data source into this enumerator. The added data source should have a name before it can be added.

This data source overwrites the existing one with the same name only the OverWritten is true and the existing one is not initialized; otherwise, this data source is not added and an error is reported. To overwrite the initialized data source, the client should first reset the initialized data source by using Reset method.
Parameters:
pDataSource The IDSSDataSource interface of the added data source.
OverWritten Determine whether to overwrite the existed one (default value is false).
Returns:
Usual COM result code:
  • S_OK
  • CLNTCONN_E_DATASOURCE_EXIST There is another data source under this enumerator, which has the same name as pDataSource (while OverWritten is false).
  • E_POINTER pDataSource is NULL.

HRESULT IDSSDataSourceEnumerator::Count (  [out, retval] Int32 *  pCount  ) 
 

Get the number of MicroStrategy data sources under this enumerator.

This method returns the number of DSSDataSource object in this enumerator.

Parameters:
pCount The number of IDSSDataSource interfaces in this enumerator.
Returns:
Usual COM result code:
  • S_OK
  • E_POINTER The memory of pCount is not allocated before call this method.

HRESULT IDSSDataSourceEnumerator::Item (  [in] VARIANT *  Index,
[out, retval] IDSSDataSource   ppDataSource
) 
 

Get the selected IDSSDataSource interface.

This method returns the IDSSDataSource interface with the specified name or index in this enumerator. Index values can be short, integer, or long (all starting with 1) or the name of the data source. If the Index is invalid or out of range or the data source is not found by the given name, an error is reported.

This is the default method of IDSSDataSourceEnumerator.
Parameters:
Index The index or name of the selected DSSDataSource object in the enumerator.
ppDataSource The pointer to the IDSSDataSource interface of selected DSSDataSource object.
Returns:
Usual COM result code:
  • S_OK
  • DSSCOM_E_INVALID_INDEX The Index is an invalid type data.
  • DSSCOM_E_NULLSTRING The name in the Index is empty.
  • CLNTCONN_E_DATASOURCE_NONEXIST The value of Index is out of range or no data source in this enumerator has the specified name.
  • E_POINTER The memory of ppDSSDataSource is not allocated before call this method.

HRESULT IDSSDataSourceEnumerator::ItemByProjectName (  [in] BSTR  ProjectName,
[out, optional] Int32 *  pNumberOfDataSources,
[out, retval] IDSSDataSource   ppDataSource
) 
 

Returns the project data source that points to a required project.

This method returns one of the project data source that points to the required project and the number of the project data sources that points to the required project.

Parameters:
ProjectName The name of the required project.
ppDataSource The pointer to the IDSSDataSource interface of the project data source.
pNumberOfDataSources The number of project data sources that points to the required project.
Returns:
Usual COM result code:
  • S_OK
  • CLNTCONN_E_DATASOURCE_NONEXIST No project data source points to the required project.

HRESULT IDSSDataSourceEnumerator::LoadFromRegistry (   ) 
 

Read registry and create data sources.

This method resets the enumerator, reads the information from the registry, and creates all the data sources that are under this enumerator.

Returns:
Usual COM result code:
  • S_OK
  • CLNTCONN_E_VALUE_NOT_IN_REGISTRY One required property value of a data source is not in the registry.
  • E_OUTOFMEMORY The memory is depleted.

HRESULT IDSSDataSourceEnumerator::RemoveDataSource (  [in] VARIANT *  pIndex  ) 
 

Remove a data source.

This method removes the data source from the enumerator if the data source is not initialized. If the removed data source contains an enumerator, that enumerator and all the data source under that enumerator is also removed.

If the removed data source is not found in the enumerator or is initialized, an error is returned.
To remove an initialized data source, the client should first reset the data source by use Reset method.
Parameters:
pIndex The index or name of the DSSDataSource object to be removed.
Returns:
Usual COM result code:
  • S_OK
  • DSSCOM_E_INVALID_INDEX The Index is an invalid type data.
  • DSSCOM_E_NULLSTRING The name in the Index is empty.
  • CLNTCONN_E_DATASOURCE_NONEXIST The value of Index is out of range or no data source in this enumerator has the specified name.

HRESULT IDSSDataSourceEnumerator::Reset (   ) 
 

Reset this enumerator by releasing all the data sources under it.

This method resets the enumerator by releasing all the data sources under it.

Returns:
Usual COM result code:
  • S_OK
  • CLNTCONN_E_TIER_MODE_NOT_SET The connection mode is not set.

HRESULT IDSSDataSourceEnumerator::SaveToRegistry (  [in, optional] VARIANT_BOOL  OverWritten  ) 
 

Save the properties of all the data source under this enumerator into the registry.

This method saves the properties of all the data sources under this enumerator into the registry. If OverWritten is true, the existing ones in the registry are replaced.

Parameters:
OverWritten Determine whether to overwrite the existing one (default value is False).
Returns:
Usual COM result code:
  • S_OK
  • CLNTCONN_E_TIER_MODE_NOT_SET The connection mode is not set.
  • CLNTCONN_E_VALUE_WRITE_FAILURE Failure to write values into the registry tree.
  • E_OUTOFMEMORY The memory is used up.

Copyright © 1996-2018 MicroStrategy Inc. All Rights Reserved.