função TUISPI_lineConfigDialogEdit (tspi.h)

Artigo
08/26/2023

A função TUISPI_lineConfigDialogEdit 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_lineConfigDialogEdit 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_lineConfigDialogEdit(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD             dwDeviceID,
  HWND              hwndOwner,
  LPCWSTR           lpszDeviceClass,
  LPVOID const      lpDeviceConfigIn,
  DWORD             dwSize,
  LPVARSTRING       lpDeviceConfigOut
);

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.

dwDeviceID

O dispositivo de linha a ser configurado.

hwndOwner

Um identificador para uma janela à qual a caixa de diálogo deve ser anexada.

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 sub-tela específica das informações de configuração aplicáveis a essa classe de dispositivo. Se esse parâmetro for NULL ou apontar para uma cadeia de caracteres vazia, a configuração de nível mais alto será selecionada. As cadeias de caracteres permitidas são iguais às TSPI_lineGetID.

lpDeviceConfigIn

Um ponteiro para a estrutura de dados de configuração opaca que foi retornada por TSPI_lineGetDevConfig (ou uma invocação anterior de TUISPI_lineConfigDialogEdit) na parte variável da estrutura VARSTRING .

dwSize

O número de bytes na estrutura apontada por lpDeviceConfigIn. Esse valor é retornado no membro dwStringSize na estrutura VARSTRING retornada por TSPI_lineGetDevConfig ou uma invocação anterior de TUISPI_lineConfigDialogEdit.

Nota Se os parâmetros de tamanho na estrutura não estiverem corretos, há a possibilidade de que os dados possam ser substituídos. Para obter mais informações sobre como definir tamanhos de estrutura, consulte o tópico alocação de memória .

lpDeviceConfigOut

Um ponteiro para o local de memória do tipo VARSTRING em que a estrutura de configuração do dispositivo é retornada. Após a conclusão bem-sucedida da solicitação, esse local é preenchido com a configuração do dispositivo. O membro dwStringFormat na estrutura VARSTRING está definido como STRINGFORMAT_BINARY. Antes de chamar lineGetDevConfig (ou uma invocação futura de lineConfigDialogEdit), o aplicativo deve definir o membro dwTotalSize dessa estrutura para indicar a quantidade de memória disponível para TAPI para retornar informações.

Valor retornado

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

LINEERR_INVALDEVICECLASS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM.

Comentários

O parâmetro lpszDeviceClass seleciona uma sub-tela específica das informações de configuração aplicáveis à classe de dispositivo na qual o usuário está interessado; 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, comece no ponto correspondente em uma cadeia de caixas de diálogo de configuração multinível, para que o usuário não precise "cavar" para localizar os parâmetros de interesse).

O parâmetro lpszDeviceClass é "tapi/line", "" ou NULL para fazer com que o provedor exiba a configuração de nível mais alto da linha.

A diferença entre essa função e TUISPI_lineConfigDialog é a origem dos parâmetros a serem editados e o resultado da edição. Em TUISPI_lineConfigDialog, os parâmetros editados são aqueles atualmente em uso no dispositivo (ou definidos para uso na próxima chamada) e quaisquer alterações feitas têm (na extensão máxima possível) um impacto imediato em qualquer conexão ativa; além disso, o aplicativo deve usar lineGetDevConfig para buscar o resultado de alterações de parâmetro de TUISPI_lineConfigDialog. Com TUISPI_lineConfigDialogEdit, os parâmetros a serem editados são passados do aplicativo e os resultados são retornados para o aplicativo, sem impacto nas conexões ativas; os resultados da edição são retornados com essa função e o aplicativo não precisa chamar lineGetDevConfig. Assim, TUISPI_lineConfigDialogEdit permite que um aplicativo forneça a capacidade do usuário de configurar parâmetros para chamadas futuras sem ter impacto em nenhuma chamada ativa. No entanto, a saída dessa função pode ser passada para TSPI_lineSetDevConfig para afetar a chamada atual ou a próxima chamada.

Para compatibilidade com versões anteriores, essa função não é exportada por provedores de serviços mais antigos. O TAPI detecta essa condição e relata LINEERR_OPERATIONUNAVAIL se um aplicativo tentar chamar essa função em um provedor mais antigo.