funzione TSPI_lineConfigDialogEdit (tspi.h)

Articolo
08/26/2023

La funzione TSPI_lineConfigDialogEdit è obsoleta. I provider di servizi TAPI versione 1.4 o precedenti possono implementare questa funzione TSPI. I TSP tapi versione 2.0 o successiva implementano TUISPI_lineConfigDialogEdit.

La funzione TSPI_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.

Sintassi

LONG TSPIAPI TSPI_lineConfigDialogEdit(
  DWORD        dwDeviceID,
  HWND         hwndOwner,
  LPCSTR       lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD        dwSize,
  LPVARSTRING  lpDeviceConfigOut
);

Parametri

dwDeviceID

Dispositivo linea da configurare.

hwndOwner

Handle di una finestra a cui deve essere collegata la finestra di dialogo.

lpszDeviceClass

Puntatore a una stringa Unicode con terminazione Null che identifica un nome di classe del dispositivo. Questa classe di dispositivo consente al chiamante di selezionare una schermata secondaria specifica delle informazioni di configurazione applicabili a tale classe del 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 TSPI_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 TSPI_lineConfigDialogEdit.

lpDeviceConfigOut

Puntatore alla posizione di memoria di tipo VARSTRING in cui viene restituita la struttura di configurazione del dispositivo. Al termine della richiesta, questa posizione viene compilata 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 per TAPI per restituire informazioni.

Valore restituito

Restituisce zero se la richiesta ha esito positivo o 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

Questa funzione fa sì che il provider di servizi visualizzi una finestra di dialogo modale (collegata a hwndOwner) per consentire all'utente di configurare i parametri correlati alla riga specificata da dwDeviceID.

Il parametro lpszDeviceClass seleziona una schermata secondaria 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, il passaggio di comm/datamodem come lpszDeviceClass fa in modo che il provider visualizzi i parametri correlati in modo specifico a Comm (o, almeno, iniziare 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 fare in modo che il provider visualizzi la configurazione di livello più alto per la riga.

La differenza tra questa funzione e TSPI_lineConfigDialog è l'origine dei parametri da modificare e il risultato della modifica. In TSPI_lineConfigDialog, i parametri modificati sono quelli attualmente in uso nel dispositivo (o impostati per l'uso nella chiamata successiva) e le eventuali modifiche apportate hanno (nella massima misura possibile) un impatto immediato su qualsiasi connessione attiva; inoltre, l'applicazione deve usare lineGetDevConfig per recuperare il risultato delle modifiche dei parametri da TSPI_lineConfigDialog. Con TSPI_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, TSPI_lineConfigDialogEdit consente a un'applicazione di fornire all'utente la possibilità di configurare i parametri per le chiamate future senza avere un impatto su alcuna 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.