Função lineConfigDialogEdit (tapi.h)

Artigo
03/08/2023

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 lineConfigDialogEdit(
  DWORD        dwDeviceID,
  HWND         hwndOwner,
  LPCSTR       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 uma cadeia de caracteres terminada em nulo 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 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.

Retornar valor

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.

Comentários

Se LINEERR_STRUCTURETOOSMALL for retornado, o membro dwTotalSize da estrutura VARSTRING apontada por lpDeviceConfigOut não especificará memória suficiente para conter toda a estrutura de configuração. O membro dwNeedSize 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; portanto, os aplicativos devem 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 que para lineGetID. Por exemplo, se a linha der suporte à API 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.