função TSPI_linePickup (tspi.h)

Artigo
08/26/2023

A função TSPI_linePickup capta um alerta de chamada no endereço de destino especificado e retorna um identificador de chamada para a chamada escolhida. Se invocado com NULL para o parâmetro lpszDestAddress , uma retirada de grupo será executada. Se exigido pelos recursos do dispositivo, lpszGroupID especifica o identificador de grupo ao qual a estação de alerta pertence.

Sintaxe

LONG TSPIAPI TSPI_linePickup(
  DRV_REQUESTID dwRequestID,
  HDRVLINE      hdLine,
  DWORD         dwAddressID,
  HTAPICALL     htCall,
  LPHDRVCALL    lphdCall,
  LPCWSTR       lpszDestAddress,
  LPCWSTR       lpszGroupID
);

Parâmetros

dwRequestID

O identificador da solicitação assíncrona.

hdLine

O identificador para a linha na qual uma chamada deve ser coletada.

dwAddressID

O endereço no hdLine no qual a retirada deve ser originada. Um identificador de endereço está permanentemente associado a um endereço; o identificador permanece constante entre as atualizações do sistema operacional.

htCall

O identificador TAPI para a nova chamada. O provedor de serviços deve salvá-lo e usá-lo em todas as chamadas subsequentes para os eventos de relatório de procedimento LINEEVENT na chamada.

lphdCall

Um ponteiro para um HDRVCALL que representa o identificador do provedor de serviços para a chamada. O provedor de serviços deve preencher esse local com seu identificador para a chamada antes que este procedimento retorne. Esse identificador será ignorado pelo TAPI se a função resultar em um erro.

lpszDestAddress

Um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que contém o endereço cuja chamada deve ser coletada. O endereço é o formato de link padrão.

lpszGroupID

Um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que contém o identificador de grupo ao qual a estação de alerta pertence. Esse parâmetro é necessário em alguns comutadores para atender chamadas fora do grupo de retirada atual.

Observeque lpszGroupID pode ser especificado por si só com um ponteiro NULL para lpszDestAddress. Como alternativa, lpszGroupID pode ser especificado além de lpszDestAddress, se necessário pelo dispositivo. Ele também pode ser NULL em si.

Retornar valor

Retorna dwRequestID ou um número de erro se ocorrer um erro. O parâmetro real lResult do ASYNC_COMPLETION correspondente será zero se a função for bem-sucedida ou um número de erro se ocorrer um erro. Os possíveis valores retornados são os seguintes:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALGROUPID LINEERR_RESOURCEUNAVAIL.

Comentários

Quando uma chamada é recebida com êxito, o provedor de serviços notifica TAPI com a mensagem LINE_CALLSTATE sobre alterações de estado de chamada. A estrutura LINECALLINFO fornece informações sobre a chamada que foi coletada. Ele lista o motivo da chamada como retirada. Essa estrutura está disponível chamando TSPI_lineGetCallInfo.

O provedor de serviços define LINEADDRCAPFLAGS_PICKUPCALLWAIT como TRUE na estrutura LINEADDRESSCAPS se TSPI_linePickup puder ser usado para pegar uma chamada para a qual o usuário detectou audivelmente o sinal de espera de chamada, mas para o qual o provedor não consegue executar a detecção. Isso dá ao usuário um mecanismo para atender a uma chamada de espera, mesmo que o provedor de serviços não tenha conseguido detectar o sinal de espera de chamada. Quando TSPI_linePickup está sendo usado para pegar uma chamada de espera de chamada, os parâmetros de ponteiro lpszDestAddress e lpszGroupID são NULL. O provedor de serviços cria um novo identificador de chamada para a chamada de espera e passa esse identificador para o usuário em lphdCall. O parâmetro dwAddressID geralmente é zero (particularmente em casos residenciais de linha única).

Depois que TSPI_linePickup é usado para pegar a segunda chamada, TSPI_lineSwapHold pode ser usado para alternar entre elas. TSPI_lineDrop pode ser usado para soltar um (e alternar para o outro) e assim por diante. Se o usuário quiser remover a chamada atual e atender à segunda chamada, ele chamará TSPI_lineDrop quando receber o bipe de espera de chamada, aguardar a segunda chamada tocar e, em seguida, chamar TSPI_lineAnswer no novo identificador de chamada. O provedor de serviços define o sinalizador LINEADDRFEATURE_PICKUP no membro dwAddressFeatures em LINEADDRESSSTATUS para indicar quando a retirada é realmente possível.

Essa função difere da função TAPI correspondente, pois segue o modelo TSPI para iniciar o tempo de vida de uma chamada. O TAPI e o provedor de serviços trocam identificadores opacos que representam a chamada entre si. Além disso, o provedor de serviços tem permissão para fazer retornos de chamada para a nova chamada antes de retornar desse procedimento. De qualquer forma, o provedor de serviços também deve tratar o identificador retornado como "ainda não válido" até que a mensagem de ASYNC_COMPLETION correspondente reporte êxito. Em outras palavras, ele não deve emitir nenhuma mensagem LINEEVENT para a nova chamada ou incluí-la em contagens de chamadas em mensagens ou estruturas de dados status para a linha.