Fonction DdeClientTransaction (ddeml.h)

Article
02/29/2024

Commence une transaction de données entre un client et un serveur. Seule une application cliente DDE (Dynamic Data Exchange) peut appeler cette fonction, et l’application ne peut l’utiliser qu’après avoir établi une conversation avec le serveur.

Syntaxe

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

Paramètres

[in, optional] pData

Type : LPBYTE

Début des données que le client doit transmettre au serveur.

Si vous le souhaitez, une application peut spécifier le handle de données (HDDEDATA) à passer au serveur et, dans ce cas, le paramètre cbData doit être défini sur -1. Ce paramètre est requis uniquement si le paramètre wType est XTYP_EXECUTE ou XTYP_POKE. Sinon, ce paramètre doit être NULL.

Pour l’utilisation facultative de ce paramètre, XTYP_POKE transactions où pData est un handle de données, le handle doit avoir été créé par un appel précédent à la fonction DdeCreateDataHandle , en utilisant le même format de données spécifié dans le paramètre wFmt .

[in] cbData

Type : DWORD

Longueur, en octets, des données pointées par le paramètre pData , y compris la valeur NULL de fin, si les données sont une chaîne. La valeur -1 indique que pData est un handle de données qui identifie les données envoyées.

[in] hConv

Type : HCONV

Handle de la conversation dans laquelle la transaction doit avoir lieu.

[in, optional] hszItem

Type : HSZ

Handle de l’élément de données pour lequel les données sont échangées pendant la transaction. Ce handle doit avoir été créé par un appel précédent à la fonction DdeCreateStringHandle . Ce paramètre est ignoré (et doit être défini sur 0L) si le paramètre wType est XTYP_EXECUTE.

[in] wFmt

Type : UINT

Format du Presse-papiers standard dans lequel l’élément de données est soumis ou demandé.

Si la transaction spécifiée par le paramètre wType ne transmet pas de données ou est XTYP_EXECUTE, ce paramètre doit être égal à zéro.

Si la transaction spécifiée par le paramètre wType fait référence à des données DDE non exécutées (XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_REQUEST), la valeur wFmt doit être un format DDE (CF_) prédéfini valide ou un format de Presse-papiers inscrit valide.

[in] wType

Type : UINT

Type de transaction. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
XTYP_ADVSTART 0x1030	Commence une boucle de conseil. Un nombre quelconque de boucles de conseil distinctes peuvent exister dans une conversation. Une application peut modifier le type de boucle de conseil en combinant le type de transaction XTYP_ADVSTART avec un ou plusieurs des indicateurs suivants : XTYPF_NODATA. Indique au serveur d’informer le client de toute modification de données sans envoyer réellement les données. Cet indicateur donne au client la possibilité d’ignorer la notification ou de demander les données modifiées du serveur. XTYPF_ACKREQ. Indique au serveur d’attendre que le client reconnaisse qu’il a reçu l’élément de données précédent avant d’envoyer l’élément de données suivant. Cet indicateur empêche un serveur rapide d’envoyer des données plus rapidement que le client ne peut les traiter.
XTYP_ADVSTOP 0x8040	Termine une boucle de conseil.
XTYP_EXECUTE 0x4050	Commence une transaction d’exécution.
XTYP_POKE 0x4090	Commence une transaction poke.
XTYP_REQUEST 0x20B0	Commence une transaction de demande.

[in] dwTimeout

Type : DWORD

Durée maximale, en millisecondes, pendant laquelle le client attend une réponse de l’application serveur dans une transaction synchrone. Ce paramètre doit être TIMEOUT_ASYNC pour les transactions asynchrones.

[out, optional] pdwResult

Type : LPDWORD

Pointeur vers une variable qui reçoit le résultat de la transaction. Une application qui ne case activée pas le résultat peut utiliser NULL pour cette valeur. Pour les transactions synchrones, le mot de bas ordre de cette variable contient tous les indicateurs de DDE_ applicables résultant de la transaction. Cela permet de prendre en charge les applications dépendantes de DDE_APPSTATUS bits. Toutefois, il est recommandé que les applications n’utilisent plus ces bits, car ils risquent de ne pas être pris en charge dans les versions futures de la bibliothèque de gestion DDEML (Dynamic Data Exchange Management Library ). Pour les transactions asynchrones, cette variable est remplie avec un identificateur de transaction unique à utiliser avec la fonction DdeAbandonTransaction et la transaction XTYP_XACT_COMPLETE .

Valeur retournée

Type : HDDEDATA

Si la fonction réussit, la valeur de retour est un handle de données qui identifie les données pour les transactions synchrones réussies dans lesquelles le client attend des données du serveur. La valeur de retour est différente de zéro pour les transactions asynchrones réussies et pour les transactions synchrones dans lesquelles le client n’attend pas de données. La valeur de retour est zéro pour toutes les transactions ayant échoué.

La fonction DdeGetLastError peut être utilisée pour obtenir le code d’erreur, qui peut être l’une des valeurs suivantes :

Remarques

Lorsqu’une application a fini d’utiliser le handle de données retourné par DdeClientTransaction, l’application doit libérer le handle en appelant la fonction DdeFreeDataHandle .

Les transactions peuvent être synchrones ou asynchrones. Pendant une transaction synchrone, DdeClientTransaction ne retourne pas tant que la transaction n’est pas terminée ou échoue. Les transactions synchrones entraînent l’entrée d’un client dans une boucle modale en attendant différents événements asynchrones. Pour cette raison, une application cliente peut toujours répondre à l’entrée utilisateur pendant l’attente d’une transaction synchrone, mais l’application ne peut pas commencer une deuxième transaction synchrone en raison de l’activité associée à la première. DdeClientTransaction échoue si une instance de la même tâche a déjà une transaction synchrone en cours.

Pendant une transaction asynchrone, DdeClientTransaction retourne une fois la transaction commencée, en passant un identificateur de transaction pour référence. Lorsque la fonction de rappel DDE du serveur termine le traitement d’une transaction asynchrone, le système envoie une transaction XTYP_XACT_COMPLETE au client. Cette transaction fournit au client les résultats de la transaction asynchrone qu’il a lancée en appelant DdeClientTransaction. Une application cliente peut choisir d’abandonner une transaction asynchrone en appelant la fonction DdeAbandonTransaction .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	ddeml.h (inclure Windows.h)
Bibliothèque	User32.lib
DLL	User32.dll