Função lineTranslateDialog (tapi.h)

Artigo
08/26/2023

A função lineTranslateDialog exibe uma caixa de diálogo modal do aplicativo que permite ao usuário alterar o local atual de um número de telefone prestes a ser discado, ajustar o local e chamar parâmetros cartão e ver o efeito.

Sintaxe

LONG lineTranslateDialog(
  HLINEAPP hLineApp,
  DWORD    dwDeviceID,
  DWORD    dwAPIVersion,
  HWND     hwndOwner,
  LPCSTR   lpszAddressIn
);

Parâmetros

hLineApp

Identificador de aplicativo retornado por lineInitializeEx. Se um aplicativo ainda não tiver chamado a função lineInitializeEx , ele poderá definir o parâmetro hLineApp como zero.

dwDeviceID

Identificador de dispositivo para o dispositivo de linha no qual a chamada se destina a ser discada, para que as variações nos procedimentos de discagem em diferentes linhas possam ser aplicadas ao processo de tradução.

dwAPIVersion

Versão mais alta do TAPI com suporte pelo aplicativo (não necessariamente o valor negociado por lineNegotiateAPIVersion no dispositivo de linha indicado por dwDeviceID).

hwndOwner

Manipule para uma janela à qual a caixa de diálogo deve ser anexada. Pode ser um valor NULL para indicar que qualquer janela criada durante a função não deve ter nenhuma janela de proprietário.

lpszAddressIn

Ponteiro para uma cadeia de caracteres terminada em nulo que contém um número de telefone usado, na parte inferior da caixa de diálogo, para mostrar o efeito das alterações do usuário nos parâmetros de localização. O número deve estar no formato canônico; se não for canônico, a parte do número de telefone da caixa de diálogo não será exibida. Esse ponteiro pode ser deixado NULL, caso em que a parte número de telefone da caixa de diálogo não é exibida. Se o parâmetro lpszAddressIn contiver um subaddress ou um campo de nome ou endereços adicionais separados do primeiro endereço por caracteres CR e LF, somente o primeiro endereço será usado na caixa de diálogo.

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:

LINEERR_BADDEVICEID, LINEERR_INVALPARAM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_INVALPOINTER, LINEERR_INIFILECORRUPT, LINEERR_NODRIVER, LINEERR_INUSE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED.

Comentários

No TAPI versão 2.0 ou posterior, é possível que várias instâncias dessa caixa de diálogo sejam abertas. Em versões TAPI anteriores à 2.0, LINEERR_INUSE será retornado se a caixa de diálogo já estiver exibida por outro aplicativo (ela não poderá ser aberta mais de uma vez). Nessas versões, o TAPI traz a caixa de diálogo existente para a frente e o erro indica que todas as particularidades relacionadas ao endereço passado pelo aplicativo atual não foram tratadas, pois esse endereço não foi processado pela função.

O aplicativo deve chamar lineGetTranslateCaps após essa função para obter quaisquer alterações feitas pelo usuário nos parâmetros de tradução de endereço de telefonia e chamar lineTranslateAddress para obter uma cadeia de caracteres discável com base nas novas seleções do usuário.

Se qualquer função relacionada à tradução de endereços (por exemplo, lineGetTranslateCaps ou lineTranslateAddress) retornar LINEERR_INIFILECORRUPT, o aplicativo deverá chamar lineTranslateDialog. A função lineTranslateDialog detecta os erros e os corrige e relata a ação executada ao usuário.