DdeClientTransaction-Funktion (ddeml.h)

Artikel
02/29/2024

Startet eine Datentransaktion zwischen einem Client und einem Server. Nur eine DDE-Clientanwendung (Dynamic Data Exchange) kann diese Funktion aufrufen, und die Anwendung kann sie nur verwenden, nachdem eine Konversation mit dem Server hergestellt wurde.

Syntax

HDDEDATA DdeClientTransaction(
  [in, optional]  LPBYTE  pData,
  [in]            DWORD   cbData,
  [in]            HCONV   hConv,
  [in, optional]  HSZ     hszItem,
  [in]            UINT    wFmt,
  [in]            UINT    wType,
  [in]            DWORD   dwTimeout,
  [out, optional] LPDWORD pdwResult
);

Parameter

[in, optional] pData

Typ: LPBYTE

Der Anfang der Daten, die der Client an den Server übergeben muss.

Optional kann eine Anwendung das Datenhandle (HDDEDATA) angeben, das an den Server übergeben werden soll. In diesem Fall sollte der cbData-Parameter auf -1 festgelegt werden. Dieser Parameter ist nur erforderlich, wenn der wType-ParameterXTYP_EXECUTE oder XTYP_POKE ist. Andernfalls sollte dieser Parameter NULL sein.

Für die optionale Verwendung dieses Parameters XTYP_POKE Transaktionen, bei denen pData ein Datenhandle ist, muss das Handle durch einen vorherigen Aufruf der DdeCreateDataHandle-Funktion erstellt worden sein, wobei dasselbe Datenformat verwendet wurde, das im wFmt-Parameter angegeben ist.

[in] cbData

Art: DWORD

Die Länge der Daten in Bytes, auf die der pData-Parameter verweist, einschließlich des abschließenden NULL, wenn es sich bei den Daten um eine Zeichenfolge handelt. Der Wert -1 gibt an, dass pData ein Datenhandle ist, das die gesendeten Daten identifiziert.

[in] hConv

Typ: HCONV

Ein Handle für die Konversation, in der die Transaktion stattfinden soll.

[in, optional] hszItem

Typ: HSZ

Ein Handle für das Datenelement, für das während der Transaktion Daten ausgetauscht werden. Dieses Handle muss durch einen vorherigen Aufruf der Funktion DdeCreateStringHandle erstellt worden sein. Dieser Parameter wird ignoriert (und sollte auf 0L festgelegt werden), wenn der wType-ParameterXTYP_EXECUTE ist.

[in] wFmt

Typ: UINT

Das Standardformat der Zwischenablage, in dem das Datenelement übermittelt oder angefordert wird.

Wenn die vom wType-Parameter angegebene Transaktion keine Daten übergibt oder XTYP_EXECUTE ist, sollte dieser Parameter null sein.

Wenn die durch den wType-Parameter angegebene Transaktion auf nicht ausgeführte DDE-Daten ( XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_REQUEST) verweist, muss der wFmt-Wert entweder ein gültiges vordefiniertes (CF_) DDE-Format oder ein gültiges registriertes Zwischenablageformat sein.

[in] wType

Typ: UINT

Der Transaktionstyp: Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
XTYP_ADVSTART 0x1030	Startet eine Empfehlungsschleife. Innerhalb einer Unterhaltung kann eine beliebige Anzahl unterschiedlicher Beratungsschleifen vorhanden sein. Eine Anwendung kann den Typ der Empfehlungsschleife ändern, indem sie den XTYP_ADVSTART Transaktionstyp mit einem oder mehreren der folgenden Flags kombiniert: XTYPF_NODATA. Weist den Server an, den Client über Datenänderungen zu benachrichtigen, ohne die Daten tatsächlich zu senden. Dieses Flag gibt dem Client die Möglichkeit, die Benachrichtigung zu ignorieren oder die geänderten Daten vom Server anzufordern. XTYPF_ACKREQ. Weist den Server an, zu warten, bis der Client bestätigt, dass er das vorherige Datenelement empfangen hat, bevor das nächste Datenelement gesendet wird. Dieses Flag verhindert, dass ein schneller Server Daten schneller sendet, als der Client sie verarbeiten kann.
XTYP_ADVSTOP 0x8040	Beendet eine Empfehlungsschleife.
XTYP_EXECUTE 0x4050	Startet eine Ausführungstransaktion.
XTYP_POKE 0x4090	Startet eine Poke-Transaktion.
XTYP_REQUEST 0x20B0	Startet eine Anforderungstransaktion.

