Estrutura PHONEBUTTONINFO (tapi.h)

Artigo
08/26/2023

A estrutura PHONEBUTTONINFO contém informações sobre um botão em um dispositivo de telefone. Essa estrutura é usada por várias funções TAPI e TSPI.

Sintaxe

typedef struct phonebuttoninfo_tag {
  DWORD dwTotalSize;
  DWORD dwNeededSize;
  DWORD dwUsedSize;
  DWORD dwButtonMode;
  DWORD dwButtonFunction;
  DWORD dwButtonTextSize;
  DWORD dwButtonTextOffset;
  DWORD dwDevSpecificSize;
  DWORD dwDevSpecificOffset;
  DWORD dwButtonState;
} PHONEBUTTONINFO, *LPPHONEBUTTONINFO;

Membros

dwTotalSize

Tamanho total alocado para essa estrutura de dados, em bytes.

dwNeededSize

Tamanho para essa estrutura de dados necessária para armazenar todas as informações retornadas, em bytes.

dwUsedSize

Tamanho da parte dessa estrutura de dados que contém informações úteis, em bytes.

dwButtonMode

Modo ou classe de uso geral do botão. Esse membro usa uma das constantes PHONEBUTTONMODE_.

dwButtonFunction

Função atribuída ao botão. Esse membro usa uma das constantes PHONEBUTTONFUNCTION_.

dwButtonTextSize

Tamanho do texto descritivo para o botão, em bytes.

dwButtonTextOffset

Deslocamento do início dessa estrutura para o campo de tamanho variável que contém texto descritivo para este botão. O formato dessas informações é conforme especificado no membro dwStringFormat dos recursos do dispositivo do telefone. O tamanho do campo é especificado por dwButtonTextSize.

dwDevSpecificSize

Tamanho do campo específico do dispositivo, em bytes. Se o campo específico do dispositivo for um ponteiro para uma cadeia de caracteres, o tamanho deverá incluir o terminador nulo .

dwDevSpecificOffset

Deslocamento do início da estrutura para o campo específico do dispositivo de tamanho variável. O tamanho do campo é especificado por dwDevSpecificSize.

dwButtonState

Para a função phoneGetButtonInfo , esse campo indica o estado atual do botão, usando as constantes PHONEBUTTONSTATE_. Esse campo é ignorado pela função phoneSetButtonInfo .

Comentários

As extensões específicas do dispositivo devem usar a área de tamanho variável DevSpecific (dwDevSpecificSize e dwDevSpecificOffset) dessa estrutura de dados.

Aplicativos mais antigos são compilados sem esse campo na estrutura PHONEBUTTONINFO e usando um SIZEOF PHONEBUTTONINFO menor que o novo tamanho. O aplicativo passa um parâmetro dwAPIVersion com a função phoneOpen , que pode ser usada para orientação do TAPI para lidar com essa situação. Se o aplicativo passar em um dwTotalSize menor que o tamanho da parte fixa da estrutura conforme definido no dwAPIVersion especificado, PHONEERR_STRUCTURETOOSMALL será retornado. Se a memória suficiente tiver sido alocada pelo aplicativo, antes de chamar a função TSPI_phoneGetButtonInfo , TAPI definirá os membros dwNeedEdSize e dwUsedSize para o tamanho fixo da estrutura como ela existia na versão da API especificada.

Novos provedores de serviço (que dão suporte à nova versão da API) devem examinar a versão da API passada. Se a versão da API for menor do que a versão mais alta com suporte do provedor, o provedor de serviços não deverá preencher campos sem suporte em versões de API mais antigas, pois elas cairiam na parte variável da estrutura mais antiga.

Novos aplicativos devem estar cientes da versão da API negociada e não examinar o conteúdo dos campos na parte fixa além do final original da parte fixa da estrutura para a versão da API negociada.