TSPI_providerInit-Funktion (tspi.h)

Artikel
08/26/2023

Die TSPI_providerInit-Funktion initialisiert den Dienstanbieter und gibt diesem Parameter zu, die für nachfolgende Vorgänge erforderlich sind.

Syntax

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

Parameter

dwTSPIVersion

Die Version der TSPI-Definition, unter der diese Funktion ausgeführt werden muss. Der Aufrufer kann TSPI_lineNegotiateTSPIVersion mit dem speziellen dwDeviceID-INITIALIZE_NEGOTIATION verwenden, um eine Version auszuhandeln, die für den Dienstanbieter garantiert akzeptabel ist.

dwPermanentProviderID

Der permanente Bezeichner, der innerhalb der Dienstanbieter auf diesem System eindeutig ist, des Dienstanbieters, der initialisiert wird.

dwLineDeviceIDBase

Der niedrigste Gerätebezeichner für die Leitungsgeräte, die von diesem Dienstanbieter unterstützt werden.

dwPhoneDeviceIDBase

Der niedrigste Gerätebezeichner für die von diesem Dienstanbieter unterstützten Telefongeräte.

dwNumLines

Die Anzahl von Leitungsgeräten, die von diesem Dienstanbieter unterstützt werden. Der zurückgegebene Wert ist die Anzahl der in TSPI_providerEnumDevices gemeldeten Leitungsgeräte.

dwNumPhones

Die Anzahl von Telefongeräten, die von diesem Dienstanbieter unterstützt werden. Der zurückgegebene Wert ist die Anzahl der in TSPI_providerEnumDevices gemeldeten Telefongeräte.

lpfnCompletionProc

Die Prozedur, die der Dienstanbieter aufruft, um den Abschluss aller asynchron ausgeführten Prozeduren auf Leitungs- und Telefongeräten zu melden.

lpdwTSPIOptions

Ein Zeiger auf einen Speicherspeicherort im DWORD-Format, in den der Dienstanbieter einen Wert schreiben kann, der LINETSPIOPTIONS_ Werte angibt. Dieser Parameter ermöglicht es dem Dienstanbieter, Bits zurückzugeben, die optionales Verhalten angeben, das von TAPI gewünscht wird. TAPI legt die Optionen DWORD auf 0 fest, bevor TSPI_providerInit aufgerufen wird. Wenn der Dienstanbieter also keine dieser Optionen möchte, kann er DWORD einfach auf 0 festlegen.

Derzeit ist nur ein Bit definiert, das über diesen Zeiger zurückgegeben werden soll: LINETSPIOPTION_NONREENTRANT. Der Dienstanbieter legt dieses Bit fest, wenn es nicht für vollständig präemptive, Multithreading-, Multitasking- und Multiprozessorvorgänge (z. B. aktualisieren von globalen Daten, die durch Mutexe geschützt sind) konzipiert ist. Wenn dieses Bit festgelegt ist, führt TAPI nur jeweils einen Aufruf an den Dienstanbieter durch. Es ruft keinen anderen Einstiegspunkt oder diesen Einstiegspunkt erneut auf, bis der Dienstanbieter vom ursprünglichen Funktionsaufruf zurückgibt. Ohne dieses Bitsatz kann TAPI mehrere Dienstanbietereinstiegspunkte aufrufen, einschließlich mehrmals zum gleichen Einstiegspunkt, gleichzeitig (tatsächlich gleichzeitig in einem Multiprozessorsystem).

HinweisWichtig: Es muss betont werden, dass das Festlegen dieses Bits die Leistung beeinträchtigt. Es wird dringend empfohlen, dies nur für die Entwicklung zu verwenden, aber nicht für einen gelieferten Produktionsdienstleister.

TAPI serialisiert den Zugriff auf TSPI-Funktionen, die ein Dialogfeld anzeigen ( TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, TUISPI_providerRemove), damit sie den Aufruf anderer TSPI-Funktionen nicht blockieren; Der Dienstanbieter muss internen Schutz für diese Funktionen einschließen.

Rückgabewert

Gibt null zurück, wenn die Funktion erfolgreich ist, oder eine Fehlernummer, wenn ein Fehler auftritt. Mögliche Rückgabewerte sind:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_NOMULTIPLEINSTANCE.

Hinweise

Diese Funktion wird garantiert vor einer der anderen Funktionen mit dem Präfix TSPI_line oder TSPI_phone außer TSPI_lineNegotiateTSPIVersion aufgerufen. Es wird streng mit einem nachfolgenden Aufruf von TSPI_providerShutdown Diese Paare können sich z. B. überlappen, wenn das telefonie-Systemsteuerung-Hilfsprogramm, das mit Windows-Telefonie in Version 1.4 und früher bereitgestellt wird, verwendet wird, während Telefonievorgänge ausgeführt werden. Der Aufruf dieser Funktion muss ignoriert werden (der Erfolg wird zurückgegeben), wenn bereits ein ausstehendes Paar vorhanden ist.

Ein Dienstanbieter sollte so viele Konsistenzprüfungen durchführen, wie es zu diesem Zeitpunkt praktisch ist. TSPI_providerInit wird aufgerufen, um sicherzustellen, dass es ausgeführt werden kann. Einige Konsistenz- oder Installationsfehler können jedoch erst erkannt werden, wenn der Vorgang versucht wird. Der Fehler LINEERR_NODRIVER kann verwendet werden, um solche nicht spezifischen Fehler zum Zeitpunkt ihrer Erkennung zu melden.

Es gibt keine direkt entsprechende Funktion auf TAPI-Ebene. Auf dieser Ebene können mehrere verschiedene Verwendungsinstanzen ausstehend sein, wobei ein "Anwendungshandle" zurückgegeben wird, um die instance in nachfolgenden Vorgängen zu identifizieren. Auf TSPI-Ebene unterstützt die Schnittstellenarchitektur nur eine einzelne Verwendung instance für jeden einzelnen Dienstanbieter.