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

IDSSElements Interface Reference

Inherited by IDSSElements2.

List of all members.

Detailed Description

IDSSElements is the collection interface used to hold elements.

An element is always represented as an IDSSElement interface. The IDSSElements interface is a collection interface.

An IDSSElements interface is exposed in the following circumstances:
This interface is hard to implement since under some circumstances the collection of elements may be too large to hold them all in memory at the same time. But that is an implementation problem, not an interface design problem. It does not impact the client of this interface since they can only obtain elements one at a time (using Item) or into an array of predetermined size (using the Next method of _NewEnum.


Public Member Functions

HRESULT _NewEnum ([out, retval] IUnknown pp_NewEnum)
 Enumerator for this collection.
HRESULT Add ([in] VARIANT *pElement,[in, defaultvalue(NULL)] IDSSAttribute *pAttribute,[out, retval] IDSSElement ppNewElement)
 Add a member to the collection.
HRESULT AddForms ([in] IDSSAttributeForms *pForms)
 Declare an intention to access the collection using particular forms.
HRESULT Clear ()
 Remove all members of the collection Removes all the members from the collection.
HRESULT Complete ([out, retval] VARIANT_BOOL *pComplete)
 Indicates if the collection is totally loaded.
HRESULT Count ([out, retval] Int32 *pCount)
 The number of elements in this collection.
HRESULT Filter ([in] IDSSFilter *pFilter)
 Filter used to populate the collection.
HRESULT Filter ([out, retval] IDSSFilter ppFilter)
 Filter used to populate the collection.
HRESULT Item ([in] Int32 Index,[out, retval] IDSSElement ppElement)
 Access members of the collection.
HRESULT Limit ([in] Int32 Limit)
 Limits the size of the collection.
HRESULT Limit ([out, retval] Int32 *pLimit)
 Limits the size of the collection.
HRESULT NewCollection ([in, defaultvalue(NULL)] IDSSFilter *pFilter,[in, defaultvalue(0)] Int32 Limit,[in, defaultvalue(0)] Int32 Offset,[in, defaultvalue(NULL)] IDSSResolution *pResolution,[out, retval] IDSSElements ppNewCollection)
 Gets a new collection.
HRESULT Offset ([in] Int32 Offset)
 Offset of first element in the collection.
HRESULT Offset ([out, retval] Int32 *pOffset)
 Offset of first element in the collection.
HRESULT Refresh ([in, defaultvalue(NULL)] IDSSFilter *pFilter,[in, defaultvalue(0)] Int32 Limit,[in, defaultvalue(0)] Int32 Offset,[in, defaultvalue(NULL)] IDSSResolution *pResolution)
 Re-loads the collection.
HRESULT Remove ([in] VARIANT *pIndex)
 Remove a member of the collection.
HRESULT Resolution ([in] IDSSResolution *pResolution)
 Resolution object to be used if filter as a prompt.
HRESULT Resolution ([out, retval] IDSSResolution ppResolution)
 Resolution object to be used if filter as a prompt.

Member Function Documentation

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

Enumerator for this 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 contents of the collection.

After the enumerator object has been obtained it is possible for both members of the collection to change. The effect of this change on the members of the collection that are returned by the enumeration object is implementation dependent.
Note that the user doesn't retrieve the contents of the collection until he or she calls the Next method on the enumerator object. This property does not presuppose that all of the objects are retrieved simultaneously.
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

HRESULT IDSSElements::Add (  [in] VARIANT *  pElement,
[in, defaultvalue(NULL)] IDSSAttribute *  pAttribute,
[out, retval] IDSSElement   ppNewElement
) 
 

Add a member to the collection.

Use this method to insert elements into the collection. The method does not create elements, but instead assumes the user already has the element from some other place.
In most contexts the collection is read-only and this method fails. However the collection can be written to in the following contexts:
  • The collection is exposed from an expression (presumably as part of a filter object). Only concrete elements can be put in filter expressions.
  • The collection is exposed from a Sort object. Every type of element other than metric elements can be put in the collection in this context. However, the user can not put an IDSSTemplateSubtotal pointer in. They can only specify this type of Element by putting a number DssElementSubtotal.
When an element is inserted in the collection, we actually copy out the values or DSS_IDs needed to define the element.
If the element (or a similar one) is already in the collection then we return the existing element. If the Element collection is on sorting, we disallow duplicate attribute to be put in.
Parameters:
pElement A VARIANT used to describe the element:
  • IDSSElement = insert a copy of this element in the collection. Not supported by
  • Element on sorting if type of element is DssElementMetric.
  • IDSSMetric = insert a metric element in this collection.
  • IDSSTemplateSubtotal = insert a subtotal element into this collection.
  • Number(DssElementFirst/DssElementLast/DssElementSubtotal) = insert element of this type.
pAttribute The attribute used by this element. Needed to insert elements of type subtotal, first and last.
ppNewElement The new element created in the collection. NULL if the call failed.
Returns:
Usual COM result code:
  • S_OK
  • OBJSVR_E_BAD_ELEMENT_TYPE This collection doesn't permit elements of this type.
  • OBJSVR_E_READ_ONLY The collection is read only.
  • OBJSVR_E_NEED_ATTRIBUTE We need to know the attribute in order to define this element.
  • OBJSVR_E_BAD_ATTRIBUTE Wrong attribute. (Just in case we ever allow collections that are restricted to all same or all different attributes.)

HRESULT IDSSElements::AddForms (  [in] IDSSAttributeForms *  pForms  ) 
 

Declare an intention to access the collection using particular forms.

This method indicates an intention to ask for a particular form (or forms) from the elements. It is not necessary to call this method before requesting the form directly from the element. But it is much more efficient to obtain an extra form for all the elements at once rather than doing it piecemeal. So we provide this method.

Generally the methods that return an IDSSElements interface allow the client to specify a form (or forms). But it seems reasonable that the user could, at any time, change the form of an attribute being displayed. So there is a need for this method.
We assume that the implementation is clever enough to ignore the call if the form is already loaded.
Parameters:
pForms Specify one or more forms to load using a collection of forms.
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSElements::Clear (   ) 
 

Remove all members of the collection Removes all the members from the collection.

In most contexts the collection is read-only and this method fails. However the collection can be written to in the following contexts:

  • The collection is exposed from an expression (presumably as part of a filter object).
  • The collection is exposed from a Sort object.
    Clearing the collection moves its contents to the zombie list.
    Returns:
    Usual COM result code:
  • S_OK
  • OBJSVR_E_READ_ONLY The collection is read-only.

HRESULT IDSSElements::Complete (  [out, retval] VARIANT_BOOL *  pComplete  ) 
 

Indicates if the collection is totally loaded.

Indicates whether this collection if fully loaded. A collection is considered incomplete if it would contain more elements if it had a bigger Limit value.

Parameters:
pComplete Boolean indicating if the collection is fully loaded or not.
Returns:
Usual COM result code:
  • S_OK

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

The number of elements in this collection.

Returns the number of objects in this collection.

The number of objects in the collection refers to the actual number of elements loaded in the collection. This is not necessarily the same number as the size of the complete collection.
Parameters:
pCount The number of objects in this collection.
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSElements::Filter (  [in] IDSSFilter *  pFilter  ) 
 

Filter used to populate the collection.

The (optional) filter used to load the collection.

Parameters:
pFilter New filter to use when loading the collection.
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSElements::Filter (  [out, retval] IDSSFilter   ppFilter  ) 
 

Filter used to populate the collection.

The (optional) filter used to load the collection.

Parameters:
ppFilter Filter used to load the collection. It can be NULL.
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSElements::Item (  [in] Int32  Index,
[out, retval] IDSSElement   ppElement
) 
 

Access members of the collection.

Return an element from the collection, using the IDSSElement interface. The index parameter must be a number.

The contents of the collection are numbered from 1 --> Count.
Parameters:
Index The index number into the collection of the desired element.
ppElement The Index'th element in the collection.
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSElements::Limit (  [in] Int32  Limit  ) 
 

Limits the size of the collection.

Upper bound on the number of elements this collection can contain.

Parameters:
Limit New limit for the collection.
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSElements::Limit (  [out, retval] Int32 *  pLimit  ) 
 

Limits the size of the collection.

Upper bound on the number of elements this collection can contain.

Parameters:
pLimit Current limit set on the collection.
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSElements::NewCollection (  [in, defaultvalue(NULL)] IDSSFilter *  pFilter,
[in, defaultvalue(0)] Int32  Limit,
[in, defaultvalue(0)] Int32  Offset,
[in, defaultvalue(NULL)] IDSSResolution *  pResolution,
[out, retval] IDSSElements   ppNewCollection
) 
 

Gets a new collection.

Returns a new element collection with, potentially, different parameters from the original collection. This is useful for incremental fetching. For example a user could want to get a collection containing the first 10 elements of an attribute, and then another collection with the next 10 elements without losing the first collection. This can be done by calling NewCollection() on the first collection and changing the Offset.

If any of the optional parameters are left out, then the value of the original collection is used. For example, if no filter is passed in, then the filter used to populate the original collection (i.e. the one on which the NewCollection called is being made) is used. The new collection is not actually populated until the user attempts to access it or an explicit Refresh call is made.
Parameters:
pFilter Filter to use when loading the collection.
Limit Max number of elements to retrieve.
Offset Index of first element to retrieve.
pResolution Resolution object to use when loading the collection.
ppNewCollection New collection.
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSElements::Offset (  [in] Int32  Offset  ) 
 

Offset of first element in the collection.

Offset of the first element in the collection. For example, if Offset is 100, and Limit is 100 then the collection contains elements 101 to 200 of the attribute.

Parameters:
Offset New offset.
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSElements::Offset (  [out, retval] Int32 *  pOffset  ) 
 

Offset of first element in the collection.

Offset of the first element in the collection. For example, if Offset is 100, and Limit is 100 then the collection contains elements 101 to 200 of the attribute.

Parameters:
pOffset Current offset.
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSElements::Refresh (  [in, defaultvalue(NULL)] IDSSFilter *  pFilter,
[in, defaultvalue(0)] Int32  Limit,
[in, defaultvalue(0)] Int32  Offset,
[in, defaultvalue(NULL)] IDSSResolution *  pResolution
) 
 

Re-loads the collection.

This call forces the element collection to be loaded. It is useful when the user has obtained a collection, and then changes one of its parameters (e.g. Filter or Limit) and wants to reload the changed collection.

If any of the optional parameters are left out, then the value of the original collection is used. For example, if no filter is passed in, then the filter used to populate the original collection (i.e. the one on which the NewCollection called is being made) is used. The new collection is not actually populated until the user attempts to access it, or an explicit Refresh call is made.
Parameters:
pFilter Filter to use when loading the collection.
Limit Max number of elements to retrieve.
Offset Index of first element to retrieve.
pResolution Resolution object to use when loading the collection.
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSElements::Remove (  [in] VARIANT *  pIndex  ) 
 

Remove a member of the collection.

Remove an element from the collection.

All calls on a method on an element after it is removed will fail.
Parameters:
pIndex A VARIANT value that identifies the element to be removed. Number = A value between 1 and Count. Pointer (element) = This element.
Returns:
Usual COM result code:
  • S_OK
  • E_INVALIDARG pIndex does not identify an element of the collection.

HRESULT IDSSElements::Resolution (  [in] IDSSResolution *  pResolution  ) 
 

Resolution object to be used if filter as a prompt.

This property can be used to pass a resolution object to the Element Server. A resolution object is used to pre-assign values to any prompts that might appear in a filter (i.e. the filter used to populate the collection). It defaults to NULL.

Parameters:
pResolution New resolution object.
Returns:
Usual COM result code:
  • S_OK

HRESULT IDSSElements::Resolution (  [out, retval] IDSSResolution   ppResolution  ) 
 

Resolution object to be used if filter as a prompt.

This property can be used to pass a resolution object to the Element Server. A resolution object is used to pre-assign values to any prompts that might appear in a filter (i.e. the filter used to populate the collection). It defaults to NULL.

Parameters:
ppResolution Current resolution object. It can be NULL.
Returns:
Usual COM result code:
  • S_OK

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