funzione lineInitialize (tapi.h)

Articolo
08/26/2023

La funzione lineInitialize è obsoleta . Continua a essere esportato da Tapi.dll e Tapi32.dll per la compatibilità con le versioni precedenti con applicazioni che usano le versioni API 1.3 e 1.4.

Le applicazioni che usano l'API versione 2.0 o successiva devono usare invece lineInitializeEx .

Per TAPI versioni 1.4 e versioni precedenti: La funzione lineInitialize inizializza l'uso dell'applicazione di Tapi.dll per l'uso successivo dell'astrazione della riga. La funzione registra il meccanismo di notifica specificato dell'applicazione e restituisce il numero di dispositivi line disponibili per l'applicazione. Un dispositivo linea è qualsiasi dispositivo che fornisce un'implementazione per le funzioni prefissi della riga in TAPI.

Sintassi

LONG lineInitialize(
  LPHLINEAPP   lphLineApp,
  HINSTANCE    hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR       lpszAppName,
  LPDWORD      lpdwNumDevs
);

Parametri

lphLineApp

Puntatore a una posizione riempita con l'handle di utilizzo dell'applicazione per TAPI.

hInstance

Handle dell'istanza dell'applicazione client o della DLL.

lpfnCallback

Indirizzo di una funzione di callback richiamata per determinare lo stato e gli eventi nel dispositivo line, negli indirizzi o nelle chiamate. Per altre informazioni, vedere lineCallbackFunc.

lpszAppName

Puntatore a una stringa di testo con terminazione null contenente solo caratteri visualizzabili. Se questo parametro non è NULL, contiene un nome fornito dall'applicazione per l'applicazione. Questo nome viene fornito nella struttura LINECALLINFO per indicare, in modo descrittivo, quale applicazione ha avuto origine o originariamente accettato o risposto alla chiamata. Queste informazioni possono essere utili per scopi di registrazione delle chiamate. Se lpszAppName è NULL, viene invece usato il nome del file dell'applicazione.

lpdwNumDevs

Puntatore a una posizione di dimensioni DWORD. Al termine di questa richiesta, questa posizione viene riempita con il numero di dispositivi line disponibili per l'applicazione.

Valore restituito

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

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NODRIVER, LINEERR_NODEVICE, LINEERR_NOMEM, LINEERR_NOMULTIPLEINSTANCE.

Commenti

Se LINEERR_REINIT viene restituito e la reinizializzazione TAPI è stata richiesta (ad esempio come risultato dell'aggiunta o della rimozione di un provider di servizi di telefonia), le richieste lineInitialize vengono rifiutate con questo errore finché l'ultima applicazione non arresta l'utilizzo dell'API (usando lineShutdown). In quel momento, la nuova configurazione diventa effettiva e le applicazioni possono ancora una volta chiamare lineInitialize. Se viene restituito il valore di errore LINEERR_INVALPARAM, il parametro hInstance specificato non è valido.

L'applicazione può fare riferimento a singoli dispositivi di riga usando identificatori di dispositivo linea che vanno da zero a dwNumDevs meno uno. Un'applicazione non deve presupporre che questi dispositivi di riga siano in grado di superare ciò che è specificato dal subset di telefonia di base senza prima eseguire query sulle funzionalità del dispositivo usando lineGetDevCaps e lineGetAddressCaps.

Le applicazioni non devono richiamare lineInitialize senza successivamente aprire una riga (almeno per il monitoraggio). Se l'applicazione non esegue il monitoraggio e non usa alcun dispositivo, deve chiamare lineShutdown in modo che le risorse di memoria allocate da Tapi.dll possano essere rilasciate se non necessarie e Tapi.dll stesso può essere scaricato dalla memoria mentre non è necessario.

Un altro motivo per l'esecuzione di una lineaShutdown è che se un utente modifica la configurazione del dispositivo (aggiunge o rimuove una riga o un telefono), non è possibile che TAPI comunicherà a un'applicazione che ha una linea o un handle di telefono aperto al momento. Dopo aver eseguito una riconfigurazione, causando l'invio di un messaggio LINEDEVSTATE_REINIT, nessuna applicazione può aprire un dispositivo fino a quando tutte le applicazioni non hanno eseguito una rigaShutdown. Se un provider di servizi non riesce a inizializzare correttamente, questa funzione non riesce e restituisce l'errore indicato dal provider di servizi.

In tutte le piattaforme TAPI, lineInitialize equivale a lineInitializeEx usando l'opzione LINEINITIALIZEEXOPTION_USEHIDDENWINDOW.