SWbemServices.AssociatorsOfAsync method

Artykuł
04/27/2021

The AssociatorsOfAsync method of the SWbemServices object returns a collection of objects (classes or instances) called endpoints that are associated with a specified object. The call to AssociatorsOfAsync returns immediately, and the results and status are returned to the caller through events delivered to the sink that is specified in objWbemSink. To handle each returned object, create an objWbemSink.OnObjectReady event handler.

After all the objects arrive, processing is done in the objWbemSink.OnCompleted event. This method performs the same function that the ASSOCIATORS OF WQL query performs. For more information about creating a sink, see Receiving a WMI Event.

The method is called in the asynchronous mode. For more information, see Calling a Method.

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

Syntax

SWbemServices.AssociatorsOfAsync( _
  ByVal objWbemSink, _
  ByVal strObjectPath, _
  [ ByVal strAssocClass ], _
  [ ByVal strResultClass ], _
  [ ByVal strResultRole ], _
  [ ByVal strRole ], _
  [ ByVal bClassesOnly ], _
  [ ByVal bSchemaOnly ], _
  [ ByVal strRequiredAssocQualifier ], _
  [ ByVal strRequiredQualifier ], _
  [ ByVal iFlags ], _
  [ ByVal objWbemNamedValueSet ], _
  [ ByVal objWbemAsyncContext ] _
)

Parameters

objWbemSink: Required. Object sink that receives the objects asynchronously. Create an SWbemSink object to receive the objects.
strObjectPath: Required. String that contains the object path of the source class or instance. For more information, see Describing the Location of a WMI Object.
strAssocClass [optional]: String that contains an association class. When 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 [optional]: String that contains a class name. If specified, this optional parameter indicates that the returned endpoints must belong to or be derived from the class specified in this parameter.
strResultRole [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 [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 [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 [optional]: 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 strObjectPath parameter specifies the object path of a class. When set to TRUE, the set of returned endpoints represent classes that are suitably associated with the source class in schema.
strRequiredAssocQualifier [optional]: String that contains a qualifier name. If specified, this parameter indicates that the returned endpoints must be associated with the source object through an association class that includes the specified qualifier.
strRequiredQualifier [optional]: String that contains a qualifier name. If specified, this parameter indicates that the returned endpoints must include the specified qualifier.
iFlags [optional]: Integer that specifies the additional flags to the operation. The default for this parameter is wbemFlagDontSendStatus. This parameter can accept the following values.
wbemFlagSendStatus (128 (0x80)): Causes asynchronous calls to send status updates to the OnProgress event handler for the object sink.
wbemFlagDontSendStatus (0 (0x0)): Prevents asynchronous calls from sending status updates to the OnProgress event handler for the object sink.
wbemFlagUseAmendedQualifiers (131072 (0x20000)): Causes WMI to return class amendment data along with the base class definition. For more information about amended qualifiers, see Localizing WMI Class Information.

objWbemNamedValueSet [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.

objWbemAsyncContext [optional]

An SWbemNamedValueSet object that returns to the object sink to identify the source of the original asynchronous call. Use this parameter if you are making multiple asynchronous calls using the same object sink. To use this parameter, create an SWbemNamedValueSet object and use the SWbemNamedValueSet.Add method to add a value that identifies the asynchronous call you are making. This SWbemNamedValueSet object is returned to the object sink and the source of the call can be extracted using the SWbemNamedValueSet.Item method. For more information, see Calling a Method.

Return value

This method does not return a value. If successful, the sink receives an OnObjectReady event per instance. After the last instance, the object sink receives an OnCompleted event.

Error codes

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

wbemErrAccessDenied - 2147749891 (0x80041003): Current user does not have the permission to view one or more of the classes returned by the call.
wbemErrFailed - 2147749889 (0x80041001): Unspecified error.
wbemErrInvalidParameter - 2147749896 (0x80041008): Invalid parameter was specified.
wbemErrOutOfMemory - 2147749894 (0x80041006): Not enough memory to complete the operation.
wbemErrNotFound - 2147749890 (0x80041002): Requested item was not found.

Remarks

This call returns immediately. The requested objects and status are returned to the caller through callbacks delivered to the sink that is specified in objWbemSink. To process each object when it returns, create an objWbemSink.OnObjectReady event subroutine. After all the objects are returned, you can perform final processing in your implementation of the objWbemSink.OnCompleted event.

An asynchronous callback allows a non-authenticated user to provide data to the sink. This poses security risks to your scripts and applications. To eliminate the risks, see Setting Security on an Asynchronous Call.

Use the objWbemAsyncContext parameter in scripts to verify the source of a call.

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_SWbemServices
IID	IID_ISWbemServices