função TSPI_lineConfigDialog (tspi.h)

Artigo
03/13/2024

A função TSPI_lineConfigDialog está obsoleta. Os provedores de serviços TAPI versão 1.4 ou anteriores podem implementar essa função TSPI. Os TSPs tapi versão 2.0 ou posterior implementam TUISPI_lineConfigDialog.

A função TSPI_lineConfigDialog faz com que o provedor do dispositivo de linha especificado exiba uma caixa de diálogo modal como uma janela filho de hwndOwner para permitir que o usuário configure parâmetros relacionados ao dispositivo de linha.

Sintaxe

LONG TSPIAPI TSPI_lineConfigDialog(
  DWORD  dwDeviceID,
  HWND   hwndOwner,
  LPCSTR lpszDeviceClass
);

Parâmetros

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 Unicode terminada em nulo que identifica um nome de classe de dispositivo. Essa classe de dispositivo permite que o chamador selecione uma subtela específica de 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 as mesmas de 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 caixa de diálogo de configuração de vários níveis, 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 valores retornados possíveis são os seguintes:

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

Comentários

O procedimento deve atualizar a seção [Telefonia do Windows] no arquivo Win.ini e transmitir a mensagem WM_WININICHANGE se fizer alterações no arquivo Telephon.ini que causariam uma alteração nos recursos de linha ou endereço relatados em LINEDEVCAPS ou LINEADDRESSCAPS ou se um dispositivo de linha for criado ou removido.

Não há nenhuma restrição de que essa função (TSPI_lineConfigDialog) seja chamada somente quando a linha for fechada. No entanto, cada provedor pode impor essa restrição em si. Quando TSPI_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.