AssocCreate

This function creates an uninitialised association array.

Declaration

HRESULT
AssocCreate (
    CLSID clsid,
    REFIID riid,
    PVOID *ppv);

Parameters

The clsid argument provides the CLSID of a desired object.

The riid argument provides the IID of a desired interface to the object.

The ppv argument provides the address of a variable that is to receive a pointer to the desired interface.

Return Value

The function returns zero for success, else an error code.

Behaviour

If the ppv argument is NULL, the function cannot do anything useful, and fails (returning E_INVALIDARG).

If the CLSID is either CLSID_QueryAssociations or IID_IQueryAssocations, the function uses COM (through SHCoCreateInstance) to create an instance of the QueryAssociations object and to query this instance for the desired interface. Failure at this is failure for the function. In the ordinary registry configuration, instantiation is done by SHELL32 and the created object implements the following interfaces:

• IAssociationArray
• IObjectWithAssociationList
• IQueryAssociations

The created object is capable of holding and managing an array of association elements, but it is created empty of such elements. For the created object to be useful, the caller must initialise it, e.g., through the Init or SetList methods of its IQueryAssociations and IObjectWithAssociationList interfaces.

For any other CLSID, the function fails (returning E_INVALIDARG).

Earlier Versions

The preceding description is for the SHLWAPI version 6.00 from Windows Vista. The function has been greatly reduced for this version. The following elaborations are known from earlier versions.

In versions before 6.00, the function stores NULL at the address given by ppv in all cases of failure except for when ppv is itself NULL.

Versions before 6.00 support only IID_IQueryAssociations for the CLSID. For others, the function returns E_NOTIMPL.

In versions before 6.00, the created object is not creatable through COM but is an internal implementation of SHLWAPI. If the function cannot create an instance, it fails (returning E_OUTOFMEMORY). Otherwise, it queries the newly created instance for the desired interface. The only interface implemented by this internally created object is IQueryAssociations.

Support for the creatable COM object begins with version 6.00. If the CLSID is either CLSID_QueryAssociations or IID_IQueryAssocations, and the operating system is Windows XP or greater (as determined by IsOS), then the function expects that the desired object is implemented elsewhere. The function uses COM (through SHCoCreateInstance) to create an instance and to query this instance for the desired interface. Note that if the object is instantiated by a SHELL32 version 6.00 from before Windows Vista, the implemented interfaces are:

• IAssociationArray (with a different IID and methods)
• IAssociationArrayInitialize
• IQueryAssociations

When running on earlier operating systems, the function assumes the absence of a SHELL32 that implements the QueryAssociations object. It reverts to the internal implementation, as from earlier versions.

Whatever the operating system, version 6.00 recognises the following other CLSIDs:

These each correspond to a single type of association element, such as might be inserted into an association array obtained from using CLSID_QueryAssociations. These are internal implementations of SHLWAPI and are creatable only through this function. Support for them in Windows Vista is relocated to SHELL32 for the new function AssocCreateElement.

If the CLSID is not among these or if an instance of the object cannot be created, the function fails (returning CLASS_E_CLASSNOTAVAILABLE). Otherwise, the function queries the newly created element for the desired interface. All elements implement the following interfaces:

• IAssociationElement
• IObjectWithQuerySource
• IPersistString2

The created element is a blank slate, waiting to be initialised through the SetSource or SetString methods of its IObjectWithSource and IPersistString2 interfaces.

Availability

The AssocCreate function is exported by name from SHLWAPI.DLL in version 5.00 and higher. It has long been documented, but as recognising only one CLSID and one IID.