Provides a caller with easy access to a substantial amount of object information that generally exists or can be expressed at arrays of GUIDs and/or DWORDs. Through this method a caller can obtain an array of GUIDs, an array of DWORDs, or both. When this method returns information in both arrays, then there is a relationship between the elements of both arrays, that is, pcaUUID[0] and pcadw[0] are related in some way, depending on the kind of array in question as described by rguidArray.
HRESULT GetGUIDDwordArrays(
REFGUID
rguidArray, // Specifies requested GUID or DWORDs
CAUUID *pcaUUID, // Points to CAUUID structure in which to store requested GUIDs
CADWORD *pcadw // Points to CADWORD structure in which to store requested DWORDs
);
Return Values
rguidArray
[in] Identifier of the GUIDs or DWORDs desired on return. This parameter can have the following values. Additional array types can be defined by anyone at any time by simply defining another ARRAYID for use with this method.
ARRAYID_Interfaces_Incoming
On return, pcaUUID contains the interface identifiers of all the objectÆs possible incoming interfaces that a client might access through QueryInterface. The pcadw parameter in this case must be empty (that is, pcadw.cElems is zero). These IIDs are only suggestions of what the object supports and in no way guarantee support at run-time. A client must always request an interface through QueryInterface(riid) and must be able to handle the E_NOINTERFACE failure code even if riid was specified in this array.
ARRAYID_Interfaces_Outgoing
On return, pcaUUID contains the interface identifiers of all the objectÆs outgoing interfaces, that is, those that would be marked as [source] in an objectÆs type library. The pcadw parameter in this case must be empty (that is, pcadw.cElems is zero). These IIDs are only suggestions of what the object supports and in no way guarantee support at run-time. A client must always connect to an outgoing interface through IConnectionPointContainer::FindConnectionPoint(riid) must handle the possible failure of this call even if riid in question was specified in this array.
ARRAYID_Categories_Implemented
On return, pcaUUID contains the CATIDs of the objectÆs supported categories. The pcadw parameter in this case must be empty (that is, pcadw.cElems is zero).
ARRAYID_Categories_Required
On return, pcaUUID contains the CATIDs of the objectÆs required categories, that is, the necessary container-side support without which the object cannot operate. The pcadw parameter in this case must be empty (that is, pcadw.cElems is zero).
ARRAYID_PathProperties
On return, pcadw contains the dispIDs of the objectÆs data path properties, and pcaUUID contains the GUIDs identifying the OLE_DATAPATH_<xx> type of the corresponding property in pcadw. The object must allocate and fill both arrays in this case, and both arrays must container the same number of elements.
ARRAYID_Methods_Primary
On return, pcadw contains the dispIDs of the objectÆs primary methods that best describe its user-level functionality
such methods would be displayed in the callerÆs user interface for providing features like event binding. In this case, pcaUUID.cElems must be zero.
ARRAYID_Methods_Secondary
On return, pcadw contains the dispIDs of the objectÆs seconday methods that is exactly the list of all object methods excluding those returned from ARRAYID_Methods_Primary. In this case, pcaUUID.cElems must be zero.
pcaUUID
[in, out] The address of the caller-allocated and initialized CAUUID structure in which to store the GUIDs associated with rguidArray, if applicable. The caller is responsible for freeing any allocated memory returned in this structure.
pcadw
[in, out] The address of the caller-allocated and initialized CADWORD structure in which to store the DWORDs associated with rguidArray, if applicable. The caller is responsible for freeing any allocated memory returned in this structure.
Return Values
This method can return several success codes that identify which array was or was not filled. This provides an alternate means for the caller to identify which arrays contain allocated data and which do not. On failure the object must return zero and NULL in the cElems and pElems fields of both structures, respectively. That is, the caller need not free any allocations on failure.
S_OK
Both CAUUID and CADWORD arrays were successfully allocated and filled.
CLASSINFO_S_ONLYGUIDS
Only the CAUUID array was allocated and filled whereas the CADWORD array was not needed. In this case CADWORD::cElems must be zero and CADWORD::pElems must be NULL.
CLASSINFO_S_ONLYDWORDS
Only the CADWORD array was allocated and filled whereas the CAUUID array was not needed. In this case CAUUID::cElems must be zero and CAUUID::pElems must be NULL.
E_OUTOFMEMORY
One of the arrays could not be allocated.
E_POINTER
The address in either pcaUUID or pcadw is not valid (such as NULL).
E_UNEXPECTED
An unknown error occurred.
E_INVALIDARG
The rguidArray value does not correspond to a supported array.
Remarks
E_NOTIMPL is not a valid return code for this method as all objects can at least support ARRAYID_Interfaces_Incoming.
The data structures CAUUID and CADWORD were originally defined for other OLE Controls interfaces like ISpecifyPropertyPages and IPerPropertyBrowsing. These structures are defined as follows:
typedef struct tagCAUUIDIn these definitions, cElems is the number of entries in the array pointed to by pElems. The structures themselves are caller-allocated and caller-initialized so cElems is zero and pElems is NULL. The structures are filled on output by the object implementing the method, where cElems describes the number of elements that the object stored in pElems, where the pElems array itself is object-allocated using CoTaskMemAlloc. On successful return, the caller is responsible for freeing any allocated memory in these structures. That is, if pElems is non-NULL (cElems is non-zero) then the caller must call CoTaskMemFree(pElems) when the array is no longer needed.{
ULONG cElems;
GUID *pElems;
} CAUUID;
typedef struct tagCADWORD
{
ULONG cElems;
DWORD *pElems;
} CADWORD;