Funzione lineConfigDialogEdit (tapi.h)

Articolo
08/26/2023

La funzione lineConfigDialogEdit fa sì che il provider del dispositivo linea specificato visualizzi una finestra di dialogo (collegata a hwndOwner dell'applicazione) per consentire all'utente di configurare i parametri correlati al dispositivo linea.

Sintassi

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

Parametri

dwDeviceID

Identificatore del dispositivo linea da configurare.

hwndOwner

Handle in una finestra a cui deve essere collegata la finestra di dialogo. Può essere NULL per indicare che qualsiasi finestra creata durante la funzione non deve avere una finestra di proprietario.

lpszDeviceClass

Puntatore a una stringa con terminazione Null che identifica un nome di classe del dispositivo. Questa classe di dispositivo consente all'applicazione di selezionare una schermata secondaria specifica delle informazioni di configurazione applicabili a tale classe di dispositivo. Questo parametro è facoltativo e può essere lasciato NULL o vuoto, nel qual caso viene selezionata la configurazione di livello più alto.

lpDeviceConfigIn

Puntatore alla struttura di dati di configurazione opaca restituita da lineGetDevConfig (o una precedente chiamata di 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 lineGetDevConfig o una chiamata precedente di 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 negativo se si verifica un errore. I valori restituiti possibili sono:

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM LINEERR_NODEVICE.

Commenti

Se viene restituito LINEERR_STRUCTURETOOSMALL, il membro dwTotalSize della struttura VARSTRING a cui punta lpDeviceConfigOut non specifica memoria sufficiente per contenere l'intera struttura di configurazione. Il membro dwNeededSize è stato impostato sull'importo richiesto. Nella misura in cui le voci dell'utente si riflettevano nelle informazioni che non potevano essere restituite a causa di spazio insufficiente, tali modifiche andranno perse; le applicazioni devono quindi allocare la quantità massima di spazio che potrebbe essere necessaria dalla classe del dispositivo per restituire la struttura di configurazione.Per altre informazioni, vedere Classi di dispositivi TAPI.

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

Il parametro lpszDeviceClass consente all'applicazione di selezionare 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 lineGetID. Ad esempio, se la riga supporta l'API Comm, il passaggio di "COMM" come lpszDeviceClass fa sì che il provider visualizzi i parametri correlati in modo specifico a Comm (o, almeno, inizi dal 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 sarà "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 lineConfigDialog è l'origine dei parametri da modificare e il risultato della modifica. In 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 lineConfigDialog. Con 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. LineConfigDialogEdit consente quindi a un'applicazione di fornire all'utente la possibilità di configurare i parametri per le chiamate future senza influire su alcuna chiamata attiva. Tuttavia, l'output di questa funzione può essere passato a lineSetDevConfig per influire sulla chiamata corrente o sulla chiamata successiva.