Função linePickup (tapi.h)

Artigo
08/26/2023

A função 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 pelo dispositivo, lpszGroupID especifica o identificador de grupo ao qual a estação de alerta pertence.

Sintaxe

LONG linePickup(
  HLINE   hLine,
  DWORD   dwAddressID,
  LPHCALL lphCall,
  LPCSTR  lpszDestAddress,
  LPCSTR  lpszGroupID
);

Parâmetros

hLine

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

dwAddressID

Endereço no hLine 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.

lphCall

Ponteiro para um local de memória em que o identificador para a chamada coletada é retornado. O aplicativo é o único proprietário inicial da chamada.

lpszDestAddress

Ponteiro para um buffer de caracteres terminado em nulo que contém o endereço cuja chamada deve ser coletada. O endereço está no formato de endereço discável padrão.

lpszGroupID

Ponteiro para um buffer de caracteres terminado 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.

O parâmetro lpszGroupID pode ser especificado por si mesmo com um ponteiro NULL para lpszDestAddress. Como alternativa, lpszGroupID pode ser especificado além de lpszDestAddress, se necessário pelo dispositivo.

Retornar valor

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_INVALADDRESS, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALGROUPID, LINEERR_OPERATIONFAILED, LINEERR_INVALLINEHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Comentários

Quando uma chamada é recebida com êxito, o aplicativo é notificado pela 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 usando lineGetCallInfo.

Se LINEADDRCAPFLAGS_PICKUPCALLWAIT for TRUE, linePickup poderá 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 "responder" a uma chamada de espera, mesmo que o provedor de serviços não tenha conseguido detectar o sinal de espera de chamada. Os parâmetros de ponteiro lpszDestAddress e lpszGroupID devem ser NULL para pegar uma chamada de espera de chamada. A função linePickup cria um novo identificador de chamada para a chamada de espera e passa esse identificador para o usuário. O parâmetro dwAddressID geralmente é zero (particularmente em casos residenciais de linha única).

Depois que linePickup tiver sido usado para pegar a segunda chamada, lineSwapHold poderá ser usado para alternar entre elas. A função lineDrop pode ser usada 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 deverá chamar lineDrop quando receber o bipe de espera de chamada, aguardar a segunda chamada tocar e, em seguida, chamar lineAnswer no novo identificador de chamada. O sinalizador LINEADDRFEATURE_PICKUP no membro dwAddressFeatures em LINEADDRESSSTATUS indica quando a retirada é realmente possível.