Função lineGetIcon (tapi.h)

Artigo
03/05/2024

A função lineGetIcon permite que um aplicativo recupere um ícone específico do dispositivo de linha de serviço (ou específico do provedor) para exibição ao usuário.

Sintaxe

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

Parâmetros

dwDeviceID

Identificador do dispositivo de linha 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 linha 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 valores retornados possíveis são:

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALDEVICECLASS, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_NODEVICE.

Comentários

A função lineGetIcon faz com que o provedor retorne um identificador (em lphIcon) para um recurso de ícone (obtido de LoadIcon) associado à linha especificada. 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 a linha aberta.

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 de lineGetID. Por exemplo, se a linha 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/line", "" ou NULL podem ser usados para solicitar o ícone para o serviço de linha.

Para aplicativos que usam uma versão de API 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 de dispositivo de linha de telefonia. Para aplicativos que usam a API versão 2.0 ou posterior, o TAPI substituirá o ícone de linha padrão somente se o parâmetro lpszDeviceClass for "tapi/line", "" 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 , lineGetIcon retornará LINEERR_INVALDEVICECLASS.