AssocCreateForClasses

This function creates a QueryAssociations object and populates it with association elements.

Declaration

HRESULT
AssocCreateForClasses (
    const ASSOCIATIONELEMENT *rgClasses, 
    ULONG cClasses, 
    REFIID riid, 
    PVOID *ppv);

Since the ASSOCIATIONELEMENT structure seems to be used only for this function, its definition is as well reproduced here:

typedef struct ASSOCIATIONELEMENT_ {
    ASSOCCLASS ac;
    HKEY hkClass;
    PCWSTR pszClass;
} ASSOCIATIONELEMENT;

Parameters

The rgClasses argument provides an array of descriptors for the desired association elements.

The cClasses argument provides the number of elements.

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

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

The function first creates an association list. This is an internal object with an IAssociationList interface. The list is populated with assocation elements, one for each of the cClasses descriptors at rgClasses, in the order given. Failure to create the list is failure for the function. Failure to add an element to the list is failure for the function. Note however that failure to create an element is not.

Each ASSOCIATIONELEMENT descriptor in the given array specifies a type of element and provides for its initialisation from either an open registry key or a string (corresponding respectively to initialising through the SetSource and SetString methods of the element’s IObjectWithQuerySource and IPersistString2 interfaces). The following types are supported (as values in the ASSOCCLASS enumeration):

Having created the elements, the function creates a QueryAssociations object to hold the elements as an association array. If this object cannot be created, the function fails. The function then sets its list of elements into the array by calling the SetList method of the array’s IObjectWithAssociationList interface. If this fails or if the function cannot get the desired interface to the array, the function fails.

Queries of the array, through methods of its IAssociationArray and IQueryAssociations interfaces, are satisfied from the first element that responds successfully. Elements are therefore to be given in the descriptors in order of decreasing precedence.

An association array can contain elements whose types are not supported through this function, but the array must be created separately (e.g., with the AssocCreate function), the desired elements must be created separately (with the AssocCreateElement function) and organised into a custom IAssociationList implementation and set into the array by explicitly calling the SetList method. If the desired elements are all listed above, then using this function is much more convenient.

Availability

The AssocCreateForClasses function is exported by name from SHELL32.DLL in the version 6.00 from Windows Vista, and higher.