Функция DdeClientTransaction (ddeml.h)

Статья
08/23/2023

Начинает транзакцию данных между клиентом и сервером. Только клиентское приложение динамического обмена данными (DDE) может вызывать эту функцию, и приложение может использовать ее только после установления диалога с сервером.

Синтаксис

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
);

Параметры

[in, optional] pData

Тип: LPBYTE

Начало данных, которые клиент должен передать серверу.

При необходимости приложение может указать дескриптор данных (HDDEDATA) для передачи на сервер. В этом случае параметру cbData следует задать значение -1. Этот параметр является обязательным, только если параметр wType является XTYP_EXECUTE или XTYP_POKE. В противном случае этот параметр должен иметь значение NULL.

Для необязательного использования этого параметра XTYP_POKE транзакций , где pData является дескриптором данных, дескриптор должен быть создан предыдущим вызовом функции DdeCreateDataHandle , используя тот же формат данных, что и в параметре wFmt .

[in] cbData

Тип: DWORD

Длина (в байтах) данных, на которые указывает параметр pData , включая завершающее значение NULL, если данные являются строкой. Значение -1 указывает, что pData — это дескриптор данных, который идентифицирует отправляемые данные.

[in] hConv

Тип: HCONV

Дескриптор диалога, в котором будет выполняться транзакция.

[in, optional] hszItem

Тип: HSZ

Дескриптор элемента данных, для которого происходит обмен данными во время транзакции. Этот дескриптор должен быть создан предыдущим вызовом функции DdeCreateStringHandle . Этот параметр игнорируется (и должен иметь значение 0L), если параметр wTypeXTYP_EXECUTE.

[in] wFmt

Тип: UINT

Стандартный формат буфера обмена, в котором отправляется или запрашивается элемент данных.

Если транзакция, указанная параметром wType , не передает данные или XTYP_EXECUTE, этот параметр должен быть равен нулю.

Если транзакция, указанная параметром wType, ссылается на неисполняемые данные DDE (XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP , XTYP_REQUEST), то значение wFmt должно быть либо допустимым предопределенным (CF_) форматом DDE, либо допустимым форматом зарегистрированного буфера обмена.

[in] wType

Тип: UINT

Тип транзакции. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
XTYP_ADVSTART 0x1030	Начинает цикл рекомендаций. В беседе может существовать любое количество отдельных циклов рекомендаций. Приложение может изменить тип цикла рекомендаций, объединив XTYP_ADVSTART тип транзакции с одним или несколькими из следующих флагов: XTYPF_NODATA. Указывает серверу уведомлять клиента о любых изменениях данных без фактической отправки данных. Этот флаг дает клиенту возможность игнорировать уведомление или запрашивать измененные данные с сервера. XTYPF_ACKREQ. Указывает серверу подождать, пока клиент не подтвердит получение предыдущего элемента данных перед отправкой следующего элемента данных. Этот флаг не позволяет быстрому серверу отправлять данные быстрее, чем клиент может их обработать.
XTYP_ADVSTOP 0x8040	Завершает цикл рекомендаций.
XTYP_EXECUTE 0x4050	Начинает выполнение транзакции.
XTYP_POKE 0x4090	Начинает транзакцию ткнуть.
XTYP_REQUEST 0x20B0	Начинает транзакцию запроса.

[in] dwTimeout

Тип: DWORD

Максимальное время (в миллисекундах) ожидания ответа от серверного приложения в синхронной транзакции. Этот параметр должен быть TIMEOUT_ASYNC для асинхронных транзакций.

[out, optional] pdwResult

Тип: LPDWORD

Указатель на переменную, которая получает результат транзакции. Приложение, которое не проверка результат, может использовать значение NULL для этого значения. Для синхронных транзакций слово нижнего порядка этой переменной содержит все применимые флаги DDE_, полученные в результате транзакции. Это обеспечивает поддержку приложений, зависящих от DDE_APPSTATUS битов. Однако рекомендуется, чтобы приложения больше не использовали эти биты, так как они могут не поддерживаться в будущих версиях библиотеки управления динамическим обменом данными (DDEML). Для асинхронных транзакций эта переменная заполняется уникальным идентификатором транзакции для использования с функцией DdeAbandonTransaction и транзакцией XTYP_XACT_COMPLETE .

Возвращаемое значение

Тип: HDDEDATA

Если функция выполняется успешно, возвращаемое значение представляет собой дескриптор данных, который идентифицирует данные для успешных синхронных транзакций, в которых клиент ожидает данные от сервера. Возвращаемое значение не равно нулю для успешных асинхронных транзакций и синхронных транзакций, в которых клиент не ожидает данных. Возвращаемое значение равно нулю для всех неудачных транзакций.

Функция DdeGetLastError может использоваться для получения кода ошибки, который может иметь одно из следующих значений:

Транзакции могут быть синхронными или асинхронными. Во время синхронной транзакции DdeClientTransaction не возвращается, пока транзакция не завершится успешно или не завершится сбоем. Синхронные транзакции приводят к тому, что клиент переходит в модальный цикл при ожидании различных асинхронных событий. Из-за этого клиентское приложение по-прежнему может отвечать на введенные пользователем данные во время ожидания синхронной транзакции, но приложение не может начать вторую синхронную транзакцию из-за действия, связанного с первой. DdeClientTransaction завершается сбоем, если любой экземпляр той же задачи уже выполняет синхронную транзакцию.

Во время асинхронной транзакции DdeClientTransaction возвращается после начала транзакции, передавая идентификатор транзакции для ссылки. Когда функция обратного вызова DDE сервера завершает обработку асинхронной транзакции, система отправляет XTYP_XACT_COMPLETE транзакцию клиенту. Эта транзакция предоставляет клиенту результаты асинхронной транзакции, инициированной вызовом DdeClientTransaction. Клиентское приложение может отказаться от асинхронной транзакции, вызвав функцию DdeAbandonTransaction .

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	ddeml.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll