Função lineConfigDialogEditW (tapi.h)

A função lineConfigDialogEdit faz com que o provedor do dispositivo de linha especificado exiba uma caixa de diálogo (anexada a hwndOwner do aplicativo) para permitir que o usuário configure parâmetros relacionados ao dispositivo de linha.

Sintaxe

LONG lineConfigDialogEditW(
  DWORD        dwDeviceID,
  HWND         hwndOwner,
  LPCWSTR      lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD        dwSize,
  LPVARSTRING  lpDeviceConfigOut
);

Parâmetros

dwDeviceID

Identificador do dispositivo de linha a ser configurado.

hwndOwner

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

lpszDeviceClass

Ponteiro para um cadeia de caracteresterminada nula que identifica um nome de classe de dispositivo. Essa classe de dispositivo permite que o aplicativo selecione uma sub-tela específica das informações de configuração aplicáveis a essa classe de dispositivo. Esse parâmetro é opcional e pode ser deixado NULL ou vazio, nesse caso, a configuração de nível mais alto é selecionada.

lpDeviceConfigIn

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

dwSize

Número de bytes na estrutura apontada por lpDeviceConfigIn. Esse valor é retornado no membro dwStringSize na estrutura VARSTRING retornada por lineGetDevConfig ou uma invocação anterior de lineConfigDialogEdit.

lpDeviceConfigOut

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 de VARSTRING está definido como STRINGFORMAT_BINARY. Antes de chamar lineGetDevConfig (ou uma invocação futura de lineConfigDialogEdit), o aplicativo deve definir o dwTotalSize membro dessa estrutura para indicar a quantidade de memória disponível para TAPI para retornar informações.

Valor de retorno

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_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_NODEVICE.

Observações

Se LINEERR_STRUCTURETOOSMALL for retornado, o dwTotalSize membro da estrutura VARSTRING apontado por lpDeviceConfigOut não especifica memória suficiente para conter toda a estrutura de configuração. O membro dwNeededSize foi definido como o valor necessário. Na medida em que as entradas de usuário foram refletidas em informações que não puderam ser retornadas devido a espaço insuficiente, essas edições são perdidas; os aplicativos devem, portanto, alocar a quantidade máxima de espaço que pode ser necessária pela classe de dispositivo para retornar sua estrutura de configuração (para obter mais informações, consulte classes de dispositivo TAPI).

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

O parâmetro lpszDeviceClass permite que o aplicativo selecione 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 as mesmas para lineGetID. Por exemplo, se a linha der suporte à API de Comm, passar "COMM" 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 seria "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 lineConfigDialog é a origem dos parâmetros a serem editados e o resultado da edição. Em 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 lineConfigDialog. Com 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, 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 lineSetDevConfig para afetar a chamada atual ou a próxima chamada.

Nota

O cabeçalho tapi.h define lineConfigDialogEdit como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
da Plataforma de Destino	Windows
cabeçalho	tapi.h
biblioteca	Tapi32.lib
de DLL	Tapi32.dll

Consulte também

Referência dos Serviços básicos de telefonia

visão geral de referência do TAPI 2.2

VARSTRING

lineConfigDialog

lineGetDevConfig

lineGetID

lineSetDevConfig