Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
A função lineOpen abre o dispositivo de linha especificado pelo 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 lineOpenW(
HLINEAPP hLineApp,
DWORD dwDeviceID,
LPHLINE lphLine,
DWORD dwAPIVersion,
DWORD dwExtVersion,
DWORD_PTR dwCallbackInstance,
DWORD dwPrivileges,
DWORD dwMediaModes,
LPLINECALLPARAMS const lpCallParams
);
Parâmetros
hLineApp
Manipule 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.
lphLine
Ponteiro para um identificador HLINE que é carregado com o identificador que representa o dispositivo de linha aberta. 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 de 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 da instância do 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 Este 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 um ou mais dos LINEOPENOPTION_ Constants.
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
Se LINEOPENOPTION_SINGLEADDRESS for especificada, mas
Além de definir o membro
A opção LINEOPENOPTION_SINGLEADDRESS afeta apenas a atribuição da 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 está restrito de forma alguma 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
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 roteada 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, juntamente 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 de 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 será significativo somente 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 é ignorado. Ele descreve o parâmetro de chamada que o dispositivo de linha deve ser capaz de fornecer.
Valor de retorno
Retornará zero se a solicitação for bem-sucedida ou um número de erro negativo se ocorrer um erro. Os possíveis valores retornados 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.
Observações
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 comprometimento de recursos dinâmico, 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 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), solicitações de 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 se torna eficaz 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 a 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 for registrado, o erro LINEERR_INVALMEDIAMODE será retornado.
Um aplicativo que abriu com êxito um dispositivo de linha sempre pode iniciar chamadas usando lineMakeCall, lineUnpark, linePickupe lineSet de configuração (com um hCall null), 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á 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 a 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 inferior) sempre pode adquirir a propriedade com lineGetNewCalls ou lineGetConfRelatedCalls. Se um aplicativo abrir uma linha de monitoramento em um momento em que as chamadas existirem 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 nela. Ao abrir um dispositivo de linha usando LINEMAPPER, o seguinte é verdadeiro: todos os membros desde o início do LINECALLPARAMS estrutura de dados 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 for 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 dwDeviceSpecific variavelmente dimensionado.
Nota
O cabeçalho tapi.h define lineOpen como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino |
Windows |
| cabeçalho | tapi.h |
| biblioteca | Tapi32.lib |
| de DLL |
Tapi32.dll |
Consulte também
Referência dos Serviços básicos de telefonia
visão geral de referência do TAPI 2.2
lineGetNewCalls
lineNegotiateExtVersion
lineProxyMessage
lineSetupConference