Fungsi DdeClientTransaction (ddeml.h)

Artikel
08/23/2023

Memulai transaksi data antara klien dan server. Hanya aplikasi klien Dynamic Data Exchange (DDE) yang dapat memanggil fungsi ini, dan aplikasi dapat menggunakannya hanya setelah membuat percakapan dengan server.

Sintaks

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

Jenis: LPBYTE

Awal data yang harus diteruskan klien ke server.

Secara opsional, aplikasi dapat menentukan handel data (HDDEDATA) untuk diteruskan ke server dan dalam hal ini parameter cbData harus diatur ke -1. Parameter ini diperlukan hanya jika parameter wTypeXTYP_EXECUTE atau XTYP_POKE. Jika tidak, parameter ini harus NULL.

Untuk penggunaan opsional parameter ini, XTYP_POKE transaksi di mana pData adalah handel data, handel harus dibuat oleh panggilan sebelumnya ke fungsi DdeCreateDataHandle , menggunakan format data yang sama yang ditentukan dalam parameter wFmt .

[in] cbData

Jenis: DWORD

Panjangnya, dalam byte, dari data yang diacu oleh parameter pData , termasuk NULL yang mengakhiri, jika data adalah string. Nilai -1 menunjukkan bahwa pData adalah handel data yang mengidentifikasi data yang dikirim.

[in] hConv

Jenis: HCONV

Handel ke percakapan tempat transaksi akan dilakukan.

[in, optional] hszItem

Jenis: HSZ

Handel ke item data tempat data ditukar selama transaksi. Handel ini harus dibuat oleh panggilan sebelumnya ke fungsi DdeCreateStringHandle . Parameter ini diabaikan (dan harus diatur ke 0L) jika parameter wTypeXTYP_EXECUTE.

[in] wFmt

Jenis: UINT

Format clipboard standar tempat item data dikirimkan atau diminta.

Jika transaksi yang ditentukan oleh parameter wType tidak meneruskan data atau XTYP_EXECUTE, parameter ini harus nol.

Jika transaksi yang ditentukan oleh parameter wType mereferensikan data DDE yang tidak dijalankan ( XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_REQUEST), nilai wFmt harus berupa format DDE yang telah ditentukan (CF_) yang valid atau format clipboard terdaftar yang valid.

[in] wType

Jenis: UINT

Jenis transaksi. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
XTYP_ADVSTART 0x1030	Memulai perulangan saran. Sejumlah perulangan saran yang berbeda dapat ada dalam percakapan. Aplikasi dapat mengubah jenis perulangan saran dengan menggabungkan jenis transaksi XTYP_ADVSTART dengan satu atau beberapa bendera berikut: XTYPF_NODATA. Menginstruksikan server untuk memberi tahu klien tentang perubahan data apa pun tanpa benar-benar mengirim data. Bendera ini memberi klien opsi untuk mengabaikan pemberitahuan atau meminta data yang diubah dari server. XTYPF_ACKREQ. Menginstruksikan server untuk menunggu hingga klien mengakui bahwa server menerima item data sebelumnya sebelum mengirim item data berikutnya. Bendera ini mencegah server cepat mengirim data lebih cepat daripada yang dapat diproses klien.
XTYP_ADVSTOP 0x8040	Mengakhiri perulangan saran.
XTYP_EXECUTE 0x4050	Memulai transaksi eksekusi.
XTYP_POKE 0x4090	Memulai transaksi poke.
XTYP_REQUEST 0x20B0	Memulai transaksi permintaan.

[in] dwTimeout

Jenis: DWORD

Jumlah waktu maksimum, dalam milidetik, bahwa klien akan menunggu respons dari aplikasi server dalam transaksi sinkron. Parameter ini harus TIMEOUT_ASYNC untuk transaksi asinkron.

[out, optional] pdwResult

Jenis: LPDWORD

Pointer ke variabel yang menerima hasil transaksi. Aplikasi yang tidak memeriksa hasilnya dapat menggunakan NULL untuk nilai ini. Untuk transaksi sinkron, kata berurutan rendah dari variabel ini berisi bendera DDE_ yang berlaku yang dihasilkan dari transaksi. Ini menyediakan dukungan untuk aplikasi yang bergantung pada bit DDE_APPSTATUS . Namun, disarankan agar aplikasi tidak lagi menggunakan bit ini karena mungkin tidak didukung dalam versi Dynamic Data Exchange Management Library (DDEML) di masa mendatang. Untuk transaksi asinkron, variabel ini diisi dengan pengidentifikasi transaksi unik untuk digunakan dengan fungsi DdeAbandonTransaction dan transaksi XTYP_XACT_COMPLETE .

Nilai kembali

Jenis: HDDEDATA

Jika fungsi berhasil, nilai pengembalian adalah handel data yang mengidentifikasi data untuk keberhasilan transaksi sinkron di mana klien mengharapkan data dari server. Nilai yang dikembalikan bukan nol untuk transaksi asinkron yang berhasil dan untuk transaksi sinkron di mana klien tidak mengharapkan data. Nilai yang dikembalikan adalah nol untuk semua transaksi yang gagal.

Fungsi DdeGetLastError dapat digunakan untuk mendapatkan kode kesalahan, yang bisa menjadi salah satu nilai berikut:

Keterangan

Ketika aplikasi telah selesai menggunakan handel data yang dikembalikan oleh DdeClientTransaction, aplikasi harus membebaskan handel dengan memanggil fungsi DdeFreeDataHandle .

Transaksi bisa sinkron atau asinkron. Selama transaksi sinkron, DdeClientTransaction tidak kembali sampai transaksi berhasil diselesaikan atau gagal. Transaksi sinkron menyebabkan klien memasukkan perulangan modal sambil menunggu berbagai peristiwa asinkron. Karena itu, aplikasi klien masih dapat menanggapi input pengguna saat menunggu transaksi sinkron, tetapi aplikasi tidak dapat memulai transaksi sinkron kedua karena aktivitas yang terkait dengan yang pertama. DdeClientTransaction gagal jika ada instans tugas yang sama yang memiliki transaksi sinkron yang sudah berlangsung.

Selama transaksi asinkron, DdeClientTransaction kembali setelah transaksi dimulai, meneruskan pengidentifikasi transaksi untuk referensi. Ketika fungsi panggilan balik DDE server selesai memproses transaksi asinkron, sistem mengirimkan transaksi XTYP_XACT_COMPLETE ke klien. Transaksi ini memberi klien hasil transaksi asinkron yang dimulainya dengan memanggil DdeClientTransaction. Aplikasi klien dapat memilih untuk meninggalkan transaksi asinkron dengan memanggil fungsi DdeAbandonTransaction .

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	ddeml.h (termasuk Windows.h)
Pustaka	User32.lib
DLL	User32.dll