Compartilhar via


Função lineHandoff (tapi.h)

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.

Requisitos

Requisito Valor
Plataforma de Destino Windows
Cabeçalho tapi.h
Biblioteca Tapi32.lib
DLL Tapi32.dll

Confira também

Referência básica dos Serviços de Telefonia

Visão geral de entregas

LINECALLINFO

Visão geral da referência do TAPI 2.2

Linegetcallstatus

Lineopen

lineSetCallPrivilege

lineSetMediaMode