[in] dwTimeout

Art: DWORD

Die maximale Zeitspanne in Millisekunden, für die der Client in einer synchronen Transaktion auf eine Antwort der Serveranwendung wartet. Dieser Parameter sollte für asynchrone Transaktionen TIMEOUT_ASYNC werden.

[out, optional] pdwResult

Typ: LPDWORD

Ein Zeiger auf eine Variable, die das Ergebnis der Transaktion empfängt. Eine Anwendung, die das Ergebnis nicht überprüft, kann NULL für diesen Wert verwenden. Bei synchronen Transaktionen enthält das Wort mit niedriger Ordnung dieser Variablen alle anwendbaren DDE_ Flags, die sich aus der Transaktion ergeben. Dies bietet Unterstützung für Anwendungen, die von DDE_APPSTATUS Bits abhängig sind. Es wird jedoch empfohlen, dass Anwendungen diese Bits nicht mehr verwenden, da sie in zukünftigen Versionen der Dynamic Data Exchange Management Library (DDEML) möglicherweise nicht mehr unterstützt werden. Bei asynchronen Transaktionen wird diese Variable mit einem eindeutigen Transaktionsbezeichner für die Verwendung mit der Funktion DdeAbandonTransaction und der XTYP_XACT_COMPLETE Transaktion gefüllt.

Rückgabewert

Typ: HDDEDATA

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Datenhandle, das die Daten für erfolgreiche synchrone Transaktionen identifiziert, bei denen der Client Daten vom Server erwartet. Der Rückgabewert ist ungleich null für erfolgreiche asynchrone Transaktionen und für synchrone Transaktionen, bei denen der Client keine Daten erwartet. Der Rückgabewert ist 0 (null) für alle nicht erfolgreichen Transaktionen.

Die DdeGetLastError-Funktion kann verwendet werden, um den Fehlercode abzurufen, der einer der folgenden Werte sein kann:

Hinweise

Wenn eine Anwendung die Verwendung des von DdeClientTransaction zurückgegebenen Datenhandles abgeschlossen hat, sollte die Anwendung das Handle durch Aufrufen der Funktion DdeFreeDataHandle freigeben.

Transaktionen können synchron oder asynchron sein. Während einer synchronen Transaktion wird DdeClientTransaction erst zurückgegeben, wenn die Transaktion entweder erfolgreich abgeschlossen wurde oder fehlschlägt. Synchrone Transaktionen bewirken, dass ein Client in eine modale Schleife wechselt, während er auf verschiedene asynchrone Ereignisse wartet. Aus diesem Fall kann eine Clientanwendung weiterhin auf Benutzereingaben reagieren, während sie auf eine synchrone Transaktion wartet, aber die Anwendung kann aufgrund der aktivität, die der ersten zugeordnet ist, keine zweite synchrone Transaktion starten. DdeClientTransaction schlägt fehl, wenn eine instance derselben Aufgabe bereits eine synchrone Transaktion ausgeführt hat.

Während einer asynchronen Transaktion gibt DdeClientTransaction zurück, nachdem die Transaktion begonnen hat, und übergibt einen Transaktionsbezeichner zur Referenz. Wenn die DDE-Rückruffunktion des Servers die Verarbeitung einer asynchronen Transaktion abgeschlossen hat, sendet das System eine XTYP_XACT_COMPLETE Transaktion an den Client. Diese Transaktion stellt dem Client die Ergebnisse der asynchronen Transaktion bereit, die er durch Aufrufen von DdeClientTransaction initiiert hat. Eine Clientanwendung kann eine asynchrone Transaktion abbrechen, indem sie die Funktion DdeAbandonTransaction aufruft .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ddeml.h (Windows.h einschließen)
Bibliothek	User32.lib
DLL	User32.dll