fonction TSPI_lineMakeCall (tspi.h)

Article
03/06/2024

La fonction TSPI_lineMakeCall place un appel sur la ligne spécifiée à l’adresse de destination spécifiée. Si vous le souhaitez, les paramètres d’appel peuvent être spécifiés si des paramètres d’installation d’appel par défaut sont demandés.

Syntaxe

LONG TSPIAPI TSPI_lineMakeCall(
  DRV_REQUESTID          dwRequestID,
  HDRVLINE               hdLine,
  HTAPICALL              htCall,
  LPHDRVCALL             lphdCall,
  LPCWSTR                lpszDestAddress,
  DWORD                  dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Paramètres

dwRequestID

Identificateur de la requête asynchrone.

hdLine

Handle de la ligne sur laquelle le nouvel appel doit provenir.

htCall

Le 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 les événements sur l’appel.

lphdCall

Pointeur vers un handle d’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 spécifie l’adresse de destination. Cela suit le format de numéro de numérotation standard. Ce pointeur peut être spécifié comme NULL pour les adresses non composées (comme avec un téléphone chaud, qui se connecte toujours automatiquement à un numéro prédéfini) ou lorsque toute la numérotation est effectuée à l’aide de TSPI_lineDial. Dans ce dernier cas, TSPI_lineMakeCall alloue une apparence d’appel disponible qui resterait généralement dans l’état de la numérotation jusqu’à ce que la numérotation commence. Les fournisseurs de services qui ont des fonctionnalités de multiplexage inverse peuvent permettre à une application de spécifier plusieurs adresses à la fois.

dwCountryCode

Code de pays ou de région de la partie appelée. Si la valeur 0 est spécifiée, une valeur par défaut est utilisée par l’implémentation.

lpCallParams

Pointeur vers une structure LINECALLPARAMS . Cette structure permet à TAPI de spécifier la façon dont il souhaite que l’appel soit configuré. Si NULL est spécifié, un appel vocal par défaut de 3,1 kHz est établi et une adresse d’origine arbitraire sur la ligne est sélectionnée. Cette structure sélectionne des éléments tels que le mode du porteur de l’appel, le débit de données, le type de média attendu, l’adresse d’origine, le blocage des informations d’ID de l’appelant et les paramètres de numérotation.

Valeur retournée

Retourne dwRequestID ou un numéro d’erreur si une erreur se produit. Le paramètre réel lResult du ASYNC_COMPLETION correspondant est 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_ADDRESSBLOCKED, LINEERR_INVALLINESTATE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_DIALBILLING, LINEERR_INVALADDRESS, LINEERR_DIALQUIET, LINEERR_INVALADDRESSID, LINEERR_DIALDIALTONE, LINEERR_INVALCALLPARAMS, LINEERR_DIALPROMPT, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALBEARERMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_ INVALCOUNTRYCODE, LINEERR_RATEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_USERUSERINFOTOOBIG.

Remarques

Le fournisseur de services retourne LINEERR_INVALLINESTATE si la ligne n’est actuellement pas dans un état dans lequel cette opération peut être effectuée. Vous trouverez la liste des opérations actuellement valides dans le membre dwLineFeatures (de type LINEFEATURE) de la structure LINEDEVSTATUS . ( L’appel TSPI_lineGetLineDevStatus met à jour les informations dans LINEDEVSTATUS.)

Si le fournisseur de services retourne LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE ou LINEERR_DIALPROMPT, il ne doit effectuer aucune des actions effectuées par TSPI_lineMakeCall. Par exemple, pas de numérotation partielle et pas d’offhook. Cela est dû au fait que le fournisseur de services doit d’abord analyser au préalable le nombre de caractères non pris en charge.

Une fois que TSPI_lineMakeCall retourne un message de rappel de réponse SUCCESS à l’application, le fournisseur de services doit envoyer LINE_CALLSTATE messages au lpfnEventProc transmis dans TSPI_lineOpen pour informer TAPI de la progression de l’appel. Une séquence signalée classique peut être la tonalité, la numérotation, la poursuite, la sonnerie et la connexion ; Le premier état signalé n’est pas nécessairement LINECALLSTATE_DIALTONE. Le fournisseur de services choisit le nombre d’états signalés. Il est recommandé d’envoyer autant que possible d’applications afin que les applications puissent prendre les mesures appropriées.

Le fournisseur de services effectue initialement une surveillance des médias sur le nouvel appel pour au moins l’ensemble des types de médias qui ont été surveillés sur la ligne.

Si la chaîne de numérotation a la valeur NULL, le fournisseur de services prend la ligne à l’état de numérotation (pour un fournisseur de services basé sur Comm, cela implique ATD) et envoie un message d’état d’appel indiquant LINECALLSTATE_DIALTONE.

Si la chaîne de numérotation se termine par « ; » (un point-virgule), le fournisseur de services compose le numéro partiel et envoie le message LINECALLSTATE_DIALING. Cet appel est complété par des appels à TSPI_lineDial.

Si la chaîne de numérotation contient des caractères (W, @, $, ?) qui ne sont pas pris en charge par le fournisseur de services, le fournisseur de services doit analyser la chaîne de numérotation et retourner (de manière synchrone) une erreur correspondant au premier caractère non valide.

Si l’indicateur LINECALLPARAMFLAGS_IDLE est défini, le fournisseur de services doit case activée l’status de ligne actuelle (l’équivalent d’un dé-crochet et d’une tonalité de détection). Si cet indicateur IDLE est défini et qu’il n’y a pas de tonalité de numérotation, la fonction échoue avec l’erreur LINEERR_CALLUNAVAIL. Si l’indicateur IDLE n’est pas défini ou s’il existe une tonalité, la numérotation peut continuer.

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 retourne à partir 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 l’ASYNC_COMPLETION message correspondant signale la réussite. Il ne doit pas émettre de messages LINEEVENT pour le nouvel appel ni l’inclure dans le nombre d’appels dans les messages ou status structures de données pour la ligne.