funzione phoneOpen (tapi.h)

Articolo
03/08/2023

La funzione phoneOpen apre il dispositivo telefonico specificato. Un dispositivo telefonico può essere aperto usando privilegi di proprietario o privilegi di monitoraggio. Un'applicazione che apre il telefono con privilegi di proprietario può controllare le lampade del telefono, la visualizzazione, il ringer e hookswitch o hookswitches. Un'applicazione che apre il dispositivo telefonico con privilegi di monitoraggio riceve una notifica solo sugli eventi che si verificano nel telefono, ad esempio le modifiche di hookswitch o la pressione del pulsante.

La proprietà di un dispositivo telefonico è esclusiva. In altre parole, solo un'applicazione può avere un dispositivo telefonico aperto con privilegi di proprietario alla volta. Il dispositivo telefonico può tuttavia essere aperto più volte con privilegi di monitoraggio.

Sintassi

LONG phoneOpen(
  HPHONEAPP hPhoneApp,
  DWORD     dwDeviceID,
  LPHPHONE  lphPhone,
  DWORD     dwAPIVersion,
  DWORD     dwExtVersion,
  DWORD_PTR dwCallbackInstance,
  DWORD     dwPrivilege
);

Parametri

hPhoneApp

Gestire la registrazione dell'applicazione con TAPI.

dwDeviceID

Identificatore del dispositivo telefonico da aprire.

lphPhone

Puntatore a un handle HPHONE che identifica il dispositivo telefonico aperto. Usare questo handle per identificare il dispositivo quando si richiamano altre funzioni di controllo telefonico.

dwAPIVersion

Numero di versione dell'API in cui l'API di telefonia e l'applicazione hanno accettato di funzionare. Questo numero viene ottenuto dal telefonoNegotiateAPIVersion.

dwExtVersion

Numero di versione dell'estensione in cui l'applicazione e il provider di servizi accettano di funzionare. Questo numero è zero se l'applicazione non usa estensioni. Questo numero viene ottenuto dal telefonoNegotiateExtVersion.

dwCallbackInstance

I dati dell'istanza utente vengono passati all'applicazione con ogni messaggio. Questo parametro non viene interpretato dall'API Telefonia.

dwPrivilege

Privilegi richiesti. Questo parametro usa uno e solo uno dei costanti PHONEPRIVILEGE_.

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_ALLOCATED, PHONEERR_NODRIVER, PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALAPPHANDLE, PHONEERR_RESOURCEUNAVAIL PHONEERR_INVALPRIVILEGE, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_UNINITIALIZED, PHONEERR_REINIT, PHONEERR_REINIT, PHONEERR_INUSE, PHONEERR_NODEVICE, PHONEERR_INIFILECORRUPT.

Commenti

Quando si apre un dispositivo telefonico con privilegi di monitoraggio, l'applicazione invia messaggi quando si verificano eventi che modificano lo stato del telefono. I messaggi inviati all'applicazione includono PHONE_BUTTON e PHONE_STATE. Quest'ultimo fornisce un'indicazione dell'elemento di stato del telefono che è cambiato.

Quando si apre un telefono con privilegi di proprietario, il dispositivo telefonico può essere modificato in modi che influiscono sullo stato del dispositivo telefonico. Un'applicazione deve aprire un telefono solo usando privilegi di proprietario se vuole modificare attivamente il dispositivo telefonico e dovrebbe chiudere il dispositivo telefonico al termine per consentire ad altre applicazioni di controllare il telefono.

Quando un'applicazione apre un dispositivo telefonico, deve specificare la versione dell'API negoziata e, se vuole usare le estensioni del telefono, la versione dell'estensione specifica del dispositivo del telefono. Questo numero di versione dovrebbe essere stato ottenuto con le funzioni phoneNegotiateAPIVersion e phoneNegotiateExtVersion . Il numero di versioni consente la combinazione e la corrispondenza di diverse versioni dell'applicazione con versioni api diverse e versioni del provider di servizi.