Função DdeClientTransaction (ddeml.h)
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_ADVSTOPXTYP_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 |
|---|---|
|
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:
|
|
Encerra um loop de consultoria. |
|
Inicia uma transação de execução. |
|
Inicia uma transação de cutucada. |
|
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 |
Confira também
Conceitual
Biblioteca de Gerenciamento de Troca dinâmica de dados
Referência