Função lineHandoff (tapi.h)

Artigo
08/26/2023

A função lineHandoff fornece a propriedade da chamada especificada para outro aplicativo. O aplicativo pode ser especificado diretamente por seu nome de arquivo ou indiretamente como o aplicativo de prioridade mais alta que manipula chamadas do modo de mídia especificado.

Sintaxe

LONG lineHandoff(
  HCALL  hCall,
  LPCSTR lpszFileName,
  DWORD  dwMediaMode
);

Parâmetros

hCall

Identificador para a chamada a ser entregue. O aplicativo deve ser um proprietário da chamada. O estado de chamada de hCall pode ser qualquer estado.

lpszFileName

Ponteiro para uma cadeia de caracteres terminada em nulo. Se esse parâmetro de ponteiro não for NULL, ele conterá o nome do arquivo do aplicativo que é o destino da entrega. Se FOR NULL, o destino de entrega será o aplicativo de prioridade mais alta que abriu a linha para privilégio de proprietário para o modo de mídia especificado. Um nome de arquivo válido não inclui o caminho do arquivo.

dwMediaMode

Modo de mídia usado para identificar o destino para a entrega indireta. O parâmetro dwMediaMode identifica indiretamente o aplicativo de destino que deve receber a propriedade da chamada. Esse parâmetro será ignorado se lpszFileName não for NULL. Esse parâmetro usa uma e apenas uma das Constantes LINEMEDIAMODE_.

Retornar valor

Retornará zero se a solicitação for bem-sucedida ou um número de erro negativo se ocorrer um erro. Os valores retornados possíveis são:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_TARGETNOTFOUND, LINEERR_INVALPOINTER, LINEERR_TARGETSELF, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOTOWNER.

Comentários

A função lineHandoff retorna LINEERR_TARGETSELF se o aplicativo de chamada tentou uma entrega indireta (ou seja, definir o parâmetro lpszFileName como NULL) e TAPI determinou que o aplicativo é o aplicativo de prioridade mais alta para o modo de mídia fornecido. Se LINEERR_TARGETNOTFOUND for retornado, um destino para a entrega da chamada não foi encontrado. Isso poderá ocorrer se o aplicativo nomeado não tiver aberto a mesma linha com o bit LINECALLPRIVILEGE_OWNER no parâmetro dwPrivileges de lineOpen. Ou, no caso de entrega no modo de mídia, nenhum aplicativo abriu a mesma linha com o bit LINECALLPRIVILEGE_OWNER no parâmetro dwPrivileges de lineOpen e com o modo de mídia especificado no parâmetro dwMediaModes de lineOpen.

A entrega de chamada permite que a propriedade de uma chamada seja passada entre aplicativos. Há dois tipos de entrega. No primeiro tipo, se o aplicativo souber o nome do arquivo do aplicativo de destino, ele poderá simplesmente especificar esse nome de arquivo. Se uma instância do aplicativo de destino tiver aberto o dispositivo de linha, a propriedade da chamada será passada para o outro aplicativo; caso contrário, a entrega falhará e um erro será retornado. Essa forma de entrega terá êxito se o identificador de chamada for entregue ao mesmo nome de arquivo que o aplicativo que solicita a entrega.

O segundo tipo de entrega é baseado no modo de mídia. Nesse caso, o aplicativo especifica indiretamente o aplicativo de destino por meio de um modo de mídia. O aplicativo de prioridade mais alta que atualmente abriu o dispositivo de linha para esse modo de mídia é o destino para a entrega. Se não houver esse aplicativo, a entrega falhará e um erro será retornado.

A função lineHandoff não altera o modo de mídia de uma chamada. Para alterar o modo de mídia de uma chamada, o aplicativo deve usar lineSetMediaMode na chamada, especificando o novo modo de mídia. Isso altera o modo de mídia da chamada, conforme armazenado na estrutura LINECALLINFO da chamada.

Se a entrega for bem-sucedida, o aplicativo receptor receberá uma mensagem LINE_CALLSTATE para a chamada. Essa mensagem indica que o aplicativo receptor tem privilégio de proprietário para a chamada (dwParam3). Além disso, o número de proprietários e/ou monitores da chamada pode ter sido alterado. Isso é relatado pela mensagem LINE_CALLINFO e o aplicativo de recebimento pode invocar lineGetCallStatus e lineGetCallInfo para recuperar mais informações sobre a chamada recebida.

O aplicativo receptor deve primeiro marcar o modo de mídia em LINECALLINFO. Se apenas um único sinalizador de modo de mídia estiver definido, a chamada será oficialmente desse modo de mídia e o aplicativo poderá agir de acordo. Se UNKNOWN e outros sinalizadores de modo de mídia estiverem definidos, o modo de mídia da chamada será oficialmente DESCONHECIDO, mas será considerado um dos modos de mídia para os quais um sinalizador é definido em LINECALLINFO. O aplicativo deve assumir que deve investigar o modo de mídia de prioridade mais alta.

Se a investigação for bem-sucedida (para esse modo de mídia ou para outro), o aplicativo deverá definir o membro do modo de mídia em LINECALLINFO para o modo de mídia única que foi reconhecido. Se o sinalizador de modo de mídia corresponder ao modo de mídia LINECALLINFO , o aplicativo poderá agir adequadamente. Se fizer uma determinação para outro modo de mídia, ele deverá primeiro entregar a chamada para esse modo de mídia.

Se a investigação falhar, o aplicativo deverá limpar o sinalizador de modo de mídia correspondente em LINECALLINFO e entregar a chamada, especificando dwMediaMode como LINEMEDIAMODE_UNKNOWN. Ele também deve desalocar seu identificador de chamada (ou reverter de volta ao monitoramento).

Se nenhum dos modos de mídia tiver sido bem-sucedido em fazer uma determinação, somente o sinalizador UNKNOWN permanecerá definido no campo modo de mídia de LINECALLINFO no momento em que o aplicativo de mídia tentar entregar a chamada para UNKNOWN. A linha finalHandoff falhará se o aplicativo for o único proprietário restante da chamada. Isso informa ao aplicativo que ele deve descartar a chamada e desalocar seu identificador, caso em que a chamada é abandonada. Os privilégios do aplicativo de invocação para a chamada não são alterados por essa operação, mas o aplicativo pode alterar seus privilégios para uma chamada com lineSetCallPrivilege.