Funzione lineInitializeExA (tapi.h)

Articolo
08/26/2023

La funzione lineInitializeEx inizializza l'uso di TAPI dell'applicazione per l'uso successivo dell'astrazione della riga. 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 con prefisso riga nell'API di telefonia.

Sintassi

LONG lineInitializeExA(
  LPHLINEAPP               lphLineApp,
  HINSTANCE                hInstance,
  LINECALLBACK             lpfnCallback,
  LPCSTR                   lpszFriendlyAppName,
  LPDWORD                  lpdwNumDevs,
  LPDWORD                  lpdwAPIVersion,
  LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);

Parametri

lphLineApp

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

hInstance

Handle dell'istanza dell'applicazione client o della DLL. L'applicazione o la DLL può passare NULL per questo parametro, nel qual caso TAPI usa l'handle del modulo dell'eseguibile radice del processo (ai fini dell'identificazione delle destinazioni di handoff di chiamata e priorità della modalità supporto).

lpfnCallback

Indirizzo di una funzione di callback richiamata per determinare lo stato e gli eventi nel dispositivo line, negli indirizzi o nelle chiamate, quando l'applicazione usa il metodo di notifica degli eventi "finestra nascosta". Per altre informazioni, vedere lineCallbackFunc. Questo parametro viene ignorato e deve essere impostato su NULL quando l'applicazione sceglie di usare i meccanismi di notifica degli eventi "event handle" o "porta di completamento".

lpszFriendlyAppName

Puntatore a una stringa di testo con terminazione Null che contiene 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 intuitivo, quale applicazione ha avuto origine o ha originariamente accettato o risposto alla chiamata. Queste informazioni possono essere utili per scopi di registrazione delle chiamate. Se lpszFriendlyAppName è NULL, viene usato invece il nome del file del modulo dell'applicazione , come restituito dalla funzione GetModuleFileName.

lpdwNumDevs

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

lpdwAPIVersion

Puntatore a una posizione con dimensioni DWORD. L'applicazione deve inizializzare questo DWORD, prima di chiamare questa funzione, alla versione più alta dell'API progettata per supportare (ad esempio, lo stesso valore che passerebbe nel parametro dwAPIHighVersion di lineNegotiateAPIVersion). I valori artificialmente alti non devono essere utilizzati; il valore deve essere impostato in modo accurato. TAPI converte eventuali messaggi o strutture più recenti in valori o formati supportati dalla versione dell'applicazione. Al termine di questa richiesta, questa posizione viene riempita con la versione più elevata dell'API supportata da TAPI, consentendo così all'applicazione di rilevare e adattarsi a essere installata in un sistema con una versione diversa di TAPI.

lpLineInitializeExParams

Puntatore a una struttura di tipo LINEINITIALIZEEXPARAMS contenente parametri aggiuntivi usati per stabilire l'associazione tra l'applicazione e TAPI (in particolare, il meccanismo di notifica degli eventi selezionato dell'applicazione e i parametri associati).

Valore restituito

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

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Commenti

Le applicazioni devono selezionare uno dei tre meccanismi in base ai quali TAPI invia una notifica all'applicazione di eventi di telefonia: finestra nascosta, handle eventi o porta di completamento.

Il meccanismo Hidden Window viene selezionato specificando LINEINITIALIZEEXOPTION_USEHIDDENWINDOW nel membro dwOptions nella struttura LINEINITIALIZEEXPARAMS . In questo meccanismo (che è l'unico meccanismo disponibile per TAPI versione 1.X applications), TAPI crea una finestra nel contesto dell'applicazione durante la funzione lineInitializeEx o lineInitialize (per le applicazioni TAPI versione 1.3 e 1.4) e sottoclassa la finestra in modo che tutti i messaggi inviati siano gestiti da un WNDPROC in TAPI stesso. Quando TAPI ha un messaggio da recapitare all'applicazione, TAPI invia un messaggio alla finestra nascosta. Quando il messaggio viene ricevuto (che può verificarsi solo quando l'applicazione chiama la funzione Windows GetMessage ), Windows passa il contesto del processo a quello dell'applicazione e richiama WNDPROC in TAPI. TAPI recapita quindi il messaggio all'applicazione chiamando lineCallbackProc, un puntatore a cui l'applicazione fornita come parametro nella chiamata a lineInitializeEx (o lineInitialize). Questo meccanismo richiede all'applicazione di disporre di una coda di messaggi (che non è auspicabile per i processi del servizio) e di gestire regolarmente tale coda per evitare di ritardare l'elaborazione degli eventi di telefonia. La finestra nascosta viene eliminata definitivamente da TAPI durante la funzione lineShutdown .

Il meccanismo Di gestione eventi viene selezionato specificando LINEINITIALIZEEXOPTION_USEEVENT nel membro dwOptions nella struttura LINEINITIALIZEEXPARAMS . In questo meccanismo, TAPI crea un oggetto evento per conto dell'applicazione e restituisce un handle all'oggetto nel membro hEvent in LINEINITIALIZEEXPARAMS. L'applicazione non deve modificare questo evento in alcun modo (ad esempio, non deve chiamare SetEvent, ResetEvent, CloseHandle e così via) o risultati del comportamento non definiti; l'applicazione può attendere solo questo evento usando funzioni come WaitForSingleObject o MsgWaitForMultipleObjects. TAPI segnala questo evento ogni volta che una notifica degli eventi di telefonia è in sospeso per l'applicazione; l'applicazione deve chiamare lineGetMessage per recuperare il contenuto del messaggio. L'evento viene reimpostato da TAPI quando non sono presenti eventi in sospeso. L'handle di evento viene chiuso e l'oggetto evento eliminato definitivamente da TAPI durante la funzione lineShutdown . L'applicazione non è necessaria per attendere l'handle dell'evento creato; l'applicazione può scegliere di chiamare lineGetMessage e bloccarla in attesa di accodamento di un messaggio.

Il meccanismo Porta di completamento viene selezionato specificando LINEINITIALIZEEXOPTION_USECOMPLETION PORT nel membro dwOptions nella struttura LINEINITIALIZEEXPARAMS . In questo meccanismo, ogni volta che un evento di telefonia deve essere inviato all'applicazione, TAPI lo invia usando PostQueuedCompletionStatus alla porta di completamento specificata dall'applicazione nel membro hCompletionPort in LINEINITIALIZEEXPARAMS, contrassegnata con la chiave di completamento specificata dall'applicazione nel membro dwCompletionKey in LINEINITIALIZEEXPARAMS. L'applicazione deve aver creato in precedenza la porta di completamento usando CreateIoCompletionPort. L'applicazione recupera gli eventi usando GetQueuedCompletionStatus. Al ritorno da GetQueuedCompletionStatus, l'applicazione ha il valore dwCompletionKey specificato scritto in DWORD a cui punta il parametro lpCompletionKey e un puntatore a una struttura LINEMESSAGE restituita alla posizione a cui punta lpOverlapped. Dopo che l'applicazione ha elaborato l'evento, è responsabilità dell'applicazione chiamare LocalFree per rilasciare la memoria usata per contenere la struttura LINEMESSAGE . Poiché l'applicazione ha creato la porta di completamento (consentendo così la condivisione per altri scopi), l'applicazione deve chiuderla; l'applicazione non deve chiudere la porta di completamento fino a quando non viene chiamato lineShutdown.

Quando un'applicazione multithreading usa il meccanismo di gestione eventi e più thread sono in attesa sull'handle oppure il meccanismo di notifica della porta di completamento e più thread sono in attesa sulla porta, è possibile che gli eventi di telefonia vengano elaborati fuori sequenza. Ciò non è dovuto alla sequenza di recapito di eventi da TAPI, ma potrebbe essere causato dal time slicing dei thread o dall'esecuzione di thread in processori separati.

Se viene restituito LINEERR_REINIT e la reinizializzazione TAPI è stata richiesta, ad esempio in seguito all'aggiunta o alla rimozione di un provider di servizi di telefonia, le richieste lineInitializeEx vengono rifiutate con questo errore fino a quando l'ultima applicazione non arresta l'utilizzo dell'API (tramite lineShutdown), al momento in cui la nuova configurazione diventa effettiva e le applicazioni sono nuovamente autorizzate a chiamare lineInitializeEx.

Se viene restituito il valore di errore LINEERR_INVALPARAM, il parametro hInstance specificato non è valido.

L'applicazione può fare riferimento a singoli dispositivi line usando identificatori di dispositivo della riga che vanno da zero a dwNumDevs meno uno. Un'applicazione non deve presupporre che questi dispositivi line siano in grado di qualsiasi funzione TAPI specifica senza prima eseguire query sulle funzionalità del dispositivo in base a lineGetDevCaps e lineGetAddressCaps.

Nota

L'intestazione tapi.h definisce lineInitializeEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.