funzione TUISPI_lineConfigDialogEdit (tspi.h)

Articolo
03/08/2023

La funzione TUISPI_lineConfigDialogEdit fa sì che il provider del dispositivo linea specificato visualizzi una finestra di dialogo modale come finestra figlio di hwndOwner per consentire all'utente di configurare i parametri correlati al dispositivo linea. Questa funzione rende obsoleta la funzione TSPI_lineConfigDialogEdit nella versione 2.0 e successiva (supportata nella versione 1.4 e versioni precedenti).

L'implementazione è facoltativa.

Sintassi

LONG TSPIAPI TUISPI_lineConfigDialogEdit(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD             dwDeviceID,
  HWND              hwndOwner,
  LPCWSTR           lpszDeviceClass,
  LPVOID const      lpDeviceConfigIn,
  DWORD             dwSize,
  LPVARSTRING       lpDeviceConfigOut
);

Parametri

lpfnUIDLLCallback

Puntatore a una funzione che la DLL dell'interfaccia utente può chiamare per comunicare con la DLL del provider di servizi per ottenere informazioni necessarie per visualizzare la finestra di dialogo.

dwDeviceID

Dispositivo linea da configurare.

hwndOwner

Handle a una finestra a cui collegare la finestra di dialogo.

lpszDeviceClass

Puntatore a una stringa Unicode con terminazione null che identifica un nome della classe di dispositivo. Questa classe di dispositivo consente al chiamante di selezionare una sottoscreen specifica delle informazioni di configurazione applicabili a tale classe di dispositivo. Se questo parametro è NULL o punta a una stringa vuota, viene selezionata la configurazione di livello più alto. Le stringhe consentite sono uguali a per TSPI_lineGetID.

lpDeviceConfigIn

Puntatore alla struttura di dati di configurazione opaca restituita da TSPI_lineGetDevConfig (o una chiamata precedente di TUISPI_lineConfigDialogEdit) nella parte variabile della struttura VARSTRING .

dwSize

Numero di byte nella struttura a cui punta lpDeviceConfigIn. Questo valore viene restituito nel membro dwStringSize nella struttura VARSTRING restituito da TSPI_lineGetDevConfig o una chiamata precedente di TUISPI_lineConfigDialogEdit.

Nota Se i parametri delle dimensioni nella struttura non sono corretti, è possibile che i dati possano essere sovrascritti. Per altre informazioni sull'impostazione delle dimensioni della struttura, vedere l'argomento relativo all'allocazione della memoria .

lpDeviceConfigOut

Puntatore alla posizione di memoria del tipo VARSTRING in cui viene restituita la struttura di configurazione del dispositivo. Al termine della richiesta, questa posizione viene riempita con la configurazione del dispositivo. Il membro dwStringFormat nella struttura VARSTRING è impostato su STRINGFORMAT_BINARY. Prima di chiamare lineGetDevConfig (o una chiamata futura di lineConfigDialogEdit), l'applicazione deve impostare il membro dwTotalSize di questa struttura per indicare la quantità di memoria disponibile a TAPI per restituire informazioni.

Valore restituito

Restituisce zero se la richiesta ha esito positivo o un numero di errore se si verifica un errore. I valori restituiti possibili sono:

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

Commenti

Il parametro lpszDeviceClass seleziona una sottoscreen specifica delle informazioni di configurazione applicabili alla classe di dispositivo in cui l'utente è interessato; le stringhe consentite sono uguali a per TSPI_lineGetID. Ad esempio, se la riga supporta l'API Comm, passando comm/datamodem come lpszDeviceClass fa sì che il provider visualizzi i parametri correlati in modo specifico a Comm (o, almeno, inizia al punto corrispondente in una catena di finestre di dialogo di configurazione multilivello, quindi l'utente non deve "scavare" per trovare i parametri di interesse).

Il parametro lpszDeviceClass è "tapi/line", "" o NULL per consentire al provider di visualizzare la configurazione di livello più alto per la riga.

La differenza tra questa funzione e TUISPI_lineConfigDialog è l'origine dei parametri da modificare e il risultato della modifica. In TUISPI_lineConfigDialog, i parametri modificati sono attualmente in uso nel dispositivo (o impostati per l'uso nella chiamata successiva) e le modifiche apportate (al massimo possibile) hanno un impatto immediato su qualsiasi connessione attiva; inoltre, l'applicazione deve usare lineGetDevConfig per recuperare il risultato delle modifiche dei parametri da TUISPI_lineConfigDialog. Con TUISPI_lineConfigDialogEdit, i parametri da modificare vengono passati dall'applicazione e i risultati vengono restituiti all'applicazione, senza alcun impatto sulle connessioni attive; i risultati della modifica vengono restituiti con questa funzione e l'applicazione non deve chiamare lineGetDevConfig. Pertanto, TUISPI_lineConfigDialogEdit consente a un'applicazione di fornire all'utente la possibilità di configurare i parametri per le chiamate future senza avere un impatto su qualsiasi chiamata attiva. Tuttavia, l'output di questa funzione può essere passato a TSPI_lineSetDevConfig per influire sulla chiamata corrente o sulla chiamata successiva.

Per la compatibilità con le versioni precedenti, questa funzione non viene esportata dai provider di servizi meno recenti. TAPI rileva questa condizione e segnala LINEERR_OPERATIONUNAVAIL se un'applicazione tenta di chiamare questa funzione in un provider precedente.