funzione TSPI_lineGetDevConfig (tspi.h)

Articolo
08/26/2023

La funzione TSPI_lineGetDevConfig restituisce un oggetto struttura dati, il contenuto di cui sono specifici per la riga (provider di servizi) e la classe di dispositivo, dando la configurazione corrente di un dispositivo a uno con il dispositivo linea.

Sintassi

LONG TSPIAPI TSPI_lineGetDevConfig(
  DWORD       dwDeviceID,
  LPVARSTRING lpDeviceConfig,
  LPCWSTR     lpszDeviceClass
);

Parametri

dwDeviceID

Dispositivo linea da configurare.

lpDeviceConfig

Puntatore a una struttura di dati di tipo VARSTRING in cui viene restituita la struttura di configurazione del dispositivo associato. Al termine della richiesta, il provider di servizi riempie questa struttura di dati con la configurazione del dispositivo. Il membro dwStringFormat nella struttura VARSTRING deve essere impostato su STRINGFORMAT_BINARY. Se il membro dwTotalSize della struttura VARSTRING puntato al parametro lpDeviceConfig è maggiore o uguale alla dimensione della parte fissa della struttura, il provider di servizi imposta il membro dwNeedSize sulla dimensione necessaria e restituisce zero.

lpszDeviceClass

Puntatore a una stringa Unicode con terminazione null che specifica la classe di dispositivo del dispositivo la cui configurazione è richiesta. Le stringhe della classe di dispositivo valide sono uguali a quelle specificate per la funzione TSPI_lineGetID quando viene applicata a un dispositivo linea (dwSelect ha il valore LINECALLSELECT_LINE).

Valore restituito

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

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL.

Commenti

Lo stato della chiamata è specifico del dispositivo.

Questa funzione può essere usata per recuperare una struttura di dati dal provider di servizi che specifica la configurazione di un dispositivo associato uno a uno con il dispositivo della riga. Il parametro lpszDeviceClass seleziona quale delle diverse classi di dispositivi deve essere recuperata. Il set di classi supportate è limitato a quelli i cui dispositivi corrispondono a uno-a-uno con il dispositivo linea. Per altre informazioni sulle classi di dispositivo comuni, vedere Classi di dispositivo TSPI.

Un provider di servizi deve in genere consentire la classe di dispositivo tapi/line in questa funzione. Recupera parametri con ambito "line", ad esempio l'elenco di indirizzi in questa riga, l'elenco di dispositivi hardware fisici, ad esempio porte COMM corrispondenti agli indirizzi, numero massimo di chiamate simultanee (se configurabili) e così via.

In generale, questa funzione non consente classi di dispositivi correlate ai supporti, ad esempio mci waveaudio, onde a basso livello o classi di dispositivi datamodem, perché in genere si applicano a una chiamata specifica o a un determinato indirizzo. Poiché può essere presente più di uno di questi dispositivi per riga, l'identificazione della chiamata specifica o dell'indirizzo semplicemente dal parametro dell'identificatore del dispositivo della riga in questa funzione sarebbe ambigua. Un'eccezione può essere effettuata per le classi di dispositivo specifiche delle chiamate o degli indirizzi nei casi in cui sono presenti informazioni di configurazione della classe che si applicano all'intero ambito del dispositivo linea, ad esempio le impostazioni predefinite iniziali e così via.

Esistono diversi motivi per cui il supporto eccezionale per le classi di dispositivi specifiche della chiamata e degli indirizzi è di solo un valore limitato in questa funzione. Innanzitutto, poiché queste classi possono essere ambigue su provider di servizi a più indirizzi/più chiamate, solo un subset di provider di servizi li supporta. Le applicazioni non sono probabilmente in grado di aggiungere una dipendenza specifica del dispositivo dall'inclusione di queste classi in questa funzione. In secondo luogo, poiché le "classi multimediali di livello superiore" emergono che implementano protocolli di alto livello, ad esempio l'accesso al file system con accesso esterno in termini di API di trasporto di basso livello, la configurazione per queste classi tende all'ambito "istanza" anziché all'ambito "class". L'API multimediale di alto livello deve fornire le proprie funzioni per configurare istanze specifiche delle chiamate o specifiche degli indirizzi.

Qualsiasi tipo di dispositivi e classi di dispositivi supportate da questa funzione, può potenzialmente influire su due tipi di informazioni di configurazione: permanente e temporanea. Le informazioni permanenti sono sopravvissute a diverse "apre" della riga e anche in diversi "inits" del provider di servizi stesso. Le informazioni temporanee sono sopravvissute solo all'interno di una riga "aperta" univoca. Quando la riga viene chiusa, tali informazioni temporanee recuperate o impostate tramite TSPI_lineSetDevConfig possono ripristinare i valori predefiniti o non definiti. Il chiamante può recuperare in modo affidabile qualsiasi configurazione temporanea solo da una sequenza, ad esempio TSPI_lineOpen, TSPI_lineConfigDialog, TSPI_lineGetDevConfig. Il chiamante può impostare in modo affidabile le informazioni di configurazione temporanee recuperate da tale sequenza tramite una sequenza, ad esempio TSPI_lineOpen, TSPI_lineSetDevConfig. La parte temporanea della configurazione rimane stabile solo fino alla successiva TSPI_lineConfigDialog, TSPI_lineSetDevConfig o TSPI_lineClose. Il provider di servizi deve occuparsi dell'archiviazione di qualsiasi parte permanente della configurazione, in genere in un file .ini e ricaricarlo ogni volta che viene inizializzato il provider di servizi.

Il formato esatto dei dati contenuti nella struttura restituita da questa funzione è specifico dell'API della classe line e del dispositivo, non documentata e non definita. La struttura restituita da questa funzione non può essere accessibile direttamente o modificata dall'applicazione, ma può essere archiviata solo intatta e successivamente usata in TSPI_lineSetDevConfig per ripristinare le impostazioni. La struttura non può necessariamente essere passata ad altri dispositivi, anche della stessa classe di dispositivo (anche se questo può funzionare in alcune istanze, non è garantito). Un provider di servizi deve inserire elementi nella struttura dei dati per consentire la verifica della coerenza in caso di errori dovuti a un'applicazione client che passa informazioni incompatibili.