Método SWbemServices.AssociatorsOf
O método AssociatorsOf do objeto SWbemServices retorna uma coleção de objetos (classes ou instâncias) chamados de pontos de extremidade associados a um objeto especificado. Esse método executa a mesma função que a consulta WQL ASSOCIATORS OF.
Esse método é chamado no modo semissíncrono por padrão. 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
objWbemObjectSet = .AssociatorsOf( _
ByVal strObjectPath, _
[ ByVal strAssocClass ], _
[ ByVal strResultClass ], _
[ ByVal strResultRole ], _
[ ByVal strRole ], _
[ ByVal bClassesOnly ], _
[ ByVal bSchemaOnly ], _
[ ByVal strRequiredAssocQualifier ], _
[ ByVal strRequiredQualifier ], _
[ ByVal iFlags ], _
[ ByVal objwbemNamedValueSet ] _
)
Parâmetros
-
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. Se 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 sinalizadores adicionais para a operação. O valor padrão para esse parâmetro é wbemFlagReturnImmediately, que chama o método no modo semissíncrono. Esse parâmetro pode aceitar os valores a seguir.
-
wbemFlagForwardOnly (32 (0x20))
-
Faz com que um enumerador somente de encaminhamento seja retornado. Normalmente, os enumeradores apenas de encaminhamento são mais rápidos e usam menos memória do que os enumeradores convencionais, mas eles não permitem chamadas para SWbemObject.Clone_.
-
wbemFlagBidirectional (0 (0x0))
-
Faz com que a WMI retenha ponteiros para objetos da enumeração até que o cliente libere o enumerador.
-
wbemFlagReturnImmediately (16 (0x10))
-
Faz com que a chamada retorne imediatamente.
-
wbemFlagReturnWhenComplete (0 (0x0))
-
Faz com que essa chamada fique bloqueada até que a consulta seja concluída. Esse sinalizador chama o método no modo síncrono.
-
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, confira Como localizar informações de classe 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.
Retornar valor
Se a chamada for bem-sucedida, um objeto SWbemObjectSet será retornado.
Códigos do Erro
Após a conclusão do método AssociatorsOf, o objeto Err poderá conter um dos códigos de erro da lista a seguir.
Observação
Uma coleção retornada sem elementos não é um erro.
-
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
O método recupera as instâncias de recursos gerenciados associadas a um recurso especificado por meio de uma ou mais classes de associação. Você fornece o caminho do objeto para o ponto de extremidade de origem e AssociatorsOf retorna os recursos gerenciados no ponto de extremidade oposto. O método AssociatorsOf executa a mesma função que a consulta WQL ASSOCIATORS OF.
Para obter mais informações sobre as consultas ASSOCIATORS OF WQL, as instâncias de origem e os pontos de extremidade, confira Instrução ASSOCIATORS OF.
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 |