Função lineMakeCall (tapi.h)

Artigo
08/26/2023

A função lineMakeCall coloca uma chamada na linha especificada para o endereço de destino especificado. Opcionalmente, os parâmetros de chamada poderão ser especificados se qualquer coisa, exceto os parâmetros de configuração de chamada padrão, forem solicitados.

Sintaxe

LONG lineMakeCall(
  HLINE                  hLine,
  LPHCALL                lphCall,
  LPCSTR                 lpszDestAddress,
  DWORD                  dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Parâmetros

hLine

Manipule para o dispositivo de linha aberta no qual uma chamada deve ser originada.

lphCall

Ponteiro para um identificador HCALL. O identificador só é válido depois que a mensagem LINE_REPLY é recebida pelo aplicativo indicando que a função lineMakeCall foi concluída com êxito. Use esse identificador para identificar a chamada ao invocar outras operações de telefonia na chamada. Inicialmente, o aplicativo é o único proprietário dessa chamada. Esse identificador será nulo se a função retornar um erro (de forma síncrona ou assíncrona pela mensagem de resposta).

lpszDestAddress

Ponteiro para o endereço de destino. Isso segue o formato de número discável padrão. Esse ponteiro pode ser NULL para endereços não discados (como com um telefone quente) ou quando toda a discagem é executada usando lineDial. No último caso, lineMakeCall aloca uma aparência de chamada disponível que normalmente permaneceria no estado dialtone até que a discagem comece. Os provedores de serviços que têm funcionalidades de multiplexação inversas podem permitir que um aplicativo especifique vários endereços ao mesmo tempo.

dwCountryCode

Código de país ou região da parte chamada. Se um valor de 0 for especificado, um padrão será usado pela implementação.

lpCallParams

Ponteiro para uma estrutura LINECALLPARAMS . Essa estrutura permite que o aplicativo especifique como ele deseja que a chamada seja configurada. Se NULL for especificado, uma chamada de voz padrão de 3,1 kHz será estabelecida e um endereço de origem arbitrária na linha será selecionado. Essa estrutura permite que o aplicativo selecione elementos como o modo de portador da chamada, a taxa de dados, o modo de mídia esperado, o endereço de origem, o bloqueio de informações de ID do chamador e os parâmetros de discagem.

Valor retornado

Retorna um identificador de solicitação positivo se a função for concluída de forma assíncrona ou um número de erro negativo se ocorrer um erro. O parâmetro dwParam2 da mensagem de LINE_REPLY correspondente será zero se a função for bem-sucedida ou se for um número de erro negativo se ocorrer um erro. Os possíveis valores retornados são:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALLINEHANDLE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CALLUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_DIALBILLING, LINEERR_INVALPARAM, LINEERR_DIALDIALTONE, LINEERR_INVALPOINTER, LINEERR_DIALPROMPT, LINEERR_INVALRATE, LINEERR_DIALQUIET, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_RATEUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_ RESOURCEUNAVAIL, LINEERR_INVALBEARERMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALCALLPARAMS, LINEERR_UNINITIALIZED, LINEERR_INVALCOUNTRYCODE, LINEERR_USERUSERINFOTOOBIG.

Comentários

Se LINEERR_INVALLINESTATE for retornado, a linha não estará atualmente em um estado no qual essa operação pode ser executada. Uma lista de operações válidas no momento pode ser encontrada no membro dwLineFeatures (do tipo LINEFEATURE_) na estrutura LINEDEVSTATUS . Chamar lineGetLineDevStatus atualiza as informações em LINEDEVSTATUS. Se LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE ou LINEERR_DIALPROMPT for retornado, nenhuma das ações executadas de outra forma por lineMakeCall ocorreu; por exemplo, nenhum dos endereços discáveis antes do caractere ofensivo foi discado, nenhum estado hookswitch foi alterado e assim por diante.

Após a conclusão da discagem, várias mensagens LINE_CALLSTATE geralmente são enviadas ao aplicativo para notificá-lo sobre o progresso da chamada. Nenhuma sequência geralmente válida de transições de estado de chamada é especificada, pois nenhuma sequência fixa única de transições pode ser garantida na prática. Uma sequência típica pode fazer com que uma chamada faça a transição de dialtone, discagem, continuação, ringback, para conectada. Com linhas não discadas, a chamada normalmente pode fazer a transição diretamente para o estado conectado .

Um aplicativo tem a opção de especificar um endereço de origem no dispositivo de linha especificado. Um provedor de serviços que modela todas as estações em um comutador como endereços em um único dispositivo de linha permite que o aplicativo origine chamadas de qualquer uma dessas estações usando lineMakeCall.

Os parâmetros de chamada permitem que o aplicativo faça chamadas sem voz ou solicite opções especiais de configuração de chamada que não estão disponíveis por padrão.

Um aplicativo pode discar parcialmente usando lineMakeCall e continuar discando usando lineDial. Para obter mais informações sobre discagem parcial, consulte lineDial e TSPI_lineMakeCall. Para abandonar uma tentativa de chamada, use lineDrop.

Depois que lineMakeCall retorna uma mensagem de resposta de êxito para o aplicativo, uma mensagem LINE_CALLSTATE é enviada ao aplicativo para indicar o estado atual da chamada. Esse estado não é necessariamente LINECALLSTATE_DIALTONE.

Essa função pode enviar dados sobre o fio em forma não criptografada; portanto, alguém escutando na rede pode ser capaz de ler os dados. O risco de segurança de enviar os dados em texto claro deve ser considerado antes de usar esse método.

Cuidado O TAPI gravará os dados retornados no buffer referenciado por lphCall quando a mensagem LINE_REPLY for retornada. Isso significa que o buffer deve permanecer válido até que a mensagem LINE_REPLY seja retornada; caso contrário, podem ocorrer exceções e corrupção de dados.