Função lineForward (tapi.h)

Artigo
08/26/2023

A função lineForward encaminha chamadas destinadas ao endereço especificado na linha especificada, de acordo com as instruções de encaminhamento especificadas. Quando um endereço de origem (dwAddressID) é encaminhado, as chamadas de entrada especificadas para esse endereço são desviadas para o outro número pela opção. Essa função fornece uma combinação de recursos de encaminhamento e não perturbação. Essa função também pode cancelar o encaminhamento atualmente em vigor.

Sintaxe

LONG lineForward(
  HLINE                   hLine,
  DWORD                   bAllAddresses,
  DWORD                   dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD                   dwNumRingsNoAnswer,
  LPHCALL                 lphConsultCall,
  LPLINECALLPARAMS const  lpCallParams
);

Parâmetros

hLine

Manipule para o dispositivo de linha.

bAllAddresses

Especifica se todos os endereços de origem na linha ou apenas o especificado devem ser encaminhados. Se TRUE, todos os endereços na linha serão encaminhados e dwAddressID será ignorado; se FALSE, somente o endereço especificado como dwAddressID será encaminhado.

dwAddressID

Endereço na linha especificada cujas chamadas de entrada devem ser encaminhadas. Esse parâmetro será ignorado se bAllAddresses for TRUE.

Um identificador de endereço está permanentemente associado a um endereço; o identificador permanece constante entre as atualizações do sistema operacional.

lpForwardList

Ponteiro para uma estrutura de dados de tamanho variável que descreve as instruções de encaminhamento específicas, do tipo LINEFORWARDLIST.

dwNumRingsNoAnswer

O número de anéis antes de uma chamada é considerado uma "sem resposta". Se dwNumRingsNoAnswer estiver fora do intervalo, o valor real será definido como o valor mais próximo no intervalo permitido.

lphConsultCall

Ponteiro para um local HCALL. Em alguns ambientes de telefonia, esse local é carregado com um identificador para uma chamada de consulta que é usada para consultar a parte que está sendo encaminhada e o aplicativo se torna o único proprietário inicial dessa chamada. Esse ponteiro deve ser válido mesmo em ambientes em que o encaminhamento de chamadas não requer uma chamada de consulta. Esse identificador será definido como NULL se nenhuma chamada de consulta for criada.

lpCallParams

Ponteiro para uma estrutura do tipo LINECALLPARAMS. Esse ponteiro é ignorado, a menos que lineForward exija o estabelecimento de uma chamada para o destino de encaminhamento (e lphConsultCall é retornado, nesse caso , lpCallParams é opcional). Se NULL, os parâmetros de chamada padrão serão usados. Caso contrário, os parâmetros de chamada especificados são usados para estabelecer hConsultCall.

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_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPARAM, LINEERR_UNINITIALIZED.

Comentários

Um encaminhamento bem-sucedido indica apenas que a solicitação foi aceita pelo provedor de serviços, não que o encaminhamento esteja configurado na opção . Uma mensagem de LINE_ADDRESSSTATE (encaminhamento) fornece a confirmação de que o encaminhamento foi configurado na opção.

O encaminhamento dos endereços permanece em vigor até que essa função seja chamada novamente. A lista de encaminhamento mais recente substitui a antiga. O encaminhamento pode ser cancelado especificando um ponteiro NULL como lpForwardList. Se um endereço de destino NULL for especificado para uma entrada na lista de encaminhamento, a operação atuará como um não-perturbe.

O encaminhamento status de um endereço também pode ser afetado externamente; por exemplo, por ações administrativas na opção ou por um usuário de outra estação. Talvez não seja possível que o provedor de serviços esteja ciente dessa alteração de estado e talvez não seja possível manter a sincronização com o estado de encaminhamento conhecido pela opção.

Como um provedor de serviços pode não saber o estado de encaminhamento do endereço "com certeza" (ou seja, ele pode ter sido encaminhado ou desviado de uma maneira desconhecida), lineForward terá êxito, a menos que não defina as novas instruções de encaminhamento. Em outras palavras, uma solicitação para que todo o encaminhamento seja cancelado em um momento em que não haja nenhum encaminhamento em vigor é bem-sucedida. Isso ocorre porque não há nenhum "desamparado". Você só pode alterar o conjunto anterior de instruções de encaminhamento.

O êxito ou a falha dessa operação não depende do conjunto anterior de instruções de encaminhamento e o mesmo é verdadeiro ao definir instruções de encaminhamento diferentes. O provedor deve "cancelar tudo" antes de definir as novas instruções de encaminhamento. Como isso pode levar tempo em ambientes de telefonia analógica, um provedor também pode querer comparar o encaminhamento atual com o novo e emitir apenas instruções para a opção para chegar ao estado final (deixando o encaminhamento inalterado não afetado).

Invocar lineForward quando LINEFORWARDLIST tem dwNumEntries definido como zero tem o mesmo efeito que fornecer um parâmetro nulllpForwardList . Ele cancela todo o encaminhamento atualmente em vigor.