CComDynamicUnkArray Class
This class stores an array of IUnknown pointers.
Syntax
class CComDynamicUnkArray
Members
Public Constructors
| Name | Description |
|---|---|
| CComDynamicUnkArray::CComDynamicUnkArray | Constructor. Initializes the collection values to NULL and the collection size to zero. |
| CComDynamicUnkArray::~CComDynamicUnkArray | The destructor. |
Public Methods
| Name | Description |
|---|---|
| CComDynamicUnkArray::Add | Call this method to add an IUnknown pointer to the array. |
| CComDynamicUnkArray::begin | Returns a pointer to the first IUnknown pointer in the collection. |
| CComDynamicUnkArray::clear | Empties the array. |
| CComDynamicUnkArray::end | Returns a pointer to one past the last IUnknown pointer in the collection. |
| CComDynamicUnkArray::GetAt | Retrieves the element at the specified index. |
| CComDynamicUnkArray::GetCookie | Call this method to get the cookie associated with a given IUnknown pointer. |
| CComDynamicUnkArray::GetSize | Returns the number of elements the array can store. |
| CComDynamicUnkArray::GetUnknown | Call this method to get the IUnknown pointer associated with a given cookie. |
| CComDynamicUnkArray::Remove | Call this method to remove an IUnknown pointer from the array. |
Remarks
CComDynamicUnkArray holds a dynamically allocated array of IUnknown pointers, each an interface on a connection point. CComDynamicUnkArray can be used as a parameter to the IConnectionPointImpl template class.
The CComDynamicUnkArray methods begin and end can be used to loop through all connection points (for example, when an event is fired).
See Adding Connection Points to an Object for details on automating creation of connection point proxies.
Note
Note The class CComDynamicUnkArray is used by the Add Class wizard when creating a control which has Connection Points. If you wish to specify the number of Connection Points manually, change the reference from CComDynamicUnkArray to CComUnkArray< n >, where n is the number of connection points required.
Requirements
Header: atlcom.h
CComDynamicUnkArray::Add
Call this method to add an IUnknown pointer to the array.
DWORD Add(IUnknown* pUnk);
Parameters
pUnk
The IUnknown pointer to add to the array.
Return Value
Returns the cookie associated with the newly added pointer. Use this cookie to retrieve the pointer from the array with CComDynamicUnkArray::GetAt.
Remarks
The position where this item is inserted won't necessarily be directly after the last-inserted item if Remove() was previously called on this array. Use the returned cookie to reliably access the inserted pointer.
The array's size might be increased to accommodate more items. Use GetSize() to get the new size.
CComDynamicUnkArray::begin
Returns a pointer to the beginning of the collection of IUnknown interface pointers.
IUnknown**
begin();
Return Value
A pointer to an IUnknown interface pointer.
Remarks
The collection contains pointers to interfaces stored locally as IUnknown. You cast each IUnknown interface to the real interface type and then call through it. You do not need to query for the interface first.
Before using the IUnknown interface, you should check that it is not NULL.
CComDynamicUnkArray::clear
Empties the array. Resets the size to 0.
void clear();
CComDynamicUnkArray::CComDynamicUnkArray
The constructor.
CComDynamicUnkArray();
Remarks
Sets the collection size to zero and initializes the values to NULL. The destructor frees the collection, if necessary.
CComDynamicUnkArray::~CComDynamicUnkArray
The destructor.
~CComDynamicUnkArray();
Remarks
Frees resources allocated by the class constructor.
CComDynamicUnkArray::end
Returns a pointer to one-past the last element in the array's allocated buffer.
Note: this means that the last-inserted pointer is not guaranteed to be at end()-1 because the array may not be filled to capacity.
IUnknown**
end();
Return Value
A pointer to an IUnknown interface pointer.
CComDynamicUnkArray::GetAt
Retrieves the element at the specified index.
IUnknown* GetAt(int nIndex);
Parameters
nIndex
The index of the element to retrieve.
Return Value
A pointer to an IUnknown interface if an element was previously added and exists at this index; otherwise NULL.
CComDynamicUnkArray::GetCookie
Call this method to get the cookie associated with a given IUnknown pointer.
DWORD WINAPI GetCookie(IUnknown** ppFind);
Parameters
ppFind
The IUnknown pointer for which the associated cookie is required.
Return Value
Returns the cookie associated with the IUnknown pointer, or zero if no matching IUnknown pointer is found.
Remarks
If there is more than one instance of the same IUnknown pointer, this function returns the cookie for the first one.
CComDynamicUnkArray::GetSize
Returns the allocated capacity of the array.
Note: this is not the same as the number of non-NULL elements currently in the array.
int GetSize() const;
Return Value
The number of elements the array can store. GetSize() == end() - begin().
CComDynamicUnkArray::GetUnknown
Call this method to get the IUnknown pointer associated with a given cookie.
IUnknown* WINAPI GetUnknown(DWORD dwCookie);
Parameters
dwCookie
The cookie for which the associated IUnknown pointer is required.
Return Value
Returns the IUnknown pointer, or NULL if no matching cookie is found.
CComDynamicUnkArray::Remove
Call this method to remove an IUnknown pointer from the array.
All other elements are unchanged and retain their index and cookie.
BOOL Remove(DWORD dwCookie);
Parameters
dwCookie
The cookie referencing the IUnknown pointer to be removed from the array.
Return Value
Returns TRUE if the pointer is removed; otherwise FALSE.