Funzione DdeClientTransaction (ddeml.h)

Articolo
08/23/2023

Avvia una transazione di dati tra un client e un server. Solo un'applicazione client DDE (Dynamic Data Exchange) può chiamare questa funzione e l'applicazione può usarla solo dopo aver stabilito una conversazione con il server.

Sintassi

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

Parametri

[in, optional] pData

Tipo: LPBYTE

L'inizio dei dati che il client deve passare al server.

Facoltativamente, un'applicazione può specificare l'handle dati (HDDEDATA) da passare al server e in tal caso il parametro cbData deve essere impostato su -1. Questo parametro è obbligatorio solo se il parametro wType è XTYP_EXECUTE o XTYP_POKE. In caso contrario, questo parametro deve essere NULL.

Per l'utilizzo facoltativo di questo parametro, XTYP_POKE transazioni in cui pData è un handle dati, l'handle deve essere stato creato da una chiamata precedente alla funzione DdeCreateDataHandle , utilizzando lo stesso formato di dati specificato nel parametro wFmt .

[in] cbData

Tipo: DWORD

Lunghezza, in byte, dei dati a cui fa riferimento il parametro pData , inclusa la terminazione NULL, se i dati sono una stringa. Un valore di -1 indica che pData è un handle dati che identifica i dati inviati.

[in] hConv

Tipo: HCONV

Handle alla conversazione in cui si svolge la transazione.

[in, optional] hszItem

Tipo: HSZ

Handle per l'elemento di dati per il quale i dati vengono scambiati durante la transazione. Questo handle deve essere stato creato da una chiamata precedente alla funzione DdeCreateStringHandle . Questo parametro viene ignorato (e deve essere impostato su 0L) se il parametro wType è XTYP_EXECUTE.

[in] wFmt

Tipo: UINT

Formato standard degli Appunti in cui l'elemento di dati viene inviato o richiesto.

Se la transazione specificata dal parametro wType non passa dati o è XTYP_EXECUTE, questo parametro deve essere zero.

Se la transazione specificata dal parametro wType fa riferimento ai dati DDE non eseguiti ( XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP ,XTYP_REQUEST), il valore wFmt deve essere un formato DDE (CF_) valido o un formato di Appunti registrato valido.

[in] wType

Tipo: UINT

Tipo di transazione. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
XTYP_ADVSTART 0x1030	Inizia un ciclo di consigli. Qualsiasi numero di cicli di consigli distinti può esistere all'interno di una conversazione. Un'applicazione può modificare il tipo di ciclo di consulenza combinando il tipo di transazione XTYP_ADVSTART con uno o più flag seguenti: XTYPF_NODATA. Indica al server di inviare una notifica al client di eventuali modifiche ai dati senza inviare effettivamente i dati. Questo flag consente al client di ignorare la notifica o richiedere i dati modificati dal server. XTYPF_ACKREQ. Indica al server di attendere fino a quando il client riconosce che ha ricevuto l'elemento dati precedente prima di inviare l'elemento dati successivo. Questo flag impedisce a un server veloce di inviare dati più velocemente che il client possa elaborarlo.
XTYP_ADVSTOP 0x8040	Termina un ciclo di consigli.
XTYP_EXECUTE 0x4050	Avvia una transazione di esecuzione.
XTYP_POKE 0x4090	Avvia una transazione di poke.
XTYP_REQUEST 0x20B0	Avvia una transazione di richiesta.

[in] dwTimeout

Tipo: DWORD

Tempo massimo, in millisecondi, che il client attenderà una risposta dall'applicazione server in una transazione sincrona. Questo parametro deve essere TIMEOUT_ASYNC per le transazioni asincrone.

[out, optional] pdwResult

Tipo: LPDWORD

Puntatore a una variabile che riceve il risultato della transazione. Un'applicazione che non controlla il risultato può usare NULL per questo valore. Per le transazioni sincrone, la parola a basso ordine di questa variabile contiene eventuali flag di DDE_ applicabili risultanti dalla transazione. In questo modo viene fornito il supporto per le applicazioni dipendenti dai bit di DDE_APPSTATUS . È tuttavia consigliabile che le applicazioni non usino più questi bit perché potrebbero non essere supportate nelle versioni future della libreria DDEML ( Dynamic Data Exchange Management Library ). Per le transazioni asincrone, questa variabile viene riempita con un identificatore di transazione univoco da usare con la funzione DdeAbandonTransaction e la transazione XTYP_XACT_COMPLETE .

Valore restituito

Tipo: HDDEDATA

Se la funzione ha esito positivo, il valore restituito è un handle di dati che identifica i dati per le transazioni sincrone in cui il client prevede dati dal server. Il valore restituito è diverso da zero per le transazioni asincrone riuscite e per le transazioni sincrone in cui il client non prevede dati. Il valore restituito è zero per tutte le transazioni non riuscite.

La funzione DdeGetLastError può essere usata per ottenere il codice di errore, che può essere uno dei valori seguenti:

Commenti

Al termine dell'uso dell'handle dati restituito da DdeClientTransaction, l'applicazione deve liberare l'handle chiamando la funzione DdeFreeDataHandle .

Le transazioni possono essere sincrone o asincrone. Durante una transazione sincrona, DdeClientTransaction non restituisce finché la transazione non viene completata correttamente o ha esito negativo. Le transazioni sincrone causano l'immissione di un ciclo modale durante l'attesa di vari eventi asincroni. A causa di questo, un'applicazione client può comunque rispondere all'input utente durante l'attesa in una transazione sincrona, ma l'applicazione non può iniziare una seconda transazione sincrona a causa dell'attività associata al primo. DdeClientTransaction ha esito negativo se qualsiasi istanza della stessa attività ha una transazione sincrona già in corso.

Durante una transazione asincrona, DdeClientTransaction restituisce dopo l'avvio della transazione, passando un identificatore di transazione per riferimento. Al termine dell'elaborazione di una transazione asincrona, il sistema invia una transazione XTYP_XACT_COMPLETE al client. Questa transazione fornisce al client i risultati della transazione asincrona avviata chiamando DdeClientTransaction. Un'applicazione client può scegliere di abbandonare una transazione asincrona chiamando la funzione DdeAbandonTransaction .

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ddeml.h (includere Windows.h)
Libreria	User32.lib
DLL	User32.dll