funzione phoneInitializeExA (tapi.h)

Articolo
03/08/2023

La funzione phoneInitializeEx inizializza l'uso dell'applicazione di 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 telefono 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 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 "handle evento" o "porta di completamento".

lpszFriendlyAppName

Puntatore a un nullstringa con terminazione contenente 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 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 questa DWORD, prima di chiamare questa funzione, alla versione più alta dell'API progettata per supportare (ad esempio, lo stesso valore 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 compilata 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 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 possibili valori restituiti sono:

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM PHONEERR_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 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 applicazioni), TAPI crea una finestra nel contesto dell'applicazione durante la funzione phoneInitializeEx 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 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 è 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 phoneShutdown.
Il meccanismo di handle eventi viene selezionato specificando PHONEINITIALIZEEXOPTION_USEEVENT nella struttura 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, 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 phoneGetMessage 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 distrutto 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 un messaggio da accodare.
Il meccanismo di 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 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 dispone dell' dwCompletionKey specificata scritta nell' 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 (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 phoneShutdown.

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 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 finché l'ultima applicazione non arresta l'utilizzo dell'API (usando phoneShutdown). In quel momento, la nuova configurazione diventa effettiva e le applicazioni sono di nuovo 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 compresi tra zero e 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 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 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.