TSPI_providerInit fonction (tspi.h)

Article
08/26/2023

La fonction TSPI_providerInit initialise le fournisseur de services et lui donne les paramètres nécessaires pour les opérations suivantes.

Syntaxe

LONG TSPIAPI TSPI_providerInit(
  DWORD            dwTSPIVersion,
  DWORD            dwPermanentProviderID,
  DWORD            dwLineDeviceIDBase,
  DWORD            dwPhoneDeviceIDBase,
  DWORD_PTR        dwNumLines,
  DWORD_PTR        dwNumPhones,
  ASYNC_COMPLETION lpfnCompletionProc,
  LPDWORD          lpdwTSPIOptions
);

Paramètres

dwTSPIVersion

Version de la définition TSPI sous laquelle cette fonction doit fonctionner. L’appelant peut utiliser TSPI_lineNegotiateTSPIVersion avec le INITIALIZE_NEGOTIATION spécial dwDeviceID pour négocier une version qui est acceptable pour le fournisseur de services.

dwPermanentProviderID

Identificateur permanent, unique au sein des fournisseurs de services sur ce système, du fournisseur de services en cours d’initialisation.

dwLineDeviceIDBase

Identificateur d’appareil le plus bas pour les appareils de ligne pris en charge par ce fournisseur de services.

dwPhoneDeviceIDBase

Identificateur d’appareil le plus bas pour les appareils téléphoniques pris en charge par ce fournisseur de services.

dwNumLines

Nombre d’appareils de ligne pris en charge par ce fournisseur de services. La valeur retournée est le nombre d’appareils de ligne signalés dans TSPI_providerEnumDevices.

dwNumPhones

Nombre d’appareils téléphoniques pris en charge par ce fournisseur de services. La valeur retournée est le nombre d’appareils téléphoniques signalés dans TSPI_providerEnumDevices.

lpfnCompletionProc

Procédure que le fournisseur de services appelle pour signaler l’achèvement de toutes les procédures de fonctionnement asynchrone sur les appareils en ligne et téléphoniques.

lpdwTSPIOptions

Pointeur vers un emplacement de mémoire de taille DWORD, dans lequel le fournisseur de services peut écrire une valeur spécifiant LINETSPIOPTIONS_ valeurs. Ce paramètre permet au fournisseur de services de retourner des bits indiquant les comportements facultatifs souhaités pour TAPI. TAPI définit les options DWORD sur 0 avant d’appeler TSPI_providerInit. Par conséquent, si le fournisseur de services ne souhaite aucune de ces options, il peut simplement laisser le DWORD défini sur 0.

À ce stade, un seul bit est défini pour être retourné par le biais de ce pointeur : LINETSPIOPTION_NONREENTRANT. Le fournisseur de services définit ce bit s’il n’est pas conçu pour une opération multitâche, multitâche et multitâche complète (par exemple, mise à jour des données globales protégées par des mutexes). Lorsque ce bit est défini, TAPI n’effectue qu’un seul appel à la fois au fournisseur de services ; il n’appelle aucun autre point d’entrée, ni ce point d’entrée à nouveau, tant que le fournisseur de services n’est pas retourné à partir de l’appel de fonction d’origine. Sans ce jeu de bits, TAPI peut appeler simultanément plusieurs points d’entrée du fournisseur de services, y compris plusieurs fois vers le même point d’entrée (en fait simultanément dans un système multiprocesseur).

Remarqueimportante : Il faut souligner que la définition de ce bit dégrade les performances. Il est vivement recommandé de l’utiliser uniquement pour le développement, mais pas pour un fournisseur de services de production expédié.

TAPI ne sérialise pas l’accès aux fonctions TSPI qui affichent une boîte de dialogue ( TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, TUISPI_providerRemove) afin qu’elles ne bloquent pas l’appel d’autres fonctions TSPI ; le fournisseur de services doit inclure une protection interne sur ces fonctions.

Valeur retournée

Retourne 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_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_NOMULTIPLEINSTANCE.

Remarques

Cette fonction est garantie pour être appelée avant l’une des autres fonctions préfixées par TSPI_line ou TSPI_phone, à l’exceptionde TSPI_lineNegotiateTSPIVersion. Il est strictement associé à un appel ultérieur à TSPI_providerShutdown Ces paires peuvent se chevaucher, par exemple, lorsque l’utilitaire téléphonie Panneau de configuration fourni avec La téléphonie Windows dans les versions 1.4 et antérieures est utilisé pendant que les opérations de téléphonie sont en cours. L’appel à cette fonction doit être ignoré (retour de réussite) s’il existe déjà une paire en attente.

Un fournisseur de services doit effectuer autant de vérifications de cohérence que possible à l’époque. TSPI_providerInit est appelé pour s’assurer qu’il est prêt à s’exécuter. Toutefois, certaines erreurs de cohérence ou d’installation ne peuvent pas être détectées tant que l’opération n’a pas été tentée. Le LINEERR_NODRIVER d’erreur peut être utilisé pour signaler ces erreurs non spécifiques au moment où elles sont détectées.

Il n’existe aucune fonction correspondant directement au niveau TAPI. À ce niveau, plusieurs instances d’utilisation différentes peuvent être en attente, avec un « handle d’application » retourné pour identifier les instance dans les opérations suivantes. Au niveau TSPI, l’architecture d’interface ne prend en charge qu’une seule instance d’utilisation pour chaque fournisseur de services distinct.