função TSPI_lineConfigDialogEdit (tspi.h)

Artigo
08/26/2023

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

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

Parâmetros

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 subtela específica de 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 as mesmas de 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 TSPI_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 TSPI_lineConfigDialogEdit.

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 é 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.

Retornar valor

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

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

Comentários

Essa função faz com que o provedor de serviços exiba uma caixa de diálogo modal (anexada a hwndOwner) para permitir que o usuário configure parâmetros relacionados à linha especificada por dwDeviceID.

O parâmetro lpszDeviceClass seleciona uma subtela específica de informações de configuração aplicáveis à classe de dispositivo na qual o usuário está interessado; as cadeias de caracteres permitidas são as mesmas que para 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 caixa de diálogo de configuração de vários níveis, 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 para a linha.

A diferença entre essa função e TSPI_lineConfigDialog é a origem dos parâmetros a serem editados e o resultado da edição. Em TSPI_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 TSPI_lineConfigDialog. Com TSPI_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, TSPI_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 tenta chamar essa função em um provedor mais antigo.