funzione TSPI_providerInit (tspi.h)

Articolo
08/26/2023

La funzione TSPI_providerInit inizializza il provider di servizi e lo fornisce i parametri necessari per le operazioni successive.

Sintassi

LONG TSPIAPI TSPI_providerInit(
  DWORD            dwTSPIVersion,
  DWORD            dwPermanentProviderID,
  DWORD            dwLineDeviceIDBase,
  DWORD            dwPhoneDeviceIDBase,
  DWORD_PTR        dwNumLines,
  DWORD_PTR        dwNumPhones,
  ASYNC_COMPLETION lpfnCompletionProc,
  LPDWORD          lpdwTSPIOptions
);

Parametri

dwTSPIVersion

Versione della definizione TSPI in cui questa funzione deve funzionare. Il chiamante può usare TSPI_lineNegotiateTSPIVersion con il INITIALIZE_NEGOTIATION dwDeviceIDspeciale per negoziare una versione che è garantita essere accettabile per il provider di servizi.

dwPermanentProviderID

Identificatore permanente, univoco all'interno dei provider di servizi in questo sistema, del provider di servizi inizializzato.

dwLineDeviceIDBase

Identificatore del dispositivo più basso per i dispositivi di riga supportati da questo provider di servizi.

dwPhoneDeviceIDBase

Identificatore del dispositivo più basso per i dispositivi telefonici supportati da questo provider di servizi.

dwNumLines

Il numero di dispositivi di riga supportati da questo provider di servizi. Il valore restituito è il numero di dispositivi di riga segnalati in TSPI_providerEnumDevices.

dwNumPhones

Numero di dispositivi telefonici supportati da questo provider di servizi. Il valore restituito è il numero di dispositivi telefonici segnalati in TSPI_providerEnumDevices.

lpfnCompletionProc

La procedura chiama il provider di servizi per segnalare il completamento di tutte le procedure operative in modo asincrono nei dispositivi line e phone.

lpdwTSPIOptions

Puntatore a un percorso di memoria di dimensioni DWORD, in cui il provider di servizi può scrivere un valore che specifica LINETSPIOPTIONS_ valori. Questo parametro consente al provider di servizi di restituire bit che indicano comportamenti facoltativi desiderati di TAPI. TAPI imposta le opzioni DWORD su 0 prima di chiamare TSPI_providerInit, quindi se il provider di servizi non vuole nessuna di queste opzioni, può solo lasciare la DWORD impostata su 0.

A questo punto, viene definito un solo bit da restituire tramite questo puntatore: LINETSPIOPTION_NONREENTRANT. Il provider di servizi imposta questo bit se non è progettato per un'operazione multithreading, multithreading, multiprocessore (ad esempio, aggiornamento dei dati globali protetti da mutex). Quando questo bit è impostato, TAPI effettua una sola chiamata alla volta al provider di servizi; non chiama alcun altro punto di ingresso, né tale punto di ingresso, fino a quando il provider di servizi non restituisce dalla chiamata di funzione originale. Senza questo set di bit, TAPI può chiamare in più punti di ingresso del provider di servizi, inclusi più volte allo stesso punto di ingresso, contemporaneamente (in realtà in un sistema multiprocessore).

NotaImportante: è necessario sottolineare che l'impostazione di questo bit degrada le prestazioni. È consigliabile usare questa opzione solo per lo sviluppo, ma non per un provider di servizi di produzione fornito.

TAPI non serializza l'accesso alle funzioni TSPI che visualizzano una finestra di dialogo ( TUISPI_lineConfigDialog , TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, TUISPI_providerRemove ) in modo che non blocchino altre funzioni TSPI da chiamare; il provider di servizi deve includere la protezione interna in queste funzioni.

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_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_NOMULTIPLEINSTANCE.

Commenti

Questa funzione deve essere chiamata prima di qualsiasi altra funzione preceduta da TSPI_line oTSPI_phone tranne TSPI_lineNegotiateTSPIVersion. È strettamente associato a una chiamata successiva a TSPI_providerShutdown Queste coppie possono sovrapporsi, ad esempio, quando l'utilità Telefonia Pannello di controllo fornita con La telefonia windows nelle versioni 1.4 e versioni precedenti viene usata mentre le operazioni di telefonia sono in corso. La chiamata a questa funzione deve essere ignorata (restituzione dell'esito positivo) se esiste già una coppia in sospeso.

Un provider di servizi deve eseguire il maggior numero di controlli di coerenza che è pratico al momento. TSPI_providerInit viene chiamato per assicurarsi che sia pronto per l'esecuzione. Alcuni errori di coerenza o installazione, tuttavia, non possono essere rilevati finché l'operazione non viene tentata. L'errore LINEERR_NODRIVER può essere usato per segnalare tali errori non specifici al momento in cui vengono rilevati.

Non esiste alcuna funzione corrispondente direttamente a livello TAPI. A questo livello, più istanze di utilizzo diverse possono essere in sospeso, con un "handle applicazione" restituito per identificare l'istanza nelle operazioni successive. A livello di TSPI, l'architettura dell'interfaccia supporta solo un'istanza di utilizzo singola per ogni provider di servizi distinto.