função TUISPI_lineConfigDialog (tspi.h)

Artigo
03/09/2024

A função TUISPI_lineConfigDialog faz com que o provedor do dispositivo de linha especificado exiba uma caixa de diálogo modal como uma janela filho do hwndOwner para permitir que o usuário configure parâmetros relacionados ao dispositivo de linha. Essa função torna a função TSPI_lineConfigDialog obsoleta na versão 2.0 e posterior (com suporte na versão 1.4 e anterior).

A implementação é opcional.

Sintaxe

LONG TSPIAPI TUISPI_lineConfigDialog(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD             dwDeviceID,
  HWND              hwndOwner,
  LPCWSTR           lpszDeviceClass
);

Parâmetros

lpfnUIDLLCallback

Ponteiro para uma função que a DLL da interface do usuário pode chamar para se comunicar com a DLL do provedor de serviços para obter as informações necessárias para exibir a caixa de diálogo e enviar a configuração atualizada para o provedor de serviços.

dwDeviceID

O dispositivo de linha a ser configurado.

hwndOwner

Um identificador para uma janela pai na qual a janela da caixa de diálogo deve ser colocada.

lpszDeviceClass

Um ponteiro para uma cadeia de caracteres terminada em nulo que identifica um nome de classe de dispositivo. Essa classe de dispositivo permite que o chamador selecione uma sub-tela específica das informações de configuração aplicáveis a essa classe de dispositivo. Se esse parâmetro for NULL ou uma cadeia de caracteres vazia, a caixa de diálogo de configuração de nível mais alto deverá ser selecionada. As cadeias de caracteres permitidas são iguais às TSPI_lineGetID. Por exemplo, se a linha der suporte à API comm, passar comm/datamodem como lpszDeviceClass fará com que o provedor exiba os parâmetros relacionados especificamente ao Comm (ou, pelo menos, para iniciar no ponto correspondente em uma cadeia de caixas de diálogo de configuração multinível, para que o usuário não precise pesquisar para localizar os parâmetros desejados).)

Retornar valor

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

LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL.

Comentários

Não há nenhuma restrição de que TUISPI_lineConfigDialog ser chamado somente quando a linha for fechada. No entanto, cada provedor pode impor essa restrição em si. Quando TUISPI_lineConfigDialog é chamado, o provedor pode alertar o usuário com a mensagem "A linha está em uso por um ou mais aplicativos. Você não pode alterar a configuração de linha enquanto a linha estiver em uso" (e retornar a mensagem de erro LINEERR_INUSE). No entanto, algumas configurações podem ser seguras para alterar "em tempo real", especialmente aquelas relacionadas a tipos de mídia (como o protocolo de controle de erros de modem), especialmente quando esse tipo de mídia não está em uso no momento. O provedor pode permitir que essas opções sejam alteradas enquanto a linha está aberta.

Os usuários não devem ter permissão para alterar qualquer coisa que altere valores retornados com LINEDEVCAPS ou LINEADDRESSCAPS sem primeiro fechar a linha à força como um sinal de que os aplicativos devem chamar funções que retornam essas estruturas para ter informações precisas.