funzione phoneInitializeExA (tapi.h)

Articolo
03/08/2023

La funzione phoneInitializeEx inizializza l'uso dell'applicazione TAPI 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 phoneInitializeExA(
  LPHPHONEAPP               lphPhoneApp,
  HINSTANCE                 hInstance,
  PHONECALLBACK             lpfnCallback,
  LPCSTR                    lpszFriendlyAppName,
  LPDWORD                   lpdwNumDevs,
  LPDWORD                   lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

Parametri

lphPhoneApp

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.

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 "finestra nascosta" della notifica degli eventi (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 "gestione eventi" 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 descrittivo, quale applicazione ha la proprietà del dispositivo telefonico. Se lpszFriendlyAppName è NULL, viene invece usato il nome del modulo dell'applicazione, come restituito dalla funzione GetModuleFileName.

lpdwNumDevs

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

lpdwAPIVersion

Puntatore a una DWORD. L'applicazione deve inizializzare questa DWORD, prima di chiamare questa funzione, alla versione più alta dell'API progettata per supportare (ad esempio, lo stesso valore passerebbe al parametro dwAPIHighVersion del phoneNegotiateAPIVersion). I valori ad alto livello artificiale non devono essere usati; il valore deve essere impostato in modo accurato. TAPI converte i messaggi o le strutture più recenti in valori o formati supportati dalla versione dell'applicazione. Al termine di questa richiesta, questa posizione viene riempita con la versione API più elevata supportata da TAPI, consentendo 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 eventi selezionato dell'applicazione e i parametri associati).

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:

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 al quale TAPI notifica l'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 ,ovvero l'unico meccanismo disponibile per TAPI versione 1.x applications), TAPI crea una finestra nel contesto dell'applicazione durante la funzione phoneInitializeEx e sottoclasse la finestra in modo che tutti i messaggi pubblicati 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 il 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 che l'applicazione disponga di una coda di messaggi (che non è auspicabile per i processi del servizio) e di eseguire regolarmente tale coda per evitare il ritardo dell'elaborazione degli eventi di telefonia. La finestra nascosta viene distrutta 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 in questo evento usando funzioni come WaitForSingleObject o MsgWaitForMultipleObjects. TAPI segnala questo evento ogni volta che una notifica di evento 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 in sospeso eventi. L'handle eventi viene chiuso e l'oggetto evento distrutto da TAPI durante la funzione phoneShutdown . L'applicazione non è necessaria per attendere l'handle di eventi creato; l'applicazione potrebbe scegliere invece di chiamare phoneGetMessage e di bloccarlo in attesa di una coda di un messaggio.
Il meccanismo Porta di completamento viene 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 specificata nel membro hCompletionPort in PHONEINITIALIZEEXPARAMS, contrassegnata con la chiave di completamento specificata nell'applicazione specificata 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 la dwCompletionKey specificata scritta nel parametro DWORD a cui fa riferimento il parametro lpCompletionKey e un puntatore a una struttura PHONEMESSAGE restituita alla posizione a cui punta da lpOverlapped. Dopo aver 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 la condivisione per altri scopi), l'applicazione deve chiuderla; l'applicazione non deve chiudere la porta di completamento fino a quando dopo aver chiamato phoneShutdown.

Quando un'applicazione multithreaded usa il meccanismo di gestione eventi e più thread sono in attesa sull'handle o sul 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. Questo non è dovuto alla sequenza di recapito di eventi da TAPI, ma sarebbe causato dal tempo di slicing di thread o l'esecuzione di thread in processori separati.

Se PHONEERR_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 phoneInitializeEx vengono rifiutate con questo errore finché l'ultima applicazione non arresta l'utilizzo dell'API (usando phoneShutdown). In quel momento, la nuova configurazione diventa effettiva e le applicazioni sono ancora una volta autorizzate a chiamare telefonoInitializeEx.

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 telefonici che vanno da zero a dwNumDevs meno uno. Un'applicazione non presuppone che questi dispositivi telefonici siano in grado di qualsiasi funzione TAPI particolare 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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.