Função phoneOpen (tapi.h)

Artigo
03/02/2024

A função phoneOpen abre o dispositivo de telefone especificado. Um dispositivo de telefone pode ser aberto usando privilégio de proprietário ou privilégio de monitor. Um aplicativo que abre o telefone com privilégio de proprietário pode controlar as lâmpadas, a tela, o toque e os hookswitch ou hookswitches do telefone. Um aplicativo que abre o dispositivo de telefone com privilégio de monitor é notificado apenas sobre eventos que ocorrem no telefone, como alterações hookswitch ou pressionamentos de botão.

A propriedade de um dispositivo de telefone é exclusiva. Em outras palavras, apenas um aplicativo pode ter um dispositivo de telefone aberto com privilégio de proprietário por vez. No entanto, o dispositivo de telefone pode ser aberto várias vezes com privilégio de monitor.

Sintaxe

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

Parâmetros

hPhoneApp

Manipule para o registro do aplicativo com TAPI.

dwDeviceID

Identificador do dispositivo de telefone a ser aberto.

lphPhone

Ponteiro para um identificador HPHONE que identifica o dispositivo de telefone aberto. Use esse identificador para identificar o dispositivo ao invocar outras funções de controle de telefone.

dwAPIVersion

Número de versão da API sob o qual o aplicativo e a API de Telefonia concordaram em operar. Esse número é obtido de phoneNegotiateAPIVersion.

dwExtVersion

Número de versão da extensão sob o qual o aplicativo e o provedor de serviços concordam em operar. Esse número será zero se o aplicativo não usar extensões. Esse número é obtido de phoneNegotiateExtVersion.

dwCallbackInstance

Dados de instância de usuário passados de volta para o aplicativo com cada mensagem. Esse parâmetro não é interpretado pela API de Telefonia.

dwPrivilege

Privilégio solicitado. Esse parâmetro usa uma e apenas uma das constantes PHONEPRIVILEGE_.

Retornar valor

Retornará zero se a solicitação for bem-sucedida ou um número de erro negativo se ocorrer um erro. Os valores retornados possíveis são:

PHONEERR_ALLOCATED, PHONEERR_NODRIVER, PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALAPPHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_INVALPRIVILEGE, PHONEERR_REINIT, PHONEERR_INUSE, PHONEERR_NODEVICE, PHONEERR_INIFILECORRUPT.

Comentários

Ao abrir um dispositivo de telefone com privilégios de monitor, o aplicativo recebe mensagens quando ocorrem eventos que alteram o status do telefone. As mensagens enviadas ao aplicativo incluem PHONE_BUTTON e PHONE_STATE. Este último fornece uma indicação do item de status do telefone que foi alterado.

Ao abrir um telefone com privilégio de proprietário, o dispositivo de telefone pode ser manipulado de maneiras que afetam o estado do dispositivo de telefone. Um aplicativo só deve abrir um telefone usando o privilégio de proprietário se quiser ativamente manipular o dispositivo de telefone e deve fechar o dispositivo de telefone quando terminar para permitir que outros aplicativos controlem o telefone.

Quando um aplicativo abre um dispositivo de telefone, ele deve especificar a versão da API negociada e, se quiser usar as extensões do telefone, a versão de extensão específica do dispositivo do telefone. Esse número de versão deveria ter sido obtido com as funções phoneNegotiateAPIVersion e phoneNegotiateExtVersion . A numeração de versão permite a combinação e a correspondência de diferentes versões de aplicativo com diferentes versões de API e versões do provedor de serviços.