função TSPI_lineForward (tspi.h)

Artigo
08/26/2023

A função TSPI_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 específico atualmente em vigor.

Sintaxe

LONG TSPIAPI TSPI_lineForward(
  DRV_REQUESTID           dwRequestID,
  HDRVLINE                hdLine,
  DWORD                   bAllAddresses,
  DWORD                   dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD                   dwNumRingsNoAnswer,
  HTAPICALL               htConsultCall,
  LPHDRVCALL              lphdConsultCall,
  LPLINECALLPARAMS const  lpCallParams
);

Parâmetros

dwRequestID

O identificador da solicitação assíncrona.

hdLine

O identificador do provedor de serviços para a linha a ser encaminhada.

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. Esse parâmetro não é validado pelo TAPI quando essa função é chamada.

dwAddressID

O endereço na linha especificada cujas chamadas de entrada devem ser encaminhadas. Esse parâmetro será ignorado se bAllAddresses for TRUE. Esse parâmetro não é validado pelo TAPI quando essa função é chamada.

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

lpForwardList

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

dwNumRingsNoAnswer

Especifica o número de anéis antes que uma chamada de entrada seja considerada uma "sem resposta". Se dwNumRingsNoAnswer estiver fora do intervalo, o valor real será definido como o valor mais próximo no intervalo permitido. Esse parâmetro não é validado pelo TAPI quando essa função é chamada.

htConsultCall

O identificador TAPI para uma nova chamada, se essa chamada precisar ser criada pelo provedor de serviços. Em alguns ambientes de telefonia, encaminhar uma chamada tem o efeito colateral da criação de uma chamada de consulta usada para consultar a parte que está sendo encaminhada. Nesse ambiente, o provedor de serviços cria a nova chamada de consulta e deve salvar esse valor e usá-lo em todas as chamadas subsequentes para os eventos de relatório de procedimento LINEEVENT na chamada. Se nenhuma chamada de consulta for criada, esse valor poderá ser ignorado pelo provedor de serviços.

lphdConsultCall

Um ponteiro para um HDRVCALL que representa o identificador do provedor de serviços para a chamada. Em ambientes de telefonia em que o encaminhamento de uma chamada tem o efeito colateral da criação de uma chamada de consulta usada para consultar a parte que está sendo encaminhada, o provedor de serviços deve preencher esse local com seu identificador para a chamada antes que esse procedimento retorne. O provedor de serviços tem permissão para fazer retornos de chamada em relação à nova chamada antes de retornar desse procedimento. Se nenhuma chamada de consulta for criada, o HDRVCALL deverá ser deixado NULL.

lpCallParams

Um ponteiro para uma estrutura do tipo LINECALLPARAMS. Esse ponteiro é ignorado pelo provedor de serviços, a menos que lineForward exija o estabelecimento de uma chamada para o destino de encaminhamento (e lphdConsultCall é 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 htConsultCall.

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_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL.

Comentários

O provedor de serviços retornará LINEERR_INVALPARAM se o parâmetro de lista de encaminhamento especificado contiver informações inválidas.

O provedor de serviços não executará nenhuma discagem se retornar LINEERR_INVALADDRESS.

O provedor de serviços retorna êxito para essa função para indicar apenas que a solicitação é aceita pelo provedor de serviços, não que o encaminhamento esteja configurado na opção . Uma mensagem LINE_ADDRESSSTATE (encaminhamento) é enviada para fornecer que o encaminhamento está configurado na opção .

O encaminhamento do endereço ou endereços permanece em vigor até que essa função seja chamada novamente. A lista de encaminhamento mais recente substitui qualquer antiga em vigor. Se essa função for chamada, especificando um ponteiro NULL como lpForwardList, o provedor de serviços deverá cancelar qualquer encaminhamento que esteja sendo executado nesse momento. 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 meio de 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 consiga manter a sincronização com o estado de encaminhamento conhecido pela opção. O provedor deve sempre indicar o que sabe ser verdadeiro e indicar que o estado de encaminhamento é desconhecido caso contrário.

Como um provedor de serviços pode não saber o estado de encaminhamento do endereço sem dúvida (ou seja, ele pode ter sido encaminhado ou desviado de uma maneira desconhecida), TSPI_lineForward é bem-sucedido, 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 há nenhum encaminhamento em vigor é bem-sucedida. Isso ocorre porque não há nenhum avanço; você só pode invocar um novo conjunto 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. Se necessário, 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 apenas emitir instruções para a opção para chegar ao estado final (deixando o encaminhamento inalterado não afetado).

Invocar TSPI_lineForward quando LINEFORWARDLIST tiver dwNumEntries definido como zero tem o mesmo efeito que fornecer um parâmetro lpForwardListNULL; ele cancela todo o encaminhamento atualmente em vigor.

Como o valor NULL retornado em lphdConsultCall é a única maneira de o TAPI determinar se o provedor de serviços criou uma chamada de consulta, o provedor de serviços não pode usar NULL como um identificador de chamada.

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 o ASYNC_COMPLETION correspondente reporte êxito. Em outras palavras, ele não deve emitir nenhuma mensagem para a nova chamada ou incluí-la em contagens de chamadas em mensagens ou status estruturas de dados para a linha.