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):

Type Symbolic Name Initialise From Class of Element Created
0x00 ASSOCCLASS_SHELL_KEY key AssocShellElement
0x01 ASSOCCLASS_PROGID_KEY key AssocProgidElement
0x02 ASSOCCLASS_PROGID_STR string AssocProgidElement
0x03 ASSOCCLASS_CLSID_KEY key AssocClsidElement
0x04 ASSOCCLASS_CLSID_STR string AssocClsidElement
0x05 ASSOCCLASS_APP_KEY key AssocApplicationElement
0x06 ASSOCCLASS_APP_STR string AssocApplicationElement
0x07 ASSOCCLASS_SYSTEM_STR string AssocSystemElement
0x08 ASSOCCLASS_FOLDER hard-coded string “Folder” AssocFolderElement
0x09 ASSOCCLASS_STAR string AssocStarElement

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.