funzione TSPI_lineSetDevConfig (tspi.h)

Articolo
03/09/2024

La funzione TSPI_lineSetDevConfig ripristina la configurazione di un dispositivo associato uno a uno con il dispositivo linea da una struttura di dati ottenuta in precedenza usando TSPI_lineGetDevConfig. Il contenuto di questa struttura di dati è specifico della riga [provider di servizi] e della classe del dispositivo.

Sintassi

LONG TSPIAPI TSPI_lineSetDevConfig(
  DWORD        dwDeviceID,
  LPVOID const lpDeviceConfig,
  DWORD        dwSize,
  LPCWSTR      lpszDeviceClass
);

Parametri

dwDeviceID

Dispositivo linea da configurare.

lpDeviceConfig

Puntatore alla struttura dei dati di configurazione restituita nella parte variabile della struttura VARSTRING da TSPI_lineGetDevConfig.

dwSize

Numero di byte nella struttura a cui punta lpDeviceConfig. Questo valore viene restituito nel membro dwStringSize della struttura VARSTRING restituito da TSPI_lineGetDevConfig.

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

lpszDeviceClass

Puntatore a una stringa Unicode con terminazione Null che specifica la classe di dispositivo del dispositivo la cui configurazione deve essere ripristinata. Le stringhe di classe dispositivo valide sono uguali a quelle specificate per la funzione TSPI_lineGetID quando viene applicata a un dispositivo "line", ovvero quando 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:

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

Commenti

Lo stato della chiamata è specifico del dispositivo.

Il provider di servizi restituisce LINEERR_INVALPARAM se le informazioni contenute nella struttura a cui punta lpDeviceConfig non sono valide per questo dispositivo.

Il provider di servizi restituisce LINEERR_INVALLINESTATE se la configurazione del dispositivo non può essere modificata nello stato della riga corrente. La riga può essere utilizzata da un'altra applicazione.

Questa funzione può essere usata per ripristinare la configurazione di un dispositivo associato uno a uno con il dispositivo linea da una struttura di dati recuperata in precedenza dal provider di servizi usando la funzione TSPI_lineGetDevConfig . Il parametro lpszDeviceClass seleziona quale tra le diverse classi di dispositivi deve essere ripristinata. Il set di classi supportate è limitato a quelli i cui dispositivi corrispondono uno a uno con il dispositivo linea. Per altre informazioni sulle classi di dispositivi comuni, vedere Classi di dispositivi TSPI.

Un provider di servizi consente in genere la classe del dispositivo tapi/line in questa funzione. Ripristina i parametri con ambito "line", ad esempio l'elenco di indirizzi in questa riga e l'elenco di dispositivi hardware fisici, ad esempio le porte COMM corrispondenti agli indirizzi o il numero massimo di chiamate simultanee (se configurabili).

In generale, questa funzione non consente classi di dispositivi correlate ai supporti, ad esempio mci waveaudio, onde di basso livello o classi di dispositivi datamodem, perché in genere si applicano a una chiamata specifica o a un indirizzo specifico. Poiché può essere presente più di uno di questi dispositivi per riga, l'identificazione della chiamata o dell'indirizzo specifico è semplicemente tramite il parametro dell'identificatore del dispositivo della riga in questa funzione è ambiguo. È possibile creare un'eccezione per le classi di dispositivo specifiche della chiamata o specifiche dell'indirizzo nei casi in cui sono presenti informazioni di configurazione della classe che si applicano all'intero ambito del dispositivo riga, ad esempio le impostazioni predefinite iniziali.

Esistono diversi motivi per cui il supporto eccezionale per le classi di dispositivi specifiche delle chiamate e specifiche dell'indirizzo è di solo un valore limitato in questa funzione. In primo luogo, poiché queste classi possono essere ambigue in più indirizzi, provider di servizi con più chiamate, solo un subset di provider di servizi li supporta. È probabile che i programmi dell'applicazione non aggiungano una dipendenza specifica del dispositivo dall'inclusione di queste classi in questa funzione. In secondo luogo, man mano che emergono classi multimediali di livello superiore 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 verso l'ambito dell'istanza anziché l'ambito della classe. L'API multimediale di alto livello deve fornire le proprie funzioni per configurare istanze specifiche della chiamata o specifiche dell'indirizzo.

Qualsiasi tipo di dispositivi e classi di dispositivi supportate da questa funzione, può influire potenzialmente su due tipi di informazioni di configurazione: permanente e temporanea. Le informazioni permanenti sopravvivono in diverse "entità" della linea e anche in diversi "inits" del provider di servizi stesso. Le informazioni temporanee sopravvivono solo all'interno di una "apertura" univoca della riga. Quando la riga viene chiusa, le informazioni temporanee impostate o recuperate tramite TSPI_lineGetDevConfig 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 di .ini e ricaricarlo ogni volta che viene inizializzato il provider di servizi.

Il formato esatto dei dati contenuti all'interno della struttura passata a questa funzione è specifico per l'API della classe line e del dispositivo, non è documentato e non è definito. La struttura passata a questa funzione non può essere accessibile direttamente o modificata dall'applicazione, ma può essere archiviata intatta e successivamente usata da un TSPI_lineGetDevConfig precedente per ottenere le impostazioni. La struttura non può essere necessariamente passata ad altri dispositivi, anche della stessa classe di dispositivo (anche se questa operazione può funzionare in alcuni casi, non è garantita). Un provider di servizi deve verificare la coerenza di questa struttura di dati per evitare errori dovuti al passaggio di informazioni incompatibili da un'applicazione client.

Nota Alcuni provider di servizi possono consentire l'impostazione della configurazione mentre un dispositivo è in uso e altri potrebbero non essere in uso.