funzione phoneInitialize (tapi.h)

Articolo
08/26/2023

La funzione phoneInitialize è obsoleta. Continua a essere esportato da Tapi.dll e Tapi32.dll per garantire la compatibilità con le versioni precedenti con le applicazioni che usano le versioni TAPI 1.3 e 1.4.

Le applicazioni che usano TAPI versione 2.0 o successiva devono usare phoneInitializeEx .

Per TAPI versioni 1.4 e precedenti: La funzione phoneInitialize inizializza l'uso di TAPI dell'applicazione per l'uso successivo delle funzioni telefoniche nell'API di telefonia. Registra il meccanismo di notifica specificato dell'applicazione e restituisce il numero di dispositivi telefonici disponibili per l'applicazione.

Sintassi

LONG phoneInitialize(
  LPHPHONEAPP   lphPhoneApp,
  HINSTANCE     hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR        lpszAppName,
  LPDWORD       lpdwNumDevs
);

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.

lpfnCallback

Indirizzo di una funzione di callback richiamata per determinare lo stato e gli eventi nel dispositivo telefonico.

lpszAppName

Puntatore a una stringa con terminazione Null contenente caratteri visualizzabili. Se questo parametro non è NULL, contiene un nome fornito dall'applicazione dell'applicazione. Questo nome viene fornito nella struttura PHONESTATUS per indicare, in modo intuitivo, quale applicazione è il proprietario corrente del dispositivo telefonico. Queste informazioni possono essere utili per la registrazione e la creazione di report sullo stato. Se lpszAppName è NULL, viene usato invece il nome file dell'applicazione.

lpdwNumDevs

Puntatore a DWORD. Questa posizione viene caricata con il numero di dispositivi telefonici disponibili per l'applicazione.

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_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_REINIT, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODEVICE, PHONEERR_NODRIVER, PHONEERR_INVALPARAM

Commenti

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 superare ciò che viene specificato dal subset di telefonia assistita senza prima eseguire query sulle funzionalità del dispositivo con la funzione phoneGetDevCaps .

Le applicazioni non devono richiamare phoneInitialize senza aprire successivamente un telefono (almeno per il monitoraggio). Se l'applicazione non esegue il monitoraggio e non usa alcun dispositivo, deve chiamare phoneShutdown in modo che le risorse di memoria allocate da TAPI possano essere rilasciate se non necessarie e TAPI stesso può essere scaricato dalla memoria mentre non è necessario.

Un altro motivo per eseguire un phoneShutdown è che se un utente modifica la configurazione del dispositivo (aggiunge o rimuove una linea o un telefono), non è possibile che TAPI comunicherà a un'applicazione che dispone di un handle di linea o telefono aperto al momento. Dopo aver eseguito una riconfigurazione, causando l'invio di un messaggio di PHONESTATE_REINIT, nessuna applicazione può aprire un dispositivo finché tutte le applicazioni non hanno eseguito un phoneShutdown.

Se un provider di servizi non viene inizializzato correttamente, la funzione phoneInitialize ha esito negativo e restituisce l'errore indicato dal provider di servizi. Se viene restituito il valore di errore PHONEERR_INVALPARAM, il parametro hInstance specificato non è valido.