TSPI_linePickup, fonction (tspi.h)

Article
03/13/2024

La fonction TSPI_linePickup décroche un appel en alertant à l’adresse de destination spécifiée et retourne un descripteur d’appel pour l’appel récupéré. S’il est appelé avec null pour le paramètre lpszDestAddress , un enlèvement de groupe est effectué. Si les fonctionnalités de l’appareil l’exigent, lpszGroupID spécifie l’identificateur de groupe auquel appartient la station d’alerte.

Syntaxe

LONG TSPIAPI TSPI_linePickup(
  DRV_REQUESTID dwRequestID,
  HDRVLINE      hdLine,
  DWORD         dwAddressID,
  HTAPICALL     htCall,
  LPHDRVCALL    lphdCall,
  LPCWSTR       lpszDestAddress,
  LPCWSTR       lpszGroupID
);

Paramètres

dwRequestID

Identificateur de la requête asynchrone.

hdLine

Handle de la ligne sur laquelle un appel doit être récupéré.

dwAddressID

Adresse sur hdLine à laquelle le pick-up doit provenir. Un identificateur d’adresse est associé de manière permanente à une adresse ; l’identificateur reste constant entre les mises à niveau du système d’exploitation.

htCall

Handle TAPI pour le nouvel appel. Le fournisseur de services doit l’enregistrer et l’utiliser dans tous les appels suivants à la procédure LINEEVENT rapportant des événements sur l’appel.

lphdCall

Pointeur vers un HDRVCALL représentant l’identificateur du fournisseur de services pour l’appel. Le fournisseur de services doit remplir cet emplacement avec son handle pour l’appel avant que cette procédure ne retourne. Ce handle est ignoré par TAPI si la fonction génère une erreur.

lpszDestAddress

Pointeur vers une chaîne Unicode terminée par null qui contient l’adresse dont l’appel doit être récupéré. L’adresse est au format de lien standard.

lpszGroupID

Pointeur vers une chaîne Unicode terminée par un caractère Null contenant l’identificateur de groupe auquel appartient la station d’alerte. Ce paramètre est requis sur certains commutateurs pour récupérer les appels en dehors du groupe de prise en charge actuel.

Notez quelpszGroupID peut être spécifié par lui-même avec un pointeur NULL pour lpszDestAddress. Vous pouvez également spécifier lpszGroupID en plus de lpszDestAddress, si nécessaire par l’appareil. Il peut également être NULL lui-même.

Valeur retournée

Retourne dwRequestID, ou un numéro d’erreur si une erreur se produit. Le paramètre réel lResult de la ASYNC_COMPLETION correspondante est égal à zéro si la fonction réussit, ou un numéro d’erreur si une erreur se produit. Les valeurs de retour possibles sont les suivantes :

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALGROUPID, LINEERR_RESOURCEUNAVAIL.

Remarques

Lorsqu’un appel a été récupéré avec succès, le fournisseur de services avertit TAPI avec le message LINE_CALLSTATE concernant les changements d’état de l’appel. La structure LINECALLINFO fournit des informations sur l’appel qui a été récupéré. Il indique la raison de l’appel comme enlèvement. Cette structure est disponible en appelant TSPI_lineGetCallInfo.

Le fournisseur de services définit LINEADDRCAPFLAGS_PICKUPCALLWAIT sur TRUE dans la structure LINEADDRESSCAPS si TSPI_linePickup pouvez être utilisé pour récupérer un appel pour lequel l’utilisateur a détecté le signal d’attente d’appel, mais pour lequel le fournisseur ne peut pas effectuer la détection. Cela donne à l’utilisateur un mécanisme pour répondre à un appel en attente même si le fournisseur de services n’a pas pu détecter le signal d’attente d’appel. Lorsque TSPI_linePickup est utilisé pour récupérer un appel en attente d’appel, les paramètres de pointeur lpszDestAddress et lpszGroupID ont la valeur NULL. Le fournisseur de services crée un descripteur d’appel pour l’appel en attente et le transmet à l’utilisateur dans lphdCall. Le paramètre dwAddressID est le plus souvent égal à zéro (en particulier dans les cas résidentiels à une seule ligne).

Une fois que TSPI_linePickup est utilisé pour récupérer le deuxième appel, TSPI_lineSwapHold pouvez être utilisé pour basculer entre eux. TSPI_lineDrop pouvez être utilisé pour en supprimer un (et basculer vers l’autre), etc. Si l’utilisateur souhaite supprimer l’appel actuel et récupérer le deuxième appel, il appelle TSPI_lineDrop lorsqu’il reçoit le signal sonore en attente d’appel, attend que le deuxième appel sonne, puis appelle TSPI_lineAnswer sur le nouveau descripteur d’appel. Le fournisseur de services définit l’indicateur LINEADDRFEATURE_PICKUP dans le membre dwAddressFeatures dans LINEADDRESSSTATUS pour indiquer quand l’enlèvement est réellement possible.

Cette fonction diffère de la fonction TAPI correspondante en ce qu’elle suit le modèle TSPI pour commencer la durée de vie d’un appel. TAPI et le fournisseur de services échangent des handles opaques représentant l’appel entre eux. En outre, le fournisseur de services est autorisé à effectuer des rappels pour le nouvel appel avant qu’il ne revienne de cette procédure. Dans tous les cas, le fournisseur de services doit également traiter le handle qu’il a retourné comme « non encore valide » jusqu’à ce que le message de ASYNC_COMPLETION correspondant signale la réussite. En d’autres termes, il ne doit pas émettre de messages LINEEVENT pour le nouvel appel ou l’inclure dans le nombre d’appels dans les messages ou status structures de données pour la ligne.