Função phoneGetIcon (tapi.h)

Artigo
08/26/2023

A função phoneGetIcon permite que um aplicativo recupere um ícone específico do dispositivo de telefone de serviço (ou específico do provedor) que pode ser exibido para o usuário.

Sintaxe

LONG phoneGetIcon(
  DWORD   dwDeviceID,
  LPCSTR  lpszDeviceClass,
  LPHICON lphIcon
);

Parâmetros

dwDeviceID

Identificador do dispositivo de telefone cujo ícone é solicitado.

lpszDeviceClass

Ponteiro para uma cadeia de caracteres terminada em nulo que identifica um nome de classe de dispositivo. Essa classe de dispositivo permite que o aplicativo selecione um subconjunto específico aplicável a essa classe de dispositivo. Esse parâmetro é opcional e pode ser deixado NULL ou vazio, nesse caso, o ícone de nível mais alto associado ao dispositivo de telefone em vez de um dispositivo de fluxo de mídia especificado seria selecionado.

lphIcon

Ponteiro para um local de memória no qual o identificador para o ícone é retornado.

Retornar valor

Retornará zero se a solicitação for bem-sucedida ou um número de erro negativo se ocorrer um erro. Os possíveis valores retornados são:

PHONEERR_BADDEVICEID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALDEVICECLASS, PHONEERR_UNINITIALIZED, PHONEERR_NOMEM, PHONEERR_NODEVICE.

Comentários

A função phoneGetIcon faz com que o provedor retorne um identificador (em lphIcon) para um recurso de ícone (obtido do LoadIcon) associado ao telefone especificado. O identificador de ícone é para um recurso associado ao provedor; o aplicativo deverá usar CopyIcon se quiser referenciar o ícone depois que o provedor for descarregado, o que é improvável que aconteça desde que o aplicativo tenha o telefone aberto.

O parâmetro lpszDeviceClass permite que o provedor retorne ícones diferentes com base no tipo de serviço que está sendo referenciado pelo chamador. As cadeias de caracteres permitidas são as mesmas do phoneGetID. Por exemplo, se o telefone der suporte à API comm, passar "COMM" como lpszDeviceClass fará com que o provedor retorne um ícone relacionado especificamente às funções de dispositivo Comm do provedor de serviços. Os parâmetros "tapi/phone", "" ou NULL podem ser usados para solicitar o ícone para o serviço de telefone.

Para aplicativos que usam uma versão TAPI anterior à 2.0, se o provedor não retornar um ícone (seja porque a classe de dispositivo fornecida é inválida ou o provedor não dá suporte a ícones), o TAPI substitui um ícone genérico do dispositivo de telefonia telefônica. Para aplicativos que usam o TAPI versão 2.0 ou posterior, o TAPI substituirá o ícone de telefone padrão somente se o parâmetro lpszDeviceClass for "tapi/phone", "" ou NULL. Para qualquer outra classe de dispositivo, se a classe de dispositivo fornecida não for válida ou o provedor não oferecer suporte a ícones para a classe , phoneGetIcon retornará PHONEERR_INVALDEVICECLASS.