funzione phoneInitializeExW (tapi.h)

La funzione phoneInitializeEx inizializza l'uso di TAPI dell'applicazione per l'uso successivo dell'astrazione del telefono. Registra il meccanismo di notifica specificato dell'applicazione e restituisce il numero di dispositivi telefonici disponibili per l'applicazione. Un dispositivo telefonico è qualsiasi dispositivo che fornisce un'implementazione per le funzioni con prefisso telefonico nell'API Telefonia.

Sintassi

LONG phoneInitializeExW(
  LPHPHONEAPP               lphPhoneApp,
  HINSTANCE                 hInstance,
  PHONECALLBACK             lpfnCallback,
  LPCWSTR                   lpszFriendlyAppName,
  LPDWORD                   lpdwNumDevs,
  LPDWORD                   lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

Parametri

lphPhoneApp

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.

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 phoneCallbackFunc. 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 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 PHONESTATUS per indicare, in modo intuitivo, quale applicazione ha la proprietà del dispositivo telefonico. Se lpszFriendlyAppName è NULL, viene usato invece il nome file del modulo dell'applicazione , come restituito dalla funzione GetModuleFileName.

lpdwNumDevs

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

lpdwAPIVersion

Puntatore a un 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 phoneNegotiateAPIVersion). 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ù recente dell'API supportata da TAPI, consentendo così all'applicazione di rilevare e adattarsi a essere installata in un sistema con una versione precedente di TAPI.

lpPhoneInitializeExParams

Puntatore a una struttura di tipo PHONEINITIALIZEEXPARAMS 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:

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_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 Finestra nascosta viene selezionato specificando PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW nel membro dwOptions nella struttura PHONEINITIALIZEEXPARAMS . 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 phoneInitializeEx e sottoclassa la finestra in modo che tutti i messaggi inviati vengano 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 phoneCallbackFunc, un puntatore a cui l'applicazione fornita come parametro nella chiamata a phoneInitializeEx (o phoneInitialize, per le applicazioni TAPI versione 1.3 e 1.4). 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 phoneShutdown .
  • Il meccanismo Di gestione eventi viene selezionato specificando PHONEINITIALIZEEXOPTION_USEEVENT nel membro dwOptions nella struttura PHONEINITIALIZEEXPARAMS . In questo meccanismo TAPI crea un oggetto evento per conto dell'applicazione e restituisce un handle all'oggetto nel membro hEvent in PHONEINITIALIZEEXPARAMS. 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 phoneGetMessage 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 phoneShutdown . L'applicazione non è necessaria per attendere l'handle dell'evento creato; l'applicazione potrebbe invece scegliere di chiamare phoneGetMessage e bloccarlo in attesa di accodare un messaggio.
  • Il meccanismo Porta di completamento è selezionato specificando PHONEINITIALIZEEXOPTION_USECOMPLETION PORT nel membro dwOptions nella struttura PHONEINITIALIZEEXPARAMS . In questo meccanismo, ogni volta che un evento di telefonia deve essere inviato all'applicazione, TAPI lo invia all'applicazione usando PostQueuedCompletionStatus alla porta di completamento specificata dall'applicazione nel membro hCompletionPort in PHONEINITIALIZEEXPARAMS, contrassegnata con la chiave di completamento specificata dall'applicazione nel membro dwCompletionKey in PHONEINITIALIZEEXPARAMS. L'applicazione deve aver creato in precedenza la porta di completamento usando CreateIoCompletionPort. Le applicazioni recuperano 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 PHONEMESSAGE restituita alla posizione a cui punta lpOverlapped. Dopo che l'applicazione ha elaborato l'evento, l'applicazione deve chiamare LocalFree per rilasciare la memoria usata per contenere la struttura PHONEMESSAGE . 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 phoneShutdown.
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 PHONEERR_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 phoneInitializeEx vengono rifiutate con questo errore fino a quando l'ultima applicazione non arresta l'utilizzo dell'API (tramite phoneShutdown). In quel momento, la nuova configurazione diventa effettiva e le applicazioni sono ancora una volta autorizzate a chiamare phoneInitializeEx.

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

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

Nota

L'intestazione tapi.h definisce phoneInitializeEx 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.

Requisiti

   
Piattaforma di destinazione Windows
Intestazione tapi.h
Libreria Tapi32.lib
DLL Tapi32.dll

Vedi anche

PHONEINITIALIZEEXPARAMS

PHONEMESSAGE

PHONESTATUS

Funzioni supplementari del servizio telefonico

Panoramica dei riferimenti a TAPI 2.2

phoneCallbackFunc

phoneGetDevCaps

phoneGetMessage

phoneNegotiateAPIVersion

phoneShutdown