SWbemObject.Associators_ method

Article
01/07/2021

The Associators_ method of the SWbemObject object returns a collection of objects (classes or instances) that are associated with the current object. These returned objects are called endpoints. This method performs the same function that the ASSOCIATORS OF WQL query performs.

For an explanation of this syntax, see Document Conventions for the Scripting API.

Syntax

objWbemObjectSet = .Associators_( _
  [ ByVal strAssocClass ], _
  [ ByVal strResultClass ], _
  [ ByVal strResultRole ], _
  [ ByVal strRole ], _
  [ ByVal bClassesOnly ], _
  [ ByVal bSchemaOnly ], _
  [ ByVal strRequiredAssocQualifier ], _
  [ ByVal strRequiredQualifier ], _
  [ ByVal iFlags ], _
  [ ByVal objwbemNamedValueSet ] _
)

Parameters

strAssocClass [in, optional]: String that contains an association class. If specified, this parameter indicates that the returned endpoints must be associated with the source through the specified association class or a class derived from this association class.
strResultClass [in, optional]: String that contains a class name. If specified, this parameter indicates that the returned endpoints must belong to or be derived from the class specified in this parameter.
strResultRole [in, optional]: String that contains a property name. If specified, this parameter indicates that the returned endpoints must play a particular role in their association with the source object. The role is defined by the name of a specified property (which must be a reference property) of an association.
strRole [in, optional]: String that contains a property name. If specified, this parameter indicates that the returned endpoints must participate in an association with the source object in which the source object plays a particular role. The role is defined by the name of a specified property (which must be a reference property) of an association.
bClassesOnly [in, optional]: Boolean value that indicates whether a list of class names should be returned rather than actual instances of the classes. These are the classes to which the endpoint instances belong. The default value for this parameter is FALSE.
bSchemaOnly [in, optional]: This is a Boolean value that indicates whether the query applies to the schema rather than the data. The default value for this parameter is FALSE. It can only be set to TRUE if the object on which this method is invoked is a class. When set to TRUE, the set of returned endpoints represent classes that are suitably associated with the source class in the schema.
strRequiredAssocQualifier [in, optional]: String that contains a qualifier name. This parameter, if specified, indicates that the returned endpoints must be associated with the source object through an association class that includes the specified qualifier.
strRequiredQualifier [in, optional]: String that contains a qualifier name. This parameter, if specified, indicates that the returned endpoints must include the specified qualifier.
iFlags [in, optional]: Integer specifying additional flags to the operation. The default for this parameter is wbemFlagReturnImmediately, which directs the call to return immediately rather than wait until the query has completed. This parameter can accept the following values.
wbemFlagForwardOnly (32 (0x20)): Causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators, but they do not allow calls to SWbemObject.Clone_.
wbemFlagBidirectional (0 (0x0)): Causes WMI to retain pointers to objects of the enumeration until the client releases the enumerator.
wbemFlagReturnImmediately (16 (0x10)): Causes the call to return immediately.
wbemFlagReturnWhenComplete (0 (0x0)): Causes this call to block until the query has completed.
wbemFlagUseAmendedQualifiers (131072 (0x20000)): Causes WMI to return class amendment data with the base class definition. Including this flag makes the localized description qualifier text available for classes, properties and methods. For more information about amended qualifiers, see Localizing WMI Class Information.

objwbemNamedValueSet [in, optional]

Typically, this is undefined. Otherwise, this is an SWbemNamedValueSet object whose elements represent the context information that can be used by the provider that is servicing the request. A provider that supports or requires such information must document the recognized value names, data type of the value, allowed values, and semantics.

Return value

If the call is successful, an SWbemObjectSet object is returned.

Error codes

After completion of the Associators_ method, the Err object may contain one of the error codes in the following list.

wbemErrAccessDenied - 2147749891 (0x80041003): The current user does not have permission to view one or more of the classes returned by the call.
wbemErrFailed - 2147749889 (0x80041001): Unspecified error.
wbemErrInvalidParameter - 2147749896 (0x80041008): A specified parameter is not valid.
wbemErrOutOfMemory - 2147749894: Not enough memory to complete the operation.

Remarks

For more information about the ASSOCIATORS OF associated WQL query, source instances, and endpoints, see ASSOCIATORS OF Statement.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Header	Wbemdisp.h
Type library	Wbemdisp.tlb
DLL	Wbemdisp.dll
CLSID	CLSID_SWbemObject
IID	IID_ISWbemObject