Função lineOpen (tapi.h)

Artigo
03/05/2024

A função lineOpen abre o dispositivo de linha especificado por seu identificador de dispositivo e retorna um identificador de linha para o dispositivo de linha aberto correspondente. Esse identificador de linha é usado em operações subsequentes no dispositivo de linha.

Sintaxe

LONG lineOpen(
  HLINEAPP               hLineApp,
  DWORD                  dwDeviceID,
  LPHLINE                lphLine,
  DWORD                  dwAPIVersion,
  DWORD                  dwExtVersion,
  DWORD_PTR              dwCallbackInstance,
  DWORD                  dwPrivileges,
  DWORD                  dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

Parâmetros

hLineApp

Manipule para o registro do aplicativo com TAPI.

dwDeviceID

Identifica o dispositivo de linha a ser aberto. Ele pode ser um identificador de dispositivo válido ou o valor .

Valor	Significado
LINEMAPPER	Esse valor é usado para abrir um dispositivo de linha no sistema que dá suporte às propriedades especificadas em lpCallParams. O aplicativo pode usar lineGetID para determinar o identificador do dispositivo de linha que foi aberto.

lphLine

Ponteiro para um identificador HLINE que é carregado com o identificador que representa o dispositivo de linha aberto. Use esse identificador para identificar o dispositivo ao invocar outras funções no dispositivo de linha aberta.

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 com lineNegotiateAPIVersion.

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 com lineNegotiateExtVersion.

dwCallbackInstance

Dados de instância de usuário passados de volta para o aplicativo com cada mensagem associada a essa linha ou com endereços ou chamadas nessa linha. Esse parâmetro não é interpretado pela API de Telefonia.

dwPrivileges

Privilégio que o aplicativo deseja quando notificado de uma chamada Esse parâmetro contém uma ou mais das constantes LINECALLPRIVILEGE_. Para aplicativos que usam TAPI versão 2.0 ou posterior, os valores para esse parâmetro também podem ser combinados com uma ou mais das constantes LINEOPENOPTION_.

Se a opção LINEOPENOPTION_SINGLEADDRESS for especificada, o aplicativo estará interessado apenas em novas chamadas que aparecem no endereço especificado pelo membro dwAddressID na estrutura LINECALLPARAMS apontada pelo parâmetro lpCallParams (que deve ser especificado).

Se LINEOPENOPTION_SINGLEADDRESS for especificado, mas lpCallParams for inválido ou o dwAddressID incluído não existir na linha, a abertura falhará com LINERR_INVALADDRESSID.

Além de definir o membro dwAddressID da estrutura LINECALLPARAMS para o endereço desejado, o aplicativo também deve definir dwAddressMode em LINECALLPARAMS como LINEADDRESSMODE_ADDRESSID.

A opção LINEOPENOPTION_SINGLEADDRESS afeta apenas a atribuição do TAPI de propriedade inicial de chamadas criadas pelo provedor de serviços usando uma mensagem LINE_NEWCALL . Um aplicativo que abre a linha com LINECALLPRIVILEGE_MONITOR continua recebendo identificadores de monitoramento para todas as chamadas criadas na linha. Além disso, o aplicativo não é impedido de fazer chamadas ou executar outras operações que afetam outros endereços na linha aberta.

Quando a opção LINEOPENOPTION_PROXY é especificada (somente TAPI 2.0 ou superior), o aplicativo também deve indicar quais solicitações de proxy específicas ele está preparado para lidar. Ele faz isso passando, no parâmetro lpCallParams , um ponteiro para uma estrutura LINECALLPARAMS na qual os membros dwDevSpecificSize e dwDevSpecificOffset foram definidos para delimitar uma matriz de DWORDs. Cada elemento dessa matriz deve conter uma das constantes LINEPROXYREQUEST_. Por exemplo, um aplicativo de manipulador de proxy que dá suporte a todas as cinco funções relacionadas ao Agent passaria uma matriz de cinco DWORDs(dwDevSpecificSize seria 20 decimal) contendo os cinco valores de LINEPROXYREQUEST_ definidos.

O aplicativo de manipulador de solicitação de proxy pode ser executado em qualquer computador que tenha autorização para controlar o dispositivo de linha. No entanto, as solicitações são sempre roteados por meio do servidor no qual o provedor de serviços está executando que realmente controla o dispositivo de linha. Portanto, será mais eficiente se o aplicativo que está tratando solicitações de proxy (como o controle do agente ACD) for executado diretamente no servidor junto com o provedor de serviços.

Tentativas subsequentes, pelo mesmo aplicativo ou outros aplicativos, de abrir o dispositivo de linha e registrar-se para lidar com as mesmas solicitações de proxy que um aplicativo que já está registrado falham com LINEERR_NOTREGISTERED.

Para interromper o tratamento de solicitações na linha, o aplicativo simplesmente chama lineClose.

Outras combinações de sinalizador retornam o erro LINEERR_INVALPRIVSELECT.

dwMediaModes

O tipo de mídia ou modos de interesse para o aplicativo. Esse parâmetro é usado para registrar o aplicativo como um destino potencial para chamada de entrada e entrega de chamada para o tipo de mídia especificado. Esse parâmetro só será significativo se o bit LINECALLPRIVILEGE_OWNER em dwPrivileges estiver definido (e ignorado de outra forma). Esse parâmetro usa uma ou mais das constantes LINEMEDIAMODE_.

lpCallParams

Ponteiro para uma estrutura do tipo LINECALLPARAMS. Esse ponteiro só será usado se LINEMAPPER ou LINEOPENOPTION_PROXY for usado; caso contrário , lpCallParams será ignorado. Ele descreve o parâmetro de chamada que o dispositivo de linha deve ser capaz de fornecer.

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:

LINEERR_ALLOCATED, LINEERR_LINEMAPPERFAILED, LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALPRIVSELECT, LINEERR_REINIT, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

Comentários

Se LINEERR_ALLOCATED for retornado, a linha não poderá ser aberta devido a uma condição "persistente", como a de uma porta serial sendo aberta exclusivamente por outro processo. Se LINEERR_RESOURCEUNAVAIL for retornado, a linha não poderá ser aberta devido a um excesso de compromisso de recursos dinâmicos, como em ciclos de processador DSP ou memória. Esse excesso de compromisso pode ser transitório, causado pelo monitoramento de tipos de mídia ou tons, e as alterações nessas atividades por outros aplicativos podem tornar possível reabrir a linha em um curto período de tempo. Se LINEERR_REINIT for retornado e a reinicialização do TAPI tiver sido solicitada (por exemplo, como resultado da adição ou remoção de um provedor de serviços de telefonia), as solicitações lineOpen serão rejeitadas com esse erro até que o último aplicativo desligue o uso da API (usando lineShutdown); nesse momento, a nova configuração entra em vigor e os aplicativos têm mais uma vez permissão para chamar lineInitializeEx.

Abrir uma linha sempre dá direito ao aplicativo de fazer chamadas em qualquer endereço disponível na linha. A capacidade do aplicativo de lidar com chamadas de entrada ou ser o destino de entregas de chamada na linha é determinada pelo parâmetro dwMediaModes . A função lineOpen registra o aplicativo como tendo interesse em monitorar chamadas ou receber a propriedade de chamadas que são dos tipos de mídia especificados. Se o aplicativo quiser apenas monitorar chamadas, ele poderá especificar LINECALLPRIVILEGE_MONITOR. Se o aplicativo quiser apenas fazer chamadas de saída, ele poderá especificar LINECALLPRIVILEGE_NONE. Se o aplicativo estiver disposto a controlar chamadas não classificadas (chamadas de tipo de mídia desconhecido), ele poderá especificar LINECALLPRIVILEGE_OWNER e LINEMEDIAMODE_UNKNOWN. Caso contrário, o aplicativo deve especificar o tipo de mídia que está interessado em lidar. O aplicativo pode chamar a função lineSetCallPrivilege para alterar os privilégios de chamada especificados pelo LINECALLPRIVILEGES_Constants.

Os tipos de mídia especificados com lineOpen adicionam ao valor padrão para o monitoramento de tipo de mídia do provedor para determinação inicial do tipo de chamada de entrada. A função lineMonitorMedia modifica a máscara que controla LINE_MONITORMEDIA mensagens. Se um dispositivo de linha for aberto com privilégio de proprietário e um tipo de mídia de extensão não estiver registrado, o erro LINEERR_INVALMEDIAMODE será retornado.

Um aplicativo que abriu com êxito um dispositivo de linha sempre pode iniciar chamadas usando lineMakeCall, lineUnpark, linePickup e lineSetupConference (com um hCallNULL), bem como usar lineForward (supondo que isso seja permitido pelos recursos do dispositivo, pelo estado da linha e assim por diante).

Um único aplicativo pode especificar vários sinalizadores simultaneamente para lidar com vários tipos de mídia. Conflitos poderão surgir se vários aplicativos abrirem o mesmo dispositivo de linha para o mesmo tipo de mídia. Esses conflitos são resolvidos por um esquema de prioridade no qual o usuário atribui prioridades relativas aos aplicativos. Os usuários podem definir prioridades de aplicativo chamando a função lineSetAppPriority . Somente o aplicativo de prioridade mais alta para um determinado tipo de mídia receberá a propriedade (não solicitada) de uma chamada desse tipo de mídia. A propriedade pode ser recebida quando uma chamada de entrada chega pela primeira vez ou quando uma chamada é entregue. A função lineHandoff é chamada para entregar a propriedade de uma chamada para outro aplicativo. Se o usuário não atribuir prioridades ao aplicativo e vários aplicativos abrirem o mesmo dispositivo de linha, por padrão, o aplicativo que chamou lineOpen primeiro terá a prioridade mais alta.

Qualquer aplicativo (incluindo qualquer aplicativo de prioridade mais baixa) sempre pode adquirir a propriedade com lineGetNewCalls ou lineGetConfRelatedCalls. Se um aplicativo abrir uma linha para monitoramento em um momento em que as chamadas existem na linha, LINE_CALLSTATE mensagens para essas chamadas existentes não serão geradas automaticamente para o novo aplicativo de monitoramento. O aplicativo pode consultar o número de chamadas atuais na linha para determinar quantas chamadas existem e, se desejar, pode chamar lineGetNewCalls para obter identificadores para essas chamadas.

Um aplicativo que manipula a voz automatizada também deve selecionar o modo de abertura de voz interativa e receber a prioridade mais baixa para voz interativa. O motivo disso é que os provedores de serviços relatam todos os tipos de mídia de voz como voz interativa. Se a determinação do tipo de mídia não for executada pelo aplicativo para o tipo de mídia UNKNOWN e nenhum aplicativo de voz interativo tiver aberto o dispositivo de linha, as chamadas de voz não poderão acessar o aplicativo de voz automatizado e serão descartadas.

O mesmo aplicativo, ou instâncias diferentes do mesmo aplicativo, pode abrir a mesma linha várias vezes com os mesmos parâmetros ou parâmetros diferentes.

Quando um aplicativo abre um dispositivo de linha, ele deve especificar a versão da API negociada e, se quiser usar as extensões da linha, ele deverá especificar a versão de extensão específica do dispositivo da linha. Esses números de versão devem ter sido obtidos com lineNegotiateAPIVersion e lineNegotiateExtVersion. 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.

LINEMAPPER permite que um aplicativo selecione uma linha indiretamente, por meio dos serviços desejados. Ao abrir um dispositivo de linha usando LINEMAPPER, o seguinte é verdadeiro: todos os membros desde o início da estrutura de dados LINECALLPARAMS por meio de dwAddressMode são relevantes . Se dwAddressMode for LINEADDRESSMODE_ADDRESSID isso significa que qualquer endereço na linha é aceitável, caso contrário, se dwAddressMode for LINEADDRESSMODE_DIALABLEADDR, indicando que um endereço de origem específico (número de telefone) é pesquisado ou se é uma extensão específica do provedor, dwOrigAddressSize/Offset e a parte da parte variável à qual se referem também são relevantes. Se dwAddressMode for uma extensão específica do provedor, informações adicionais poderão ser contidas no membro de tamanho variável dwDeviceSpecific .