IArray2 Interface
- GetCount
- GetAt
- InsertAt
- RemoveAt
- Add
- Find
- InsertNew
- SetCount
- SetAt
- RemoveAll
IArray2 is an expansion of IArray
interface, which has added InsertNew
method. It also can be used by environments which do not recognize IUnknown data
type. IArray2 implementing a property
has to be queried via the correspondent IArray.
See also
Light Visual Basic Sample,
Object Array Sample,
Interface List
HRESULT GetCount(int * pnCount)
Parameters
pnCount- [out, retval] Reference to an integer
variable which will be set to number of valid members in the array
Returns
- S_OK in case of
success.
HRESULT GetAt(int index, VARIANT* val)
Parameters
index - [in] index of the object to retrieve.
val - [out, retval] pointer to a VARIANTvariable,
which will be assigned an appropriate interface pointer, implemented by index-th
object in the array.
Return Values
- S_OK in case of
success.
DISP_E_BADINDEX - if the index is out of the range
DISP_E_PARAMNOTOPTIONAL - if the object is not available.
- Remarks:
-
- The type vt of the VARIANT is VT_UNKNOWN. The returned value is
contained in punkVal member of the VARIANT and has type of IUnknown. This method gives access to index-th object in
the array. Most often actual type of the interface is different from IUnknown
and can be cast to the specific type, which is described for each specific use
of the IArray interface.
HRESULT InsertAt(int index, VARIANT* val)
Parameters
index - [in] index of the newly
added object.
val - [in] VARIANT,
containing a reference to an IUnknown interface to be inserted in the array. Depending on the specific type of objects
in the array if the I Unknown reference is NULL a new default object
will be inserted at the position.
Returns
S_OK in case of success.
Remarks:
This method will insert the reference to the object contained in the val
at position index. All other
members will be shifted up. Size of the array will be incremented by 1. The type
vt of the VARIANT must be VT_UNKNOWN. The value must
be contained in punkVal member of the VARIANT and have type of IUnknown.
HRESULT RemoveAt(int index)
Parameters
index - [in] index of the object to
be removed..
Returns
S_OK in case of
success.
Remarks:
Will remove the object at index position.
HRESULT Add(VARIANT* val)
Parameters
val - [in] VARIANT,
containing a reference to an I Unknown
interface to be added to the array. Depending on the specific type of objects in
the array if I Unknown reference is NULL a new default object added
at the end of the array.
Returns
S_OK in case of
success.
Remarks:
The method will insert the reference to the object contained in the val
at the end of the array. The type vt of the VARIANT must be VT_UNKNOWN.
The value must be contained in punkVal member of the VARIANT and have type of
IUnknown.
HRESULT Find(VARIANT *
val, int* pnIndex)
Parameters
val - [in] VARIANT,
containing a reference to an I Unknown
interface to be found in the array. Note that any interface of any type can be
supplied for this parameter.
pnIndex - [out] Reference to an integer variable,
which will receive 0-based index of the object in the array or -1 if not found.
Returns
S_OK. - Always.
Remarks:
If the array contains the object implementing the IUnknown reference,
contained in the val, its
0- based index will be returned in pnIndex. Otherwise pnIndex
will be set to -1.
HRESULT InsertNew(int type, int indexAt)
Parameters
type - [in] Depending on context
when there several types of object can be kept in the array this parameters
identifies type of the object, which is requested to be created and inserted in
the array. Documentation for specific property describes valid values for this
parameter.
indexAt - [in] 0-based index of the new object in the array.
It must be between 0 and the current size of array.
Returns
S_OK. - If succeeded.
DISP_E_BADINDEX - when indexAt is negative or
exceeds the current size of the array.
Remarks:
The method creates a new object of type type. In the
context when only one type of object can be added to the array type parameter
is ignored and can be set to any non-negative integer. Documentation for
specific property describes valid values for this parameter.
For example, in
case of IArray2 obtained from ISymmetries type
can be 1, 2 or 3, which are the valid values of the ESymmType
enumeration.
HRESULT SetCount(int count)
Parameters
count - [in] New size
of the array.
Returns
S_OK. - If succeeded.
ERROR_CALL_NOT_IMPLEMENTED - when count is greater than the current
size and there is no default constructor of new objects for the array
Remarks:
When count is greater than the current size the method creates a
number of new default objects and add them to the array. If
there is no default constructor of new objects for the array the method returns
error code ERROR_CALL_NOT_IMPLEMENTED.
When count is
less than the current size the last several objects are removed from the
array. The remaining elements will not change any properties. count can be zero, which empties the array.
Use SetCount(0) to remove all elements from the array.
HRESULT SetAt(int index, VARIANT* val)
Parameters
index - [in] 0-based index of in the array.
It must be less than the current size of the array.
val - [in] VARIANT,
containing a reference to an IUnknown
interface to be stored in the array.
HRESULT RemoveAll()
Empties the array.
|