Función DdeClientTransaction (ddeml.h)

Artículo
08/23/2023

Inicia una transacción de datos entre un cliente y un servidor. Solo una aplicación cliente de Intercambio de datos dinámicos (DDE) puede llamar a esta función y la aplicación solo puede usarla después de establecer una conversación con el servidor.

Sintaxis

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

Parámetros

[in, optional] pData

Tipo: LPBYTE

El principio de los datos que el cliente debe pasar al servidor.

Opcionalmente, una aplicación puede especificar el identificador de datos (HDDEDATA) para pasar al servidor y, en ese caso, el parámetro cbData debe establecerse en -1. Este parámetro solo es necesario si el parámetro wType es XTYP_EXECUTE o XTYP_POKE. De lo contrario, este parámetro debe ser NULL.

Para el uso opcional de este parámetro, XTYP_POKE transacciones en las que pData es un identificador de datos, el identificador debe haber sido creado por una llamada anterior a la función DdeCreateDataHandle , utilizando el mismo formato de datos especificado en el parámetro wFmt .

[in] cbData

Tipo: DWORD

Longitud, en bytes, de los datos a los que apunta el parámetro pData , incluido el valor NULL de terminación, si los datos son una cadena. Un valor de -1 indica que pData es un identificador de datos que identifica los datos que se envían.

[in] hConv

Tipo: HCONV

Identificador de la conversación en la que se va a realizar la transacción.

[in, optional] hszItem

Tipo: HSZ

Identificador del elemento de datos para el que se intercambian datos durante la transacción. Este identificador debe haber sido creado por una llamada anterior a la función DdeCreateStringHandle . Este parámetro se omite (y debe establecerse en 0L) si el parámetro wType es XTYP_EXECUTE.

[in] wFmt

Tipo: UINT

Formato estándar del Portapapeles en el que se envía o solicita el elemento de datos.

Si la transacción especificada por el parámetro wType no pasa datos o es XTYP_EXECUTE, este parámetro debe ser cero.

Si la transacción especificada por el parámetro wType hace referencia a datos DDE no ejecutados ( XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_REQUEST), el valor wFmt debe ser un formato DDE predefinido (CF_) válido o un formato de Portapapeles registrado válido.

[in] wType

Tipo: UINT

El tipo de transacción. Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
XTYP_ADVSTART 0x1030	Comienza un bucle de aviso. Cualquier número de bucles de aviso distintos puede existir dentro de una conversación. Una aplicación puede modificar el tipo de bucle de aviso combinando el tipo de transacción XTYP_ADVSTART con una o varias de las marcas siguientes: XTYPF_NODATA. Indica al servidor que notifique al cliente los cambios de datos sin enviar realmente los datos. Esta marca proporciona al cliente la opción de omitir la notificación o solicitar los datos modificados del servidor. XTYPF_ACKREQ. Indica al servidor que espere hasta que el cliente confirme que recibió el elemento de datos anterior antes de enviar el siguiente elemento de datos. Esta marca impide que un servidor rápido envíe datos más rápido de lo que el cliente puede procesar.
XTYP_ADVSTOP 0x8040	Finaliza un bucle de aviso.
XTYP_EXECUTE 0x4050	Inicia una transacción de ejecución.
XTYP_POKE 0x4090	Comienza una transacción de poke.
XTYP_REQUEST 0x20B0	Inicia una transacción de solicitud.

[in] dwTimeout

Tipo: DWORD

Cantidad máxima de tiempo, en milisegundos, que el cliente esperará una respuesta de la aplicación de servidor en una transacción sincrónica. Este parámetro debe ser TIMEOUT_ASYNC para transacciones asincrónicas.

[out, optional] pdwResult

Tipo: LPDWORD

Puntero a una variable que recibe el resultado de la transacción. Una aplicación que no comprueba el resultado puede usar NULL para este valor. Para las transacciones sincrónicas, la palabra de orden bajo de esta variable contiene las marcas de DDE_ aplicables resultantes de la transacción. Esto proporciona compatibilidad con las aplicaciones que dependen de DDE_APPSTATUS bits. Sin embargo, se recomienda que las aplicaciones ya no usen estos bits porque es posible que no se admitan en versiones futuras de la Biblioteca de administración dinámica de Exchange de datos (DDEML). En el caso de las transacciones asincrónicas, esta variable se rellena con un identificador de transacción único para su uso con la función DdeAbandonTransaction y la transacción XTYP_XACT_COMPLETE .

Valor devuelto

Tipo: HDDEDATA

Si la función se ejecuta correctamente, el valor devuelto es un identificador de datos que identifica los datos para transacciones sincrónicas correctas en las que el cliente espera datos del servidor. El valor devuelto es distinto de cero para las transacciones asincrónicas correctas y para las transacciones sincrónicas en las que el cliente no espera datos. El valor devuelto es cero para todas las transacciones incorrectas.

La función DdeGetLastError se puede usar para obtener el código de error, que puede ser uno de los siguientes valores:

Comentarios

Cuando una aplicación ha terminado de usar el identificador de datos devuelto por DdeClientTransaction, la aplicación debe liberar el identificador llamando a la función DdeFreeDataHandle .

Las transacciones pueden ser sincrónicas o asincrónicas. Durante una transacción sincrónica, DdeClientTransaction no devuelve hasta que la transacción se completa correctamente o se produce un error. Las transacciones sincrónicas hacen que un cliente escriba un bucle modal mientras espera varios eventos asincrónicos. Por este motivo, una aplicación cliente todavía puede responder a la entrada del usuario mientras espera una transacción sincrónica, pero la aplicación no puede iniciar una segunda transacción sincrónica debido a la actividad asociada con la primera. Se produce un error en DdeClientTransaction si alguna instancia de la misma tarea tiene una transacción sincrónica que ya está en curso.

Durante una transacción asincrónica, DdeClientTransaction devuelve una vez iniciada la transacción, pasando un identificador de transacción como referencia. Cuando la función de devolución de llamada DDE del servidor finaliza el procesamiento de una transacción asincrónica, el sistema envía una transacción XTYP_XACT_COMPLETE al cliente. Esta transacción proporciona al cliente los resultados de la transacción asincrónica que inició llamando a DdeClientTransaction. Una aplicación cliente puede optar por abandonar una transacción asincrónica llamando a la función DdeAbandonTransaction .

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ddeml.h (incluya Windows.h)
Library	User32.lib
Archivo DLL	User32.dll