fonction lineDial (tapi.h)

Article
08/26/2023

La fonction lineDial compose le numéro de numérotation spécifié sur l’appel spécifié.

Syntaxe

LONG lineDial(
  HCALL  hCall,
  LPCSTR lpszDestAddress,
  DWORD  dwCountryCode
);

Paramètres

hCall

Gérez l’appel sur lequel un numéro doit être composé. L’application doit être propriétaire de l’appel. L’état de l’appel de hCall peut être n’importe quel état, sauf inactif et déconnecté.

lpszDestAddress

Destination à composer à l’aide du format de numéro de numérotation standard.

dwCountryCode

Code de pays ou de région de la destination. Cela est utilisé par l’implémentation pour sélectionner les protocoles de progression de l’appel pour l’adresse de destination. Si la valeur 0 est spécifiée, un protocole de progression d’appel par défaut défini par le fournisseur de services est utilisé.

Valeur retournée

Retourne un identificateur de requête positif si la fonction est terminée de manière asynchrone, ou un numéro d’erreur négatif si une erreur se produit. Le paramètre dwParam2 du message LINE_REPLY correspondant est égal à zéro si la fonction réussit ou s’il s’agit d’un numéro d’erreur négatif si une erreur se produit. Les valeurs de retour possibles sont les suivantes :

LINEERR_ADDRESSBLOCKED, LINEERR_INVALPOINTER, LINEERR_DIALBILLING, LINEERR_NOMEM, LINEERR_DIALDIALTONE, LINEERR_NOTOWNER, LINEERR_DIALPROMPT, LINEERR_OPERATIONFAILED, LINEERR_DIALQUIET, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_UNINITIALIZED, LINEERR_INVALCOUNTRYCODE.

Remarques

Si LINEERR_INVALADDRESS est retourné, aucune numérotation n’a été effectuée. Si LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE ou LINEERR_DIALPROMPT est retourné, aucune des actions effectuées par lineDial n’a eu lieu. Par exemple, aucune des adresses pouvant être composer avant le caractère incriminé n’a été composé, aucun état de commutateur de crochet n’a changé, et ainsi de suite.

La fonction lineDial est utilisée pour composer sur une apparence d’appel existante. Par exemple, une fois qu’un appel a été configuré pour un transfert ou une conférence, un appel de consultation est automatiquement alloué et la fonction lineDial est utilisée pour composer cet appel de consultation. La fonction lineDial peut être appelée plusieurs fois au cours de la numérotation en plusieurs étapes, si les fonctionnalités de l’appareil de la ligne le permettent. En outre, plusieurs adresses peuvent être fournies dans une seule chaîne de numérotation séparée par CRLF. Les fournisseurs de services qui fournissent un multiplexage inverse peuvent établir des appels physiques individuels avec chacune des adresses et peuvent retourner un handle d’appel unique à l’agrégation de tous les appels à l’application. Toutes les adresses utilisent le même code de pays ou de région.

La numérotation est considérée comme terminée une fois que l’adresse a été transmise au fournisseur de services ; pas après la connexion de l’appel. Les fournisseurs de services qui fournissent un multiplexage inverse peuvent autoriser la fourniture de plusieurs adresses à la fois. Le fournisseur de services envoie LINE_CALLSTATE messages à l’application pour l’informer de la progression de l’appel. Pour annuler une tentative d’appel pendant l’établissement d’un appel, l’application appelante doit utiliser lineDrop.

Une application peut définir le paramètre lpszDestAddress de la fonction lineDial sur l’adresse d’une chaîne vide pour indiquer que la numérotation est terminée, mais uniquement si les précédents appels aux fonctions lineMakeCall et lineDial ont eu les chaînes spécifiées par lpszDestAddress terminées par des points-virgules.

La fonction lineDial peut également être utilisée dans la numérotation partielle. Pour lancer un appel à l’aide d’une numérotation partielle, l’application appelle lineMakeCall et spécifie une chaîne de numérotation partielle. Une chaîne de numérotation partielle est toute chaîne de numérotation terminée par un point-virgule. L’appel passe généralement à LINECALLSTATE_DIALING après quoi lineDial peut être appelé pour spécifier d’autres chaînes de numérotation, chacune terminée par un point-virgule. La numérotation est terminée en appelant lineDial avec une chaîne de numérotation qui n’est pas terminée par un point-virgule (par exemple, une chaîne vide). Cette technique permet aux applications d’effectuer une numérotation partielle interactive avec l’utilisateur ou d’activer une numérotation plus sophistiquée que celle d’un fournisseur de services TSP.

Si une chaîne de destination null ou une chaîne vide terminée par un point-virgule (« ; ») est entrée dans lineMakeCall , l’application passe à LINE_CALLSTATE_DIALTONE. La fonction lineDial peut être appelée dans cet état pour entrer une chaîne de numérotation unique ou plusieurs chaînes de numérotation partielles, chacune séparée par un point-virgule. L’application passe à l’état LINECALLSTATE_DIALING une fois le premier chiffre entré.

Note La fonction lineDial n’est disponible que lorsqu’un appel est en LINECALLSTATE_DIALING ou LINE_CALLSTATE_DIALTONE. Si DTMF est nécessaire lorsqu’un appel est connecté (LINECALLSTATE_CONNECTED), utilisez lineGenerateDigits.