funzione lineInitializeExA (tapi.h)

Articolo
11/20/2024

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 linea nell'API Telefonia.

Sintassi

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

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. L'applicazione o la DLL possono 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à multimediale).

lpfnCallback

Indirizzo di una funzione di callback richiamata per determinare lo stato e gli eventi nel dispositivo line, gli indirizzi o le 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 "handle evento" o "porta di completamento".

lpszFriendlyAppName

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

lpdwNumDevs

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

lpdwAPIVersion

Puntatore a una posizione DWORDridimensionata. 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 passerebbe in dwAPIHighVersion parametro 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, questo percorso viene compilato con la versione più elevata dell'API supportata da TAPI, consentendo così all'applicazione di rilevare e adattarsi a essere installato 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 possibili valori restituiti sono:

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

Osservazioni

Le applicazioni devono selezionare uno dei tre meccanismi in base ai quali TAPI notifica l'applicazione di eventi di telefonia: Finestra nascosta, Handle eventi o Porta di completamento.

Il meccanismo Hidden Window viene selezionato specificando LINEINITIALIZEEXOPTION_USEHIDDENWINDOW nella struttura dwOptions nella struttura LINEINITIALIZEEXPARAMS. In questo meccanismo (che è l'unico meccanismo disponibile per TAPI versione 1.applicazioni x), 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 contiene 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 GetMessage Windows ), Windows passa il contesto del processo a quello dell'applicazione e richiama WNDPROC in TAPI. TAPI recapita quindi il messaggio all'applicazione chiamando il lineCallbackProc, un puntatore a cui l'applicazione fornita come parametro nella chiamata a lineInitializeEx (o lineInitialize). Questo meccanismo richiede che l'applicazione disponga di una coda di messaggi (che non è consigliabile 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 distrutta da TAPI durante la funzione lineShutdown.

Il meccanismo di gestione eventi viene selezionato specificando LINEINITIALIZEEXOPTION_USEEVENT nella struttura 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, CloseHandlee così via) o risultati di 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 dell'evento viene chiuso e l'oggetto evento eliminato da TAPI durante la funzione lineShutdown. L'applicazione non è necessaria per attendere l'handle dell'evento creato; L'applicazione potrebbe invece scegliere di chiamare lineGetMessage e bloccarla in attesa di accodare un messaggio.

Il meccanismo Porta di completamento è 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 nell'applicazione specificata nel membro hCompletionPort in LINEINITIALIZEEXPARAMS, contrassegnata con la chiave di completamento specificata nell 'applicazione specificata 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 dispone dell' dwCompletionKey scritta nel 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 (consentendone 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 o 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 degli eventi da TAPI, ma potrebbe essere causato dal time slicing dei thread o dall'esecuzione di thread su 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, rigaInitializeEx richieste vengono rifiutate con questo errore finché l'ultima applicazione non arresta l'utilizzo dell'API (usando lineShutdown), in cui la nuova configurazione diventa effettiva e le applicazioni possono chiamare nuovamente 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 di riga compresi tra zero e 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 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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.