Função DdeClientTransaction (ddeml.h)

Artigo
02/26/2024

Inicia uma transação de dados entre um cliente e um servidor. Somente um aplicativo cliente DDE (Troca Dinâmica de Dados) pode chamar essa função, e o aplicativo só pode usá-la depois de estabelecer uma conversa com o servidor.

Sintaxe

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

O início dos dados que o cliente deve passar para o servidor.

Opcionalmente, um aplicativo pode especificar o identificador de dados (HDDEDATA) a ser passado para o servidor e, nesse caso, o parâmetro cbData deve ser definido como -1. Esse parâmetro será necessário somente se o parâmetro wType for XTYP_EXECUTE ou XTYP_POKE. Caso contrário, esse parâmetro deverá ser NULL.

Para o uso opcional desse parâmetro, XTYP_POKE transações em que pData é um identificador de dados, o identificador deve ter sido criado por uma chamada anterior para a função DdeCreateDataHandle , empregando o mesmo formato de dados especificado no parâmetro wFmt .

[in] cbData

Tipo: DWORD

O comprimento, em bytes, dos dados apontados pelo parâmetro pData , incluindo o NULL de terminação, se os dados forem uma cadeia de caracteres. Um valor de -1 indica que pData é um identificador de dados que identifica os dados que estão sendo enviados.

[in] hConv

Tipo: HCONV

Um identificador para a conversa na qual a transação deve ocorrer.

[in, optional] hszItem

Tipo: HSZ

Um identificador para o item de dados para o qual os dados estão sendo trocados durante a transação. Esse identificador deve ter sido criado por uma chamada anterior para a função DdeCreateStringHandle . Esse parâmetro será ignorado (e deverá ser definido como 0L) se o parâmetro wType for XTYP_EXECUTE.

[in] wFmt

Tipo: UINT

O formato da área de transferência padrão no qual o item de dados está sendo enviado ou solicitado.

Se a transação especificada pelo parâmetro wType não passar dados ou for XTYP_EXECUTE, esse parâmetro deverá ser zero.

Se a transação especificada pelo parâmetro wType fizer referência a dados DDE não executados ( XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP XTYP_REQUEST), o valor wFmt deverá ser um formato DDE predefinido (CF_) válido ou um formato de área de transferência registrado válido.

[in] wType

Tipo: UINT

O tipo de transação. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
XTYP_ADVSTART 0x1030	Inicia um loop de consultoria. Qualquer número de loops de aconselhamento distintos pode existir dentro de uma conversa. Um aplicativo pode alterar o tipo de loop de consultoria combinando o tipo de transação XTYP_ADVSTART com um ou mais dos seguintes sinalizadores: XTYPF_NODATA. Instrui o servidor a notificar o cliente sobre quaisquer alterações de dados sem realmente enviar os dados. Esse sinalizador dá ao cliente a opção de ignorar a notificação ou solicitar os dados alterados do servidor. XTYPF_ACKREQ. Instrui o servidor a aguardar até que o cliente reconheça que recebeu o item de dados anterior antes de enviar o próximo item de dados. Esse sinalizador impede que um servidor rápido envie dados mais rapidamente do que o cliente pode processá-los.
XTYP_ADVSTOP 0x8040	Encerra um loop de consultoria.
XTYP_EXECUTE 0x4050	Inicia uma transação de execução.
XTYP_POKE 0x4090	Inicia uma transação de cutucada.
XTYP_REQUEST 0x20B0	Inicia uma transação de solicitação.

[in] dwTimeout

Tipo: DWORD

A quantidade máxima de tempo, em milissegundos, que o cliente aguardará por uma resposta do aplicativo de servidor em uma transação síncrona. Esse parâmetro deve ser TIMEOUT_ASYNC para transações assíncronas.

[out, optional] pdwResult

Tipo: LPDWORD

Um ponteiro para uma variável que recebe o resultado da transação. Um aplicativo que não marcar o resultado pode usar NULL para esse valor. Para transações síncronas, a palavra de baixa ordem dessa variável contém quaisquer sinalizadores de DDE_ aplicáveis resultantes da transação. Isso fornece suporte para aplicativos dependentes de DDE_APPSTATUS bits. No entanto, é recomendável que os aplicativos não usem mais esses bits porque podem não ter suporte em versões futuras da DDEML ( Dynamic Data Exchange Management Library ). Para transações assíncronas, essa variável é preenchida com um identificador de transação exclusivo para uso com a função DdeAbandonTransaction e a transação XTYP_XACT_COMPLETE .

Retornar valor

Tipo: HDDEDATA

Se a função for bem-sucedida, o valor retornado será um identificador de dados que identifica os dados para transações síncronas bem-sucedidas nas quais o cliente espera dados do servidor. O valor retornado é diferente de zero para transações assíncronas bem-sucedidas e para transações síncronas nas quais o cliente não espera dados. O valor retornado é zero para todas as transações malsucedidas.

A função DdeGetLastError pode ser usada para obter o código de erro, que pode ser um dos seguintes valores:

Comentários

Quando um aplicativo terminar de usar o identificador de dados retornado por DdeClientTransaction, o aplicativo deverá liberar o identificador chamando a função DdeFreeDataHandle .

As transações podem ser síncronas ou assíncronas. Durante uma transação síncrona, DdeClientTransaction não retorna até que a transação seja concluída com êxito ou falhe. Transações síncronas fazem com que um cliente insira um loop modal enquanto aguarda vários eventos assíncronos. Por isso, um aplicativo cliente ainda pode responder à entrada do usuário enquanto aguarda uma transação síncrona, mas o aplicativo não pode iniciar uma segunda transação síncrona devido à atividade associada à primeira. DdeClientTransaction falhará se qualquer instância da mesma tarefa tiver uma transação síncrona já em andamento.

Durante uma transação assíncrona, DdeClientTransaction retorna após o início da transação, passando um identificador de transação para referência. Quando a função de retorno de chamada DDE do servidor termina de processar uma transação assíncrona, o sistema envia uma transação XTYP_XACT_COMPLETE ao cliente. Essa transação fornece ao cliente os resultados da transação assíncrona iniciada chamando DdeClientTransaction. Um aplicativo cliente pode optar por abandonar uma transação assíncrona chamando a função DdeAbandonTransaction .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ddeml.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll