Práticas recomendadas para usar matrizes seguras

  • Artigo

Muitos métodos de interface da API do Microsoft Automação da Interface do Usuário recebem argumentos chamados de matrizes seguras, do tipo de dados SAFEARRAY. Este tópico descreve as práticas recomendadas para usar matrizes seguras em um Automação da Interface do Usuário aplicativos.

Clientes

Todas as matrizes seguras usadas com os métodos de API do cliente Automação da Interface do Usuário são matrizes unidimensionais baseadas em zero. Para criar uma matriz segura para um método de cliente Automação da Interface do Usuário, use a função SafeArrayCreateVector e, para ler e gravar em uma matriz segura, use as funções SafeArrayGetElement e SafeArrayPutElement. Quando terminar de usar uma matriz segura, sempre a destrua usando a função SafeArrayDestroy, quer você tenha criado a matriz segura ou recebido de um método de cliente Automação da Interface do Usuário.

Vários métodos Automação da Interface do Usuário, incluindo métodos de recuperação de propriedade, como GetCurrentPropertyValue, recuperam VARIANTs que podem conter estruturas POINT ou UiaRect. Um POINT é empacotado em uma VARIANT como uma matriz segura de duplos (VT_R8) com o membro x no índice 0 e o membro y no índice 1. Da mesma forma, um UiaRect é empacotado em um VARIANT como uma matriz segura de duplos com os membros esquerdo, superior, largura e altura nos índices de 0 a 3, respectivamente. Para uma matriz de estruturas UiaRect , a matriz segura contém uma matriz sequencial de quatro duplos para cada UiaRect. Os membros esquerdo, superior, largura e altura do primeiro UiaRect ocupam o índice 0 a 3, os membros do segundo retângulo ocupam o índice de 4 a 7 e assim por diante.

A interface IUIAutomation inclui os métodos a seguir para converter entre SAFEARRAY e vários outros tipos de dados.

Método Descrição
IUIAutomation::IntNativeArrayToSafeArray Converte uma matriz de inteiros em um SAFEARRAY.
IUIAutomation::IntSafeArrayToNativeArray Converte um SAFEARRAY de inteiros em uma matriz.
IUIAutomation::SafeArrayToRectNativeArray Converte um SAFEARRAY que contém coordenadas de retângulo em uma matriz do tipo RECT.

 

Provedores

Um provedor deve implementar vários métodos de interface que Automação da Interface do Usuário chamadas para recuperar informações do provedor. Muitas vezes, essas informações consistem em uma matriz de valores. Para retornar uma matriz para Automação da Interface do Usuário, o provedor deve empacotar a matriz em uma estrutura SAFEARRAY. Os elementos da matriz devem ser do tipo de dados esperado e devem aparecer na ordem esperada.

Conceitual

Visão geral das propriedades de automação da interface do usuário

Conceitos básicos de automação da interface do usuário