Método SWbemServices.AssociatorsOfAsync
O método AssociatorsOfAsync do objeto SWbemServices retorna uma coleção de objetos (classes ou instâncias) chamados de pontos de extremidade associados a um objeto especificado. A chamada para AssociatorsOfAsync é imediatamente retornada e os resultados e status são retornados ao chamador por meio de eventos entregues ao coletor especificado em objWbemSink. Para lidar com cada objeto retornado, crie um manipulador de eventos objWbemSink.OnObjectReady.
Depois que todos os objetos chegam, o processamento é feito no evento objWbemSink.OnCompleted. Esse método executa a mesma função que a consulta WQL ASSOCIATORS OF. Para obter mais informações sobre como criar um coletor, confira Como receber um evento do WMI.
O método é chamado no modo assíncrono. Para obter mais informações, confira Como chamar um método.
Para conferir uma explicação dessa sintaxe, confira Convenções de documentação para API de script.
Sintaxe
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 ] _
)
Parâmetros
-
objWbemSink
-
Obrigatórios. Coletor de objetos que recebe os objetos de maneira assíncrona. Crie um objeto SWbemSink para receber os objetos.
-
strObjectPath
-
Obrigatórios. Cadeia de caracteres que contém o caminho do objeto da classe de origem ou instância. Para obter mais informações, confira Como descrever o local de um objeto do WMI.
-
strAssocClass [opcional]
-
Cadeia de caracteres que contém uma classe de associação. Quando especificado, esse parâmetro indicará que os pontos de extremidade retornados devem ser associados à origem por meio da classe de associação especificada ou de uma classe derivada dessa classe de associação.
-
strResultClass [opcional]
-
Cadeia de caracteres que contém um nome de classe. Se especificado, este parâmetro opcional indicará que os pontos de extremidade retornados devem pertencer à classe especificada neste parâmetro ou serem derivados dela.
-
strResultRole [opcional]
-
Cadeia de caracteres que contém um nome de propriedade. Se especificado, esse parâmetro indicará que os pontos de extremidade retornados devem desempenhar uma função específica na associação com o objeto de origem. A função é definida pelo nome de uma propriedade especificada (que deve ser uma propriedade de referência) de uma associação.
-
strRole [opcional]
-
Cadeia de caracteres que contém um nome de propriedade. Se especificado, esse parâmetro indicará que os pontos de extremidade retornados devem participar de uma associação com o objeto de origem no qual o objeto de origem desempenha uma função específica. A função é definida pelo nome de uma propriedade especificada (que deve ser uma propriedade de referência) de uma associação.
-
bClassesOnly [opcional]
-
Valor booliano que indica se uma lista de nomes de classe deve ser retornada no lugar das instâncias reais das classes. Essas são as classes às quais as instâncias de ponto de extremidade pertencem. O valor padrão para esse parâmetro é FALSE.
-
bSchemaOnly [opcional]
-
Valor booliano que indica se a consulta se aplica ao esquema em vez dos dados. O valor padrão para esse parâmetro é FALSE. Ele só poderá ser definido como TRUE se o parâmetro strObjectPath especificar o caminho do objeto de uma classe. Quando definido como TRUE, o conjunto de pontos de extremidade retornados representará classes que estão adequadamente associadas à classe de origem no esquema.
-
strRequiredAssocQualifier [opcional]
-
Cadeia de caracteres que contém um nome de qualificador. Se especificado, esse parâmetro indicará que os pontos de extremidade retornados devem ser associados ao objeto de origem por meio de uma classe de associação que inclui o qualificador especificado.
-
strRequiredQualifier [opcional]
-
Cadeia de caracteres que contém um nome de qualificador. Se especificado, esse parâmetro indicará que os pontos de extremidade retornados devem incluir o qualificador especificado.
-
iFlags [opcional]
-
Inteiro que especifica os sinalizadores adicionais para a operação. O padrão para esse parâmetro é wbemFlagDontSendStatus. Esse parâmetro pode aceitar os valores a seguir.
-
wbemFlagSendStatus (128 (0x80))
-
Faz com que chamadas assíncronas enviem atualizações de status ao manipulador de eventos OnProgress para o coletor de objetos.
-
wbemFlagDontSendStatus (0 (0x0))
-
Evita que chamadas assíncronas enviem atualizações de status ao manipulador de eventos OnProgress do coletor de objetos.
-
wbemFlagUseAmendedQualifiers (131072 (0x20000))
-
Faz com que o WMI retorne dados de aditamento da classe juntamente com a definição da classe base. Para obter mais informações sobre qualificadores alterados, confira Como localizar informações de classe do WMI.
objWbemNamedValueSet [opcional]
Normalmente, isso é indefinido. Caso contrário, esse será um objeto SWbemNamedValueSet cujos elementos representam as informações de contexto que podem ser usadas pelo provedor que está atendendo à solicitação. Um provedor que dê suporte ou exija essas informações deve documentar os nomes de valor reconhecidos, o tipo de dados do valor, os valores permitidos e a semântica.
objWbemAsyncContext [opcional]
Um objeto SWbemNamedValueSet que é retornado ao coletor de objetos para identificar a origem da chamada assíncrona original. Use esse parâmetro se estiver fazendo várias chamadas assíncronas usando o mesmo coletor de objetos. Para usar esse parâmetro, crie um objeto SWbemNamedValueSet e use o método SWbemNamedValueSet.Add para adicionar um valor que identifique a chamada assíncrona que você está fazendo. Esse objeto SWbemNamedValueSet é retornado ao coletor de objeto, e a origem da chamada pode ser extraída usando o método SWbemNamedValueSet.Item. Para obter mais informações, confira Como chamar um método.
Retornar valor
Esse método não retorna um valor. Se tiver êxito, o coletor receberá um evento OnObjectReady por instância. Após a última instância, o coletor de objetos receberá um evento OnCompleted.
Códigos do Erro
Após a conclusão do método AssociatorsOfAsync, o objeto Err poderá conter um dos códigos de erro da lista a seguir.
-
wbemErrAccessDenied – 2147749891 (0x80041003)
-
O usuário atual não tem a permissão para exibir uma ou mais das classes retornadas pela função.
-
wbemErrFailed – 2147749889 (0x80041001)
-
Erro não especificado.
-
wbemErrInvalidParameter – 2147749896 (0x80041008)
-
Foi especificado um parâmetro inválido.
-
wbemErrOutOfMemory – 2147749894 (0x80041006)
-
Não há memória suficiente para concluir a operação.
-
wbemErrNotFound – 2147749890 (0x80041002)
-
O item solicitado não foi encontrado.
Comentários
Essa chamada é retornada imediatamente. Os objetos solicitados e o status são retornados ao chamador por meio de retornos de chamada entregues ao coletor especificado no objWbemSink. Para processar cada objeto quando ele retornar, crie uma sub-rotina de evento objWbemSink.OnObjectReady. Depois que todos os objetos forem retornados, você poderá executar o processamento final na implementação do evento objWbemSink.OnCompleted.
Um retorno de chamada assíncrono permite que um usuário não autenticado forneça dados ao coletor. Isso representa riscos de segurança para seus scripts e aplicativos. Para eliminar os riscos, consulte Configurar a segurança em uma chamada assíncrona.
Use o parâmetro objWbemAsyncContext em scripts para verificar a origem de uma chamada.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte |
Windows Vista |
| Servidor mínimo com suporte |
Windows Server 2008 |
| Cabeçalho |
|
| Biblioteca de tipos |
|
| DLL |
|
| CLSID |
CLSID_SWbemServices |
| IID |
IID_ISWbemServices |