lineHandoff, fonction (tapi.h)

Article
08/26/2023

La fonction lineHandoff donne la propriété de l’appel spécifié à une autre application. L’application peut être spécifiée directement par son nom de fichier ou indirectement en tant qu’application de priorité la plus élevée qui gère les appels du mode multimédia spécifié.

Syntaxe

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

Paramètres

hCall

Gérer l’appel à remettre. L’application doit être propriétaire de l’appel. L’état d’appel de hCall peut être n’importe quel état.

lpszFileName

Pointeur vers une chaîne terminée par null. Si ce paramètre de pointeur n’est pas NULL, il contient le nom de fichier de l’application qui est la cible du transfert. Si la valeur est NULL, la cible de transfert est l’application de priorité la plus élevée qui a ouvert la ligne pour le privilège propriétaire pour le mode multimédia spécifié. Un nom de fichier valide n’inclut pas le chemin d’accès du fichier.

dwMediaMode

Mode média utilisé pour identifier la cible pour le transfert indirect. Le paramètre dwMediaMode identifie indirectement l’application cible qui doit recevoir la propriété de l’appel. Ce paramètre est ignoré si lpszFileName n’a pas la valeur NULL. Ce paramètre utilise une seule des constantes LINEMEDIAMODE_.

Valeur retournée

Retourne zéro si la demande réussit ou un nombre d’erreur négatif si une erreur se produit. Les valeurs de retour possibles sont les suivantes :

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

Remarques

La fonction lineHandoff retourne LINEERR_TARGETSELF si l’application appelante a tenté un transfert indirect (autrement dit, définissez le paramètre lpszFileName sur NULL) et QUE TAPI a déterminé que l’application est elle-même l’application de priorité la plus élevée pour le mode multimédia donné. Si LINEERR_TARGETNOTFOUND est retourné, une cible pour le transfert d’appel n’a pas été trouvée. Cela peut se produire si l’application nommée n’a pas ouvert la même ligne avec le bit LINECALLPRIVILEGE_OWNER dans le paramètre dwPrivileges de lineOpen. Ou, dans le cas d’un transfert en mode multimédia, aucune application n’a ouvert la même ligne avec le bit LINECALLPRIVILEGE_OWNER dans le paramètre dwPrivileges de lineOpen et avec le mode multimédia spécifié dans le paramètre dwMediaModes de lineOpen.

Le transfert d’appel permet de transmettre la propriété d’un appel entre les applications. Il existe deux types de transfert. Dans le premier type, si l’application connaît le nom de fichier de l’application cible, elle peut simplement spécifier ce nom de fichier. Si un instance de l’application cible a ouvert l’appareil de ligne, la propriété de l’appel est passée à l’autre application ; sinon, le transfert échoue et une erreur est retournée. Cette forme de transfert réussit si le handle d’appel est remis au même nom de fichier que l’application qui demande le transfert.

Le deuxième type de transfert est basé sur le mode média. Dans ce cas, l’application spécifie indirectement l’application cible au moyen d’un mode multimédia. L’application de priorité la plus élevée qui a actuellement ouvert l’appareil de ligne pour ce mode multimédia est la cible du transfert. En l’absence d’une telle application, le transfert échoue et une erreur est retournée.

La fonction lineHandoff ne modifie pas le mode multimédia d’un appel. Pour modifier le mode multimédia d’un appel, l’application doit utiliser lineSetMediaMode sur l’appel, en spécifiant le nouveau mode multimédia. Cela modifie le mode multimédia de l’appel tel qu’il est stocké dans la structure LINECALLINFO de l’appel.

Si le transfert réussit, l’application de réception reçoit un message LINE_CALLSTATE pour l’appel. Ce message indique que l’application réceptrice dispose du privilège de propriétaire pour l’appel (dwParam3). En outre, le nombre de propriétaires et/ou de moniteurs pour l’appel a peut-être changé. Cela est signalé par le message LINE_CALLINFO , et l’application réceptrice peut ensuite appeler lineGetCallStatus et lineGetCallInfo pour récupérer plus d’informations sur l’appel reçu.

L’application réceptrice doit d’abord case activée le mode multimédia dans LINECALLINFO. Si un seul indicateur de mode multimédia est défini, l’appel est officiellement de ce mode multimédia et l’application peut agir en conséquence. Si UNKNOWN et d’autres indicateurs de mode multimédia sont définis, le mode multimédia de l’appel est officiellement UNKNOWN, mais il est supposé être de l’un des modes multimédias pour lesquels un indicateur est défini dans LINECALLINFO. L’application doit supposer qu’elle doit rechercher le mode multimédia de priorité la plus élevée.

Si la sonde réussit (pour ce mode multimédia ou pour un autre), l’application doit définir le membre du mode multimédia dans LINECALLINFO sur le mode multimédia unique qui a été reconnu. Si l’indicateur de mode multimédia correspond au mode multimédia LINECALLINFO , l’application peut agir en conséquence. S’il effectue une détermination pour un autre mode multimédia, il doit d’abord remettre l’appel à ce mode multimédia.

Si la sonde échoue, l’application doit effacer l’indicateur de mode multimédia correspondant dans LINECALLINFO et transmettre l’appel, en spécifiant dwMediaMode comme LINEMEDIAMODE_UNKNOWN. Il doit également libérer son handle d’appel (ou revenir à la surveillance).

Si aucun des modes multimédias n’a réussi à effectuer une détermination, seul l’indicateur UNKNOWN reste défini dans le champ mode multimédia de LINECALLINFO au moment où l’application multimédia tente de transmettre l’appel à UNKNOWN. Le lineHandoff final échoue si l’application est le seul propriétaire restant de l’appel. Cela informe l’application qu’elle doit supprimer l’appel et libérer son handle, auquel cas l’appel est abandonné. Les privilèges de l’application appelante à l’appel sont inchangés par cette opération, mais l’application peut modifier ses privilèges en un appel avec lineSetCallPrivilege.