/*
* The contents of this file is dual-licensed under 2
* alternative Open Source/Free licenses: LGPL 2.1 or later and
* Apache License 2.0. (starting with JNA version 4.0.0).
*
* You can freely decide which license you want to apply to
* the project.
*
* You may obtain a copy of the LGPL License at:
*
* http://www.gnu.org/licenses/licenses.html
*
* A copy is also included in the downloadable source code package
* containing JNA, in file "LGPL2.1".
*
* You may obtain a copy of the Apache License at:
*
* http://www.apache.org/licenses/
*
* A copy is also included in the downloadable source code package
* containing JNA, in file "AL2.0".
*/
package com.sun.jna.platform.win32;
import com.sun.jna.Memory;
import com.sun.jna.Pointer;
import com.sun.jna.platform.win32.BaseTSD.DWORD_PTR;
import com.sun.jna.platform.win32.BaseTSD.ULONG_PTR;
import com.sun.jna.platform.win32.Ddeml.CONVCONTEXT;
import com.sun.jna.platform.win32.Ddeml.CONVINFO;
import com.sun.jna.platform.win32.Ddeml.HCONV;
import com.sun.jna.platform.win32.Ddeml.HCONVLIST;
import com.sun.jna.platform.win32.Ddeml.HDDEDATA;
import com.sun.jna.platform.win32.Ddeml.HSZ;
import com.sun.jna.platform.win32.Ddeml.HSZPAIR;
import com.sun.jna.platform.win32.User32Util.MessageLoopThread;
import com.sun.jna.platform.win32.User32Util.MessageLoopThread.Handler;
import com.sun.jna.win32.W32APIOptions;
import java.io.Closeable;
import java.io.IOException;
import java.lang.reflect.Field;
import java.lang.reflect.InvocationHandler;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.logging.Level;
import java.util.logging.Logger;
/**
* DdemlUtil defines helper classes, that help with manageing DDE communications.
*/
public abstract class DdemlUtil {
/**
* StandaloneDdeClient is a convenience class, that wraps a DdeClient and
* a {@link User32Util.MessageLoopThread}. The DdeClient needs a running
* windows message loop, which is supplied by the MessageLoopThread.
*/
public static class StandaloneDdeClient implements IDdeClient, Closeable {
private final MessageLoopThread messageLoop = new MessageLoopThread();
private final IDdeClient ddeClient;
private final IDdeClient clientDelegate;
public StandaloneDdeClient() {
ddeClient = new DdeClient();
IDdeClient messageLoopHandler = (IDdeClient) Proxy.newProxyInstance(StandaloneDdeClient.class.getClassLoader(),
new Class[]{IDdeClient.class},
messageLoop.new Handler(ddeClient));
clientDelegate = (IDdeClient) Proxy.newProxyInstance(StandaloneDdeClient.class.getClassLoader(),
new Class[]{IDdeClient.class},
new MessageLoopWrapper(messageLoop, messageLoopHandler));
messageLoop.setDaemon(true);
messageLoop.start();
}
public Integer getInstanceIdentitifier() {
return ddeClient.getInstanceIdentitifier();
}
public void initialize(int afCmd) throws DdemlException {
clientDelegate.initialize(afCmd);
}
public Ddeml.HSZ createStringHandle(String value) throws DdemlException {
return clientDelegate.createStringHandle(value);
}
public void nameService(Ddeml.HSZ name, int afCmd) throws DdemlException {
clientDelegate.nameService(name, afCmd);
}
public int getLastError() {
return clientDelegate.getLastError();
}
public IDdeConnection connect(Ddeml.HSZ service, Ddeml.HSZ topic, Ddeml.CONVCONTEXT convcontext) {
return clientDelegate.connect(service, topic, convcontext);
}
public String queryString(Ddeml.HSZ value) throws DdemlException {
return clientDelegate.queryString(value);
}
@Override
public Ddeml.HDDEDATA createDataHandle(Pointer pSrc, int cb, int cbOff, Ddeml.HSZ hszItem, int wFmt, int afCmd) {
return clientDelegate.createDataHandle(pSrc, cb, cbOff, hszItem, wFmt, afCmd);
}
@Override
public void freeDataHandle(Ddeml.HDDEDATA hData) {
clientDelegate.freeDataHandle(hData);
}
@Override
public Ddeml.HDDEDATA addData(Ddeml.HDDEDATA hData, Pointer pSrc, int cb, int cbOff) {
return clientDelegate.addData(hData, pSrc, cb, cbOff);
}
@Override
public int getData(Ddeml.HDDEDATA hData, Pointer pDst, int cbMax, int cbOff) {
return clientDelegate.getData(hData, pDst, cbMax, cbOff);
}
@Override
public Pointer accessData(Ddeml.HDDEDATA hData, WinDef.DWORDByReference pcbDataSize) {
return clientDelegate.accessData(hData, pcbDataSize);
}
@Override
public void unaccessData(Ddeml.HDDEDATA hData) {
clientDelegate.unaccessData(hData);
}
@Override
public void postAdvise(Ddeml.HSZ hszTopic, Ddeml.HSZ hszItem) {
clientDelegate.postAdvise(hszTopic, hszItem);
}
public void close() throws IOException {
clientDelegate.uninitialize();
messageLoop.exit();
}
@Override
public boolean freeStringHandle(Ddeml.HSZ value) {
return clientDelegate.freeStringHandle(value);
}
@Override
public boolean keepStringHandle(Ddeml.HSZ value) {
return clientDelegate.keepStringHandle(value);
}
@Override
public void abandonTransactions() {
clientDelegate.abandonTransactions();
}
@Override
public IDdeConnectionList connectList(Ddeml.HSZ service, Ddeml.HSZ topic, IDdeConnectionList existingList, Ddeml.CONVCONTEXT ctx) {
return clientDelegate.connectList(service, topic, existingList, ctx);
}
@Override
public boolean enableCallback(int wCmd) {
return clientDelegate.enableCallback(wCmd);
}
@Override
public IDdeConnection wrap(HCONV conv) {
return clientDelegate.wrap(conv);
}
@Override
public IDdeConnection connect(String service, String topic, Ddeml.CONVCONTEXT convcontext) {
return clientDelegate.connect(service, topic, convcontext);
}
@Override
public boolean uninitialize() {
return clientDelegate.uninitialize();
}
@Override
public void postAdvise(String hszTopic, String hszItem) {
clientDelegate.postAdvise(hszTopic, hszItem);
}
@Override
public IDdeConnectionList connectList(String service, String topic, IDdeConnectionList existingList, Ddeml.CONVCONTEXT ctx) {
return clientDelegate.connectList(service, topic, existingList, ctx);
}
@Override
public void nameService(String name, int afCmd) throws DdemlException {
clientDelegate.nameService(name, afCmd);
}
@Override
public void registerAdvstartHandler(AdvstartHandler handler) {
clientDelegate.registerAdvstartHandler(handler);
}
@Override
public void unregisterAdvstartHandler(AdvstartHandler handler) {
clientDelegate.unregisterAdvstartHandler(handler);
}
@Override
public void registerAdvstopHandler(AdvstopHandler handler) {
clientDelegate.registerAdvstopHandler(handler);
}
@Override
public void unregisterAdvstopHandler(AdvstopHandler handler) {
clientDelegate.unregisterAdvstopHandler(handler);
}
@Override
public void registerConnectHandler(ConnectHandler handler) {
clientDelegate.registerConnectHandler(handler);
}
@Override
public void unregisterConnectHandler(ConnectHandler handler) {
clientDelegate.unregisterConnectHandler(handler);
}
@Override
public void registerAdvReqHandler(AdvreqHandler handler) {
clientDelegate.registerAdvReqHandler(handler);
}
@Override
public void unregisterAdvReqHandler(AdvreqHandler handler) {
clientDelegate.unregisterAdvReqHandler(handler);
}
@Override
public void registerRequestHandler(RequestHandler handler) {
clientDelegate.registerRequestHandler(handler);
}
@Override
public void unregisterRequestHandler(RequestHandler handler) {
clientDelegate.unregisterRequestHandler(handler);
}
@Override
public void registerWildconnectHandler(WildconnectHandler handler) {
clientDelegate.registerWildconnectHandler(handler);
}
@Override
public void unregisterWildconnectHandler(WildconnectHandler handler) {
clientDelegate.unregisterWildconnectHandler(handler);
}
@Override
public void registerAdvdataHandler(AdvdataHandler handler) {
clientDelegate.registerAdvdataHandler(handler);
}
@Override
public void unregisterAdvdataHandler(AdvdataHandler handler) {
clientDelegate.unregisterAdvdataHandler(handler);
}
@Override
public void registerExecuteHandler(ExecuteHandler handler) {
clientDelegate.registerExecuteHandler(handler);
}
@Override
public void unregisterExecuteHandler(ExecuteHandler handler) {
clientDelegate.unregisterExecuteHandler(handler);
}
@Override
public void registerPokeHandler(PokeHandler handler) {
clientDelegate.registerPokeHandler(handler);
}
@Override
public void unregisterPokeHandler(PokeHandler handler) {
clientDelegate.unregisterPokeHandler(handler);
}
@Override
public void registerConnectConfirmHandler(ConnectConfirmHandler handler) {
clientDelegate.registerConnectConfirmHandler(handler);
}
@Override
public void unregisterConnectConfirmHandler(ConnectConfirmHandler handler) {
clientDelegate.unregisterConnectConfirmHandler(handler);
}
@Override
public void registerDisconnectHandler(DisconnectHandler handler) {
clientDelegate.registerDisconnectHandler(handler);
}
@Override
public void unregisterDisconnectHandler(DisconnectHandler handler) {
clientDelegate.unregisterDisconnectHandler(handler);
}
@Override
public void registerErrorHandler(ErrorHandler handler) {
clientDelegate.registerErrorHandler(handler);
}
@Override
public void unregisterErrorHandler(ErrorHandler handler) {
clientDelegate.unregisterErrorHandler(handler);
}
@Override
public void registerRegisterHandler(RegisterHandler handler) {
clientDelegate.registerRegisterHandler(handler);
}
@Override
public void unregisterRegisterHandler(RegisterHandler handler) {
clientDelegate.unregisterRegisterHandler(handler);
}
@Override
public void registerXactCompleteHandler(XactCompleteHandler handler) {
clientDelegate.registerXactCompleteHandler(handler);
}
@Override
public void unregisterXactCompleteHandler(XactCompleteHandler handler) {
clientDelegate.unregisterXactCompleteHandler(handler);
}
@Override
public void registerUnregisterHandler(UnregisterHandler handler) {
clientDelegate.registerUnregisterHandler(handler);
}
@Override
public void unregisterUnregisterHandler(UnregisterHandler handler) {
clientDelegate.unregisterUnregisterHandler(handler);
}
@Override
public void registerMonitorHandler(MonitorHandler handler) {
clientDelegate.registerMonitorHandler(handler);
}
@Override
public void unregisterMonitorHandler(MonitorHandler handler) {
clientDelegate.unregisterMonitorHandler(handler);
}
}
private static class MessageLoopWrapper implements InvocationHandler {
private final Object delegate;
private final MessageLoopThread loopThread;
public MessageLoopWrapper(MessageLoopThread thread, Object delegate) {
this.loopThread = thread;
this.delegate = delegate;
}
public Object invoke(final Object proxy, final Method method, final Object[] args) throws Throwable {
try {
Object result = method.invoke(delegate, args);
Class<?> wrapClass = null;
if ( result instanceof IDdeConnection ) {
wrapClass = IDdeConnection.class;
} else if (result instanceof IDdeConnectionList) {
wrapClass = IDdeConnectionList.class;
} else if (result instanceof IDdeClient) {
wrapClass = IDdeClient.class;
}
if(wrapClass != null && method.getReturnType().isAssignableFrom(wrapClass)) {
result = wrap(result, wrapClass);
}
return result;
} catch (InvocationTargetException ex) {
Throwable cause = ex.getCause();
if (cause instanceof Exception) {
throw (Exception) cause;
} else {
throw ex;
}
}
}
private <V> V wrap(V delegate, Class clazz) {
V messageLoopHandler = (V) Proxy.newProxyInstance(StandaloneDdeClient.class.getClassLoader(),
new Class[]{clazz},
loopThread.new Handler(delegate));
V clientDelegate = (V) Proxy.newProxyInstance(StandaloneDdeClient.class.getClassLoader(),
new Class[]{clazz},
new MessageLoopWrapper(loopThread, messageLoopHandler));
return clientDelegate;
}
}
public static class DdeConnection implements IDdeConnection {
private HCONV conv;
private final IDdeClient client;
public DdeConnection(IDdeClient client, HCONV conv) {
this.conv = conv;
this.client = client;
}
public Ddeml.HCONV getConv() {
return conv;
}
@Override
public void abandonTransaction(int transactionId) {
boolean result = Ddeml.INSTANCE.DdeAbandonTransaction(client.getInstanceIdentitifier(), conv, transactionId);
if(! result) {
throw DdemlException.create(client.getLastError());
}
}
public void abandonTransactions() {
boolean result = Ddeml.INSTANCE.DdeAbandonTransaction(client.getInstanceIdentitifier(), conv, 0);
if(! result) {
throw DdemlException.create(client.getLastError());
}
}
@Override
public Ddeml.HDDEDATA clientTransaction(Pointer data, int dataLength, Ddeml.HSZ item, int wFmt, int transaction, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle) {
if(timeout == Ddeml.TIMEOUT_ASYNC && result == null) {
result = new WinDef.DWORDByReference();
}
Ddeml.HDDEDATA returnData = Ddeml.INSTANCE.DdeClientTransaction(data, dataLength, conv, item, wFmt, transaction, timeout, result);
if(returnData == null) {
throw DdemlException.create(client.getLastError());
}
if (userHandle != null) {
if (timeout != Ddeml.TIMEOUT_ASYNC) {
setUserHandle(Ddeml.QID_SYNC, userHandle);
} else {
setUserHandle(result.getValue().intValue(), userHandle);
}
}
return returnData;
}
public Ddeml.HDDEDATA clientTransaction(Pointer data, int dataLength, String item, int wFmt, int transaction, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle) {
HSZ itemHSZ = null;
try {
itemHSZ = client.createStringHandle(item);
return clientTransaction(data, dataLength, itemHSZ, wFmt, transaction, timeout, result, userHandle);
} finally {
client.freeStringHandle(itemHSZ);
}
}
@Override
public void poke(Pointer data, int dataLength, Ddeml.HSZ item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle) {
clientTransaction(data, dataLength, item, wFmt, Ddeml.XTYP_POKE, timeout, result, userHandle);
}
public void poke(Pointer data, int dataLength, String item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle) {
HSZ itemHSZ = null;
try {
itemHSZ = client.createStringHandle(item);
poke(data, dataLength, itemHSZ, wFmt, timeout, result, userHandle);
} finally {
client.freeStringHandle(itemHSZ);
}
}
@Override
public Ddeml.HDDEDATA request(Ddeml.HSZ item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle) {
return clientTransaction(Pointer.NULL, 0, item, wFmt, Ddeml.XTYP_REQUEST, timeout, result, userHandle);
}
public Ddeml.HDDEDATA request(String item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle) {
HSZ itemHSZ = null;
try {
itemHSZ = client.createStringHandle(item);
return request(itemHSZ, wFmt, timeout, result, userHandle);
} finally {
client.freeStringHandle(itemHSZ);
}
}
@Override
public void execute(String executeString, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle) {
Memory mem = new Memory(executeString.length() * 2 + 2);
mem.setWideString(0, executeString);
clientTransaction(mem, (int) mem.size(), (HSZ) null, 0, Ddeml.XTYP_EXECUTE, timeout, result, userHandle);
}
@Override
public void advstart(Ddeml.HSZ item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle) {
clientTransaction(Pointer.NULL, 0, item, wFmt, Ddeml.XTYP_ADVSTART, timeout, result, userHandle);
}
public void advstart(String item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle) {
HSZ itemHSZ = null;
try {
itemHSZ = client.createStringHandle(item);
advstart(itemHSZ, wFmt, timeout, result, userHandle);
} finally {
client.freeStringHandle(itemHSZ);
}
}
@Override
public void advstop(Ddeml.HSZ item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle) {
clientTransaction(Pointer.NULL, 0, item, wFmt, Ddeml.XTYP_ADVSTOP, timeout, result, userHandle);
}
public void advstop(String item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle) {
HSZ itemHSZ = null;
try {
itemHSZ = client.createStringHandle(item);
advstop(itemHSZ, wFmt, timeout, result, userHandle);
} finally {
client.freeStringHandle(itemHSZ);
}
}
public void impersonateClient() {
boolean result = Ddeml.INSTANCE.DdeImpersonateClient(conv);
if (!result) {
throw DdemlException.create(client.getLastError());
}
}
public void close() {
boolean result = Ddeml.INSTANCE.DdeDisconnect(conv);
if(! result) {
throw DdemlException.create(client.getLastError());
}
}
public void reconnect() {
Ddeml.HCONV newConv = Ddeml.INSTANCE.DdeReconnect(conv);
if(newConv != null) {
conv = newConv;
} else {
throw DdemlException.create(client.getLastError());
}
}
public boolean enableCallback(int wCmd) {
boolean result = Ddeml.INSTANCE.DdeEnableCallback(client.getInstanceIdentitifier(), conv, wCmd);
if ((!result) && wCmd == Ddeml.EC_QUERYWAITING) {
throw DdemlException.create(client.getLastError());
}
return result;
}
public void setUserHandle(int id, DWORD_PTR hUser) throws DdemlException {
boolean result = Ddeml.INSTANCE.DdeSetUserHandle(conv, id, hUser);
if (!result) {
throw DdemlException.create(client.getLastError());
}
}
public CONVINFO queryConvInfo(int idTransaction) throws DdemlException {
CONVINFO convInfo = new Ddeml.CONVINFO();
convInfo.cb = convInfo.size();
convInfo.ConvCtxt.cb = convInfo.ConvCtxt.size();
convInfo.write();
int result = Ddeml.INSTANCE.DdeQueryConvInfo(conv, idTransaction, convInfo);
if (result == 0) {
throw DdemlException.create(client.getLastError());
}
return convInfo;
}
}
public static class DdeConnectionList implements IDdeConnectionList {
private final IDdeClient client;
private final HCONVLIST convList;
public DdeConnectionList(IDdeClient client, Ddeml.HCONVLIST convList) {
this.convList = convList;
this.client = client;
}
@Override
public Ddeml.HCONVLIST getHandle() {
return this.convList;
}
@Override
public IDdeConnection queryNextServer(IDdeConnection prevConnection) {
Ddeml.HCONV conv = Ddeml.INSTANCE.DdeQueryNextServer(
convList,
prevConnection != null ? prevConnection.getConv() : null);
if(conv != null) {
return new DdeConnection(client, conv);
} else {
return null;
}
}
@Override
public void close() {
boolean result = Ddeml.INSTANCE.DdeDisconnectList(convList);
if(! result){
throw DdemlException.create(client.getLastError());
}
}
}
public static class DdeClient implements IDdeClient {
private Integer idInst;
private final DdeAdapter ddeAdapter = new DdeAdapter();
public Integer getInstanceIdentitifier() {
return idInst;
}
public void initialize(int afCmd) throws DdemlException {
WinDef.DWORDByReference pidInst = new WinDef.DWORDByReference();
Integer result = Ddeml.INSTANCE.DdeInitialize(pidInst, ddeAdapter, afCmd, 0);
if(result != Ddeml.DMLERR_NO_ERROR) {
throw DdemlException.create(result);
}
idInst = pidInst.getValue().intValue();
if(ddeAdapter instanceof DdeAdapter) {
ddeAdapter.setInstanceIdentifier(idInst);
}
}
public Ddeml.HSZ createStringHandle(String value) throws DdemlException {
if(value == null) {
return null;
}
int codePage;
if(W32APIOptions.DEFAULT_OPTIONS == W32APIOptions.UNICODE_OPTIONS) {
codePage = Ddeml.CP_WINUNICODE;
} else {
codePage = Ddeml.CP_WINANSI;
}
Ddeml.HSZ handle = Ddeml.INSTANCE.DdeCreateStringHandle(idInst, value, codePage);
if(handle == null) {
throw DdemlException.create(getLastError());
}
return handle;
}
public void nameService(Ddeml.HSZ name, int afCmd) throws DdemlException {
Ddeml.HDDEDATA handle = Ddeml.INSTANCE.DdeNameService(idInst, name, new Ddeml.HSZ(), afCmd);
if (handle == null) {
throw DdemlException.create(getLastError());
}
}
public void nameService(String name, int afCmd) throws DdemlException {
HSZ nameHSZ = null;
try {
nameHSZ = createStringHandle(name);
nameService(nameHSZ, afCmd);
} finally {
freeStringHandle(nameHSZ);
}
}
public int getLastError() {
return Ddeml.INSTANCE.DdeGetLastError(idInst);
}
public IDdeConnection connect(Ddeml.HSZ service, Ddeml.HSZ topic, Ddeml.CONVCONTEXT convcontext) {
Ddeml.HCONV hconv = Ddeml.INSTANCE.DdeConnect(idInst, service, topic, convcontext);
if(hconv == null) {
throw DdemlException.create(getLastError());
}
return new DdeConnection(this, hconv);
}
public IDdeConnection connect(String service, String topic, Ddeml.CONVCONTEXT convcontext) {
HSZ serviceHSZ = null;
HSZ topicHSZ = null;
try {
serviceHSZ = createStringHandle(service);
topicHSZ = createStringHandle(topic);
return connect(serviceHSZ, topicHSZ, convcontext);
} finally {
freeStringHandle(topicHSZ);
freeStringHandle(serviceHSZ);
}
}
public String queryString(Ddeml.HSZ value) throws DdemlException {
int codePage;
int byteWidth;
if(W32APIOptions.DEFAULT_OPTIONS == W32APIOptions.UNICODE_OPTIONS) {
codePage = Ddeml.CP_WINUNICODE;
byteWidth = 2;
} else {
codePage = Ddeml.CP_WINANSI;
byteWidth = 1;
}
Memory buffer = new Memory((256 + 1) * byteWidth);
try {
int length = Ddeml.INSTANCE.DdeQueryString(idInst, value, buffer, 256, codePage);
if (W32APIOptions.DEFAULT_OPTIONS == W32APIOptions.UNICODE_OPTIONS) {
return buffer.getWideString(0);
} else {
return buffer.getString(0);
}
} finally {
buffer.valid();
}
}
public Ddeml.HDDEDATA createDataHandle(Pointer pSrc, int cb, int cbOff, Ddeml.HSZ hszItem, int wFmt, int afCmd) {
Ddeml.HDDEDATA returnData = Ddeml.INSTANCE.DdeCreateDataHandle(idInst, pSrc, cb, cbOff, hszItem, wFmt, afCmd);
if(returnData == null) {
throw DdemlException.create(getLastError());
}
return returnData;
}
public void freeDataHandle(Ddeml.HDDEDATA hData) {
boolean result = Ddeml.INSTANCE.DdeFreeDataHandle(hData);
if(! result) {
throw DdemlException.create(getLastError());
}
}
public Ddeml.HDDEDATA addData(Ddeml.HDDEDATA hData, Pointer pSrc, int cb, int cbOff) {
Ddeml.HDDEDATA newHandle = Ddeml.INSTANCE.DdeAddData(hData, pSrc, cb, cbOff);
if(newHandle == null) {
throw DdemlException.create(getLastError());
}
return newHandle;
}
public int getData(Ddeml.HDDEDATA hData, Pointer pDst, int cbMax, int cbOff) {
int result = Ddeml.INSTANCE.DdeGetData(hData, pDst, cbMax, cbOff);
int errorCode = getLastError();
if(errorCode != Ddeml.DMLERR_NO_ERROR) {
throw DdemlException.create(errorCode);
}
return result;
}
public Pointer accessData(Ddeml.HDDEDATA hData, WinDef.DWORDByReference pcbDataSize) {
Pointer result = Ddeml.INSTANCE.DdeAccessData(hData, pcbDataSize);
if(result == null) {
throw DdemlException.create(getLastError());
}
return result;
}
public void unaccessData(Ddeml.HDDEDATA hData) {
boolean result = Ddeml.INSTANCE.DdeUnaccessData(hData);
if (!result) {
throw DdemlException.create(getLastError());
}
}
public void postAdvise(Ddeml.HSZ hszTopic, Ddeml.HSZ hszItem) {
boolean result = Ddeml.INSTANCE.DdePostAdvise(idInst, hszTopic, hszItem);
if (!result) {
throw DdemlException.create(getLastError());
}
}
public void postAdvise(String topic, String item) {
HSZ itemHSZ = null;
HSZ topicHSZ = null;
try {
topicHSZ = createStringHandle(topic);
itemHSZ = createStringHandle(item);
postAdvise(topicHSZ, itemHSZ);
} finally {
freeStringHandle(topicHSZ);
freeStringHandle(itemHSZ);
}
}
public boolean freeStringHandle(Ddeml.HSZ value) {
if(value == null) {
return true;
}
return Ddeml.INSTANCE.DdeFreeStringHandle(idInst, value);
}
public boolean keepStringHandle(Ddeml.HSZ value) {
return Ddeml.INSTANCE.DdeKeepStringHandle(idInst, value);
}
public void abandonTransactions() {
boolean result = Ddeml.INSTANCE.DdeAbandonTransaction(idInst, null, 0);
if(! result) {
throw DdemlException.create(getLastError());
}
}
public IDdeConnectionList connectList(Ddeml.HSZ service, Ddeml.HSZ topic, IDdeConnectionList existingList, Ddeml.CONVCONTEXT ctx) {
Ddeml.HCONVLIST convlist = Ddeml.INSTANCE.DdeConnectList(idInst, service, topic, existingList != null ? existingList.getHandle() : null, ctx);
if(convlist == null) {
throw DdemlException.create(getLastError());
} else {
return new DdeConnectionList(this, convlist);
}
}
public IDdeConnectionList connectList(String service, String topic, IDdeConnectionList existingList, Ddeml.CONVCONTEXT ctx) {
HSZ serviceHSZ = null;
HSZ topicHSZ = null;
try {
serviceHSZ = createStringHandle(service);
topicHSZ = createStringHandle(topic);
return connectList(serviceHSZ, topicHSZ, existingList, ctx);
} finally {
freeStringHandle(topicHSZ);
freeStringHandle(serviceHSZ);
}
}
public boolean enableCallback(int wCmd) {
boolean result = Ddeml.INSTANCE.DdeEnableCallback(idInst, null, wCmd);
if ((!result) && wCmd != Ddeml.EC_QUERYWAITING) {
int errorCode = getLastError();
if(errorCode != Ddeml.DMLERR_NO_ERROR) {
throw DdemlException.create(getLastError());
}
}
return result;
}
public boolean uninitialize() {
return Ddeml.INSTANCE.DdeUninitialize(idInst);
}
public void close() {
uninitialize();
}
public IDdeConnection wrap(HCONV hconv) {
return new DdeConnection(this, hconv);
}
public void unregisterDisconnectHandler(DisconnectHandler handler) {
ddeAdapter.unregisterDisconnectHandler(handler);
}
public void registerAdvstartHandler(AdvstartHandler handler) {
ddeAdapter.registerAdvstartHandler(handler);
}
public void unregisterAdvstartHandler(AdvstartHandler handler) {
ddeAdapter.unregisterAdvstartHandler(handler);
}
public void registerAdvstopHandler(AdvstopHandler handler) {
ddeAdapter.registerAdvstopHandler(handler);
}
public void unregisterAdvstopHandler(AdvstopHandler handler) {
ddeAdapter.unregisterAdvstopHandler(handler);
}
public void registerConnectHandler(ConnectHandler handler) {
ddeAdapter.registerConnectHandler(handler);
}
public void unregisterConnectHandler(ConnectHandler handler) {
ddeAdapter.unregisterConnectHandler(handler);
}
public void registerAdvReqHandler(AdvreqHandler handler) {
ddeAdapter.registerAdvReqHandler(handler);
}
public void unregisterAdvReqHandler(AdvreqHandler handler) {
ddeAdapter.unregisterAdvReqHandler(handler);
}
public void registerRequestHandler(RequestHandler handler) {
ddeAdapter.registerRequestHandler(handler);
}
public void unregisterRequestHandler(RequestHandler handler) {
ddeAdapter.unregisterRequestHandler(handler);
}
public void registerWildconnectHandler(WildconnectHandler handler) {
ddeAdapter.registerWildconnectHandler(handler);
}
public void unregisterWildconnectHandler(WildconnectHandler handler) {
ddeAdapter.unregisterWildconnectHandler(handler);
}
public void registerAdvdataHandler(AdvdataHandler handler) {
ddeAdapter.registerAdvdataHandler(handler);
}
public void unregisterAdvdataHandler(AdvdataHandler handler) {
ddeAdapter.unregisterAdvdataHandler(handler);
}
public void registerExecuteHandler(ExecuteHandler handler) {
ddeAdapter.registerExecuteHandler(handler);
}
public void unregisterExecuteHandler(ExecuteHandler handler) {
ddeAdapter.unregisterExecuteHandler(handler);
}
public void registerPokeHandler(PokeHandler handler) {
ddeAdapter.registerPokeHandler(handler);
}
public void unregisterPokeHandler(PokeHandler handler) {
ddeAdapter.unregisterPokeHandler(handler);
}
public void registerConnectConfirmHandler(ConnectConfirmHandler handler) {
ddeAdapter.registerConnectConfirmHandler(handler);
}
public void unregisterConnectConfirmHandler(ConnectConfirmHandler handler) {
ddeAdapter.unregisterConnectConfirmHandler(handler);
}
public void registerDisconnectHandler(DisconnectHandler handler) {
ddeAdapter.registerDisconnectHandler(handler);
}
public void registerErrorHandler(ErrorHandler handler) {
ddeAdapter.registerErrorHandler(handler);
}
public void unregisterErrorHandler(ErrorHandler handler) {
ddeAdapter.unregisterErrorHandler(handler);
}
public void registerRegisterHandler(RegisterHandler handler) {
ddeAdapter.registerRegisterHandler(handler);
}
public void unregisterRegisterHandler(RegisterHandler handler) {
ddeAdapter.unregisterRegisterHandler(handler);
}
public void registerXactCompleteHandler(XactCompleteHandler handler) {
ddeAdapter.registerXactCompleteHandler(handler);
}
public void unregisterXactCompleteHandler(XactCompleteHandler handler) {
ddeAdapter.xactCompleteXactCompleteHandler(handler);
}
public void registerUnregisterHandler(UnregisterHandler handler) {
ddeAdapter.registerUnregisterHandler(handler);
}
public void unregisterUnregisterHandler(UnregisterHandler handler) {
ddeAdapter.unregisterUnregisterHandler(handler);
}
public void registerMonitorHandler(MonitorHandler handler) {
ddeAdapter.registerMonitorHandler(handler);
}
public void unregisterMonitorHandler(MonitorHandler handler) {
ddeAdapter.unregisterMonitorHandler(handler);
}
}
public interface AdvstartHandler {
/**
* A server callback function should return TRUE to allow an advise loop
* on the specified topic name and item name pair, or FALSE to deny the
* advise loop. If the callback function returns TRUE, any subsequent
* calls to the DdePostAdvise function by the server on the same topic
* name and item name pair causes the system to send XTYP_ADVREQ
* transactions to the server.
*
* <p>
* <strong>Remarks</strong></p>
* <p>If a client requests an advise loop on a topic name, item name,
* and data format for an advise loop that is already established, the
* Dynamic Data Exchange Management Library (DDEML) does not create a
* duplicate advise loop but instead alters the advise loop flags
* (XTYPF_ACKREQ and XTYPF_NODATA) to match the latest request.</p>
*
* <p>
* This transaction is filtered if the server application specified the
* CBF_FAIL_ADVISES flag in the DdeInitialize function.</p>
*
* @param transactionType uType - The transaction type.
* @param dataFormat uFmt - The data format requested by the client.
* @param hconv A handle to the conversation.
* @param topic hsz1 - A handle to the topic name.
* @param item hsz2 - A handle to the item name.
* @return true if advise loop can be started
*/
boolean onAdvstart(int transactionType, int dataFormat, HCONV hconv, HSZ topic, HSZ item);
}
public interface AdvstopHandler {
/**
* A client uses the XTYP_ADVSTOP transaction to end an advise loop with
* a server. A Dynamic Data Exchange (DDE) server callback function,
* DdeCallback, receives this transaction when a client specifies
* XTYP_ADVSTOP in the DdeClientTransaction function.
*
* @param transactionType uType - The transaction type.
* @param dataFormat uFmt - The data format associated with the advise
* loop being ended.
* @param hconv A handle to the conversation.
* @param topic hsz1 - A handle to the topic name.
* @param item hsz2 - A handle to the item name.
*/
void onAdvstop(int transactionType, int dataFormat, HCONV hconv, HSZ topic, HSZ item);
}
public interface ConnectHandler {
/**
* A client uses the XTYP_CONNECT transaction to establish a
* conversation. A Dynamic Data Exchange (DDE) server callback function,
* DdeCallback, receives this transaction when a client specifies a
* service name that the server supports (and a topic name that is not
* NULL) in a call to the DdeConnect function.
*
* @param transactionType uType - The transaction type.
* @param topic hsz1 - A handle to the topic name.
* @param service hsz2 - A handle to the service name.
* @param convcontext dwData1 - CONVCONTEXT structure that contains
* context information for the conversation. If the client is not a
* DDEML application, this parameter is NULL.
* @param sameInstance dwData2 - Specifies whether the client is the
* same application instance as the server.
* @return true is connect can continue
*/
boolean onConnect(int transactionType, HSZ topic, HSZ service, CONVCONTEXT convcontext, boolean sameInstance);
}
public interface AdvreqHandler {
/**
* The XTYP_ADVREQ transaction informs the server that an advise
* transaction is outstanding on the specified topic name and item name
* pair and that data corresponding to the topic name and item name pair
* has changed. The system sends this transaction to the Dynamic Data
* Exchange (DDE) callback function, DdeCallback, after the server calls
* the DdePostAdvise function.
*
* @param transactionType uType - The transaction type.
* @param dataFormat uFmt - The format in which the data should be
* submitted to the client.
* @param hconv A handle to the conversation.
* @param topic hsz1 - A handle to the topic name.
* @param item hsz2 - A handle to the item name that has changed.
* @param count The count of XTYP_ADVREQ transactions that remain to be
* processed on the same topic, item, and format name set within the
* context of the current call to the DdePostAdvise function. The count
* is zero if the current XTYP_ADVREQ transaction is the last one. A
* server can use this count to determine whether to create an
* HDATA_APPOWNED data handle to the advise data.
*
* <p>
* This is set to CADV_LATEACK if the DDEML issued the XTYP_ADVREQ
* transaction because of a late-arriving DDE_ACK message from a client
* being outrun by the server. </p>
*
* @return Data for the changed item or NULL if transaction can't be
* completed.
*/
HDDEDATA onAdvreq(int transactionType, int dataFormat, HCONV hconv, HSZ topic, HSZ item, int count);
}
public interface RequestHandler {
/**
* A client uses the XTYP_REQUEST transaction to request data from a
* server. A Dynamic Data Exchange (DDE) server callback function,
* DdeCallback, receives this transaction when a client specifies
* XTYP_REQUEST in the DdeClientTransaction function.
*
* @param transactionType uType - The transaction type.
* @param dataFormat uFmt - The format in which the data should be
* submitted to the client.
* @param hconv A handle to the conversation.
* @param topic hsz1 - A handle to the topic name.
* @param item hsz2 - A handle to the item name.
*
* @return Data for the changed item or NULL if transaction can't be
* completed. If the server returns NULL, the client will receive a
* DDE_FNOTPROCESSED flag.
*/
HDDEDATA onRequest(int transactionType, int dataFormat, HCONV hconv, HSZ topic, HSZ item);
}
public interface WildconnectHandler {
/**
* Enables a client to establish a conversation on each of the server's
* service name and topic name pairs that match the specified service
* name and topic name. A Dynamic Data Exchange (DDE) server callback
* function, DdeCallback, receives this transaction when a client
* specifies a NULL service name, a NULL topic name, or both in a call
* to the DdeConnect or DdeConnectList function.
*
* @param transactionType uType - The transaction type.
* @param topic A handle to the topic name. If this parameter is NULL,
* the client is requesting a conversation on all topic names that the
* server supports.
* @param service A handle to the service name. If this parameter is
* NULL, the client is requesting a conversation on all service names
* that the server supports.
* @param convcontext dwData1 - CONVCONTEXT structure that contains
* context information for the conversation. If the client is not a
* DDEML application, this parameter is NULL.
* @param sameInstance dwData2 - Specifies whether the client is the
* same application instance as the server.
* @return the supported HSZPAIRs (do not include the terminating pair
* needed be the DdeCallback!)
*/
List<HSZPAIR> onWildconnect(int transactionType, HSZ topic, HSZ service, CONVCONTEXT convcontext, boolean sameInstance);
}
public interface AdvdataHandler {
/**
* Informs the client that the value of the data item has changed. The
* Dynamic Data Exchange (DDE) client callback function, DdeCallback,
* receives this transaction after establishing an advise loop with a
* server.
*
* @param transactionType uType - The transaction type.
* @param dataFormat uFmt - The format atom of the data sent from the
* server.
* @param hconv A handle to the conversation.
* @param topic hsz1 - A handle to the topic name.
* @param item hsz2 - A handle to the item name.
* @param hdata A handle to the data associated with the topic name and
* item name pair. This parameter is NULL if the client specified the
* XTYPF_NODATA flag when it requested the advise loop.
* @return A DDE callback function should return DDE_FACK if it
* processes this transaction, DDE_FBUSY if it is too busy to process
* this transaction, or DDE_FNOTPROCESSED if it rejects this
* transaction.
*/
int onAdvdata(int transactionType, int dataFormat, HCONV hconv, HSZ topic, HSZ item, HDDEDATA hdata);
}
public interface ConnectConfirmHandler {
/**
* A Dynamic Data Exchange (DDE) server callback function, DdeCallback,
* receives the XTYP_CONNECT_CONFIRM transaction to confirm that a
* conversation has been established with a client and to provide the
* server with the conversation handle. The system sends this
* transaction as a result of a previous XTYP_CONNECT or
* XTYP_WILDCONNECT transaction.
*
* @param transactionType uType - The transaction type.
* @param hconv A handle to the new conversation.
* @param topic hsz1 - A handle to the topic name.
* @param service hsz2 - A handle to the service name on which the
* conversation has been established.
* @param sameInstance dwData2 - Specifies whether the client is the
* same application instance as the server.
*/
void onConnectConfirm(int transactionType, Ddeml.HCONV hconv, Ddeml.HSZ topic, Ddeml.HSZ service, boolean sameInstance);
}
public interface DisconnectHandler {
/**
* An application's Dynamic Data Exchange (DDE) callback function,
* DdeCallback, receives the XTYP_DISCONNECT transaction when the
* application's partner in a conversation uses the DdeDisconnect
* function to terminate the conversation.
*
* <p>
* <strong>Remarks</strong></p>
*
* <p>
* This transaction is filtered if the application specified the
* CBF_SKIP_DISCONNECTS flag in the DdeInitialize function.</p>
* <p>
* The application can obtain the status of the terminated conversation
* by calling the DdeQueryConvInfo function while processing this
* transaction. The conversation handle becomes invalid after the
* callback function returns.</p>
* <p>
* An application cannot block this transaction type; the CBR_BLOCK
* return code is ignored.</p>
*
* @param transactionType uType - The transaction type.
* @param hconv A handle to that the conversation was terminated.
* @param sameInstance dwData2 - Specifies whether the client is the
* same application instance as the server.
*/
void onDisconnect(int transactionType, HCONV hconv, boolean sameInstance);
}
public interface ErrorHandler {
/**
* A Dynamic Data Exchange (DDE) callback function, DdeCallback,
* receives the XTYP_ERROR transaction when a critical error occurs.
*
* <p>
* <strong>Remarks</strong></p>
*
* <p>
* An application cannot block this transaction type; the CBR_BLOCK
* return code is ignored. The Dynamic Data Exchange Management Library
* (DDEML) attempts to free memory by removing noncritical resources. An
* application that has blocked conversations should unblock them. </p>
*
* @param transactionType uType - The transaction type.
* @param hconv A handle to the conversation associated with the error.
* This parameter is NULL if the error is not associated with a
* conversation.
* @param errorCode dwData1 - The error code in the low-order word.
* Currently, only the following error code is supported.
* <p>
* Only Ddeml.DMLERR_LOW_MEMRORY is known: Memory is low; advise, poke,
* or execute data may be lost, or the system may fail.</p>
*/
void onError(int transactionType, HCONV hconv, int errorCode);
}
public interface RegisterHandler {
/**
* A Dynamic Data Exchange (DDE) callback function, DdeCallback, receives the XTYP_REGISTER transaction type whenever a Dynamic Data Exchange Management Library (DDEML) server application uses the DdeNameService function to register a service name, or whenever a non-DDEML application that supports the System topic is started.
*
* <p>
* <strong>Remarks</strong></p>
*<p>
* This transaction is filtered if the application specified the
* CBF_SKIP_REGISTRATIONS flag in the DdeInitialize function.</p>
*<p>
* A application cannot block this transaction type; the CBR_BLOCK
* return code is ignored.</p>
*<p>
* An application should use the hsz1 parameter to add the service name
* to the list of servers available to the user. An application should
* use the hsz2 parameter to identify which application instance has
* started. </p>
*
* @param transactionType uType - The transaction type.
* @param baseServiceName hsz1 - A handle to the base service name being
* registered.
* @param instanceSpecificServiceName hsz2 - A handle to the
* instance-specific service name being registered.
*/
void onRegister(int transactionType, HSZ baseServiceName, HSZ instanceSpecificServiceName);
}
public interface XactCompleteHandler {
/**
* A Dynamic Data Exchange (DDE) client callback function, DdeCallback,
* receives the XTYP_XACT_COMPLETE transaction when an asynchronous
* transaction, initiated by a call to the DdeClientTransaction
* function, has completed.
*
* <p>
* <strong>Remarks</strong></p>
* <p>
* An application must not free the data handle obtained during this
* transaction. An application must, however, copy the data associated
* with the data handle if the application must process the data after
* the callback function returns. An application can use the DdeGetData
* function to copy the data.</p>
*
* @param transactionType uType - The transaction type.
* @param dataFormat uFmt - The format of the data associated with the
* completed transaction (if applicable) or NULL if no data was
* exchanged during the transaction.
* @param hConv - A handle to the conversation.
* @param topic hsz1 - A handle to the topic name involved in the
* completed transaction.
* @param item hsz2 - A handle to the item name involved in the
* completed transaction.
* @param hdata A handle to the data involved in the completed
* transaction, if applicable. If the transaction was successful but
* involved no data, this parameter is TRUE. This parameter is NULL if
* the transaction was unsuccessful.
* @param transactionIdentifier dwData1 - The transaction identifier of
* the completed transaction.
* @param statusFlag dwData2 - Any applicable DDE_ status flags in the low word. This parameter provides support for applications dependent on DDE_APPSTATUS bits. It is recommended that applications no longer use these bits � they may not be supported in future versions of the DDEML.
*/
void onXactComplete(int transactionType, int dataFormat, HCONV hConv, HSZ topic, HSZ item, HDDEDATA hdata, ULONG_PTR transactionIdentifier, ULONG_PTR statusFlag);
}
public interface UnregisterHandler {
/**
* A Dynamic Data Exchange (DDE) callback function, DdeCallback, receives the XTYP_REGISTER transaction type whenever a Dynamic Data Exchange Management Library (DDEML) server application uses the DdeNameService function to register a service name, or whenever a non-DDEML application that supports the System topic is started.
*
* <p>
* <strong>Remarks</strong></p>
* <p>
* This transaction is filtered if the application specified the
* CBF_SKIP_REGISTRATIONS flag in the DdeInitialize function.</p>
*<p>
* A application cannot block this transaction type; the CBR_BLOCK
* return code is ignored.</p>
*<p>
* An application should use the hsz1 parameter to remove the service
* name from the list of servers available to the user. An application
* should use the hsz2 parameter to identify which application instance
* has terminated. </p>
*
* @param transactionType uType - The transaction type.
* @param baseServiceName hsz1 - A handle to the base service name being
* registered.
* @param instanceSpecificServiceName hsz2 - A handle to the
* instance-specific service name being registered.
*/
void onUnregister(int transactionType, HSZ baseServiceName, HSZ instanceSpecificServiceName);
}
public interface ExecuteHandler {
/**
* A client uses the XTYP_EXECUTE transaction to send a command string
* to the server. A Dynamic Data Exchange (DDE) server callback
* function, DdeCallback, receives this transaction when a client
* specifies XTYP_EXECUTE in the DdeClientTransaction function.
*
* <p>
* <strong>Remarks</strong></p>
* <p>
* This transaction is filtered if the server application specified the
* CBF_FAIL_EXECUTES flag in the DdeInitialize function.</p>
*<p>
* Because most client applications expect a server application to
* perform an XTYP_EXECUTE transaction synchronously, a server should
* attempt to perform all processing of the XTYP_EXECUTE transaction
* either from within the DDE callback function or by returning the
* CBR_BLOCK return code. If the hdata parameter is a command that
* instructs the server to terminate, the server should do so after
* processing the XTYP_EXECUTE transaction. </p>
*
* @param transactionType uType - The transaction type.
* @param hconv A handle to the conversation.
* @param topic hsz1 - A handle to the topic name.
* @param commandString A handle to the command string.
* @return A server callback function should return DDE_FACK if it
* processes this transaction, DDE_FBUSY if it is too busy to process
* this transaction, or DDE_FNOTPROCESSED if it rejects this
* transaction.
*
*/
int onExecute(int transactionType, Ddeml.HCONV hconv, Ddeml.HSZ topic, Ddeml.HDDEDATA commandString);
}
public interface PokeHandler {
/**
* A client uses the XTYP_POKE transaction to send unsolicited data to
* the server. A Dynamic Data Exchange (DDE) server callback function,
* DdeCallback, receives this transaction when a client specifies
* XTYP_POKE in the DdeClientTransaction function.
*
* @param transactionType uType - The transaction type.
* @param dataFormat uFmt - The format of the data sent from the server.
* @param hconv A handle to the conversation.
* @param topic hsz1 - A handle to the topic name.
* @param item hsz2 - A handle to the item name.
* @param hdata - A handle to the data that the client is sending to the
* server.
* @return A server callback function should return the DDE_FACK flag if
* it processes this transaction, the DDE_FBUSY flag if it is too busy
* to process this transaction, or the DDE_FNOTPROCESSED flag if it
* rejects this transaction.
*
*/
int onPoke(int transactionType, int dataFormat, HCONV hconv, HSZ topic, HSZ item, HDDEDATA hdata);
}
public interface MonitorHandler {
/**
* A Dynamic Data Exchange (DDE) debugger's DDE callback function,
* DdeCallback, receives the XTYP_MONITOR transaction whenever a DDE
* event occurs in the system. To receive this transaction, an
* application must specify the APPCLASS_MONITOR value when it calls the
* DdeInitialize function.
*
* @param transactionType uType - The transaction type.
* @param hdata A handle to a DDE object that contains information about
* the DDE event. The application should use the DdeAccessData function
* to obtain a pointer to the object.
* @param eventCode dwData2 - The DDE event. This parameter can be one
* of the following values:
*
* <table>
* <tr>
* <th>Value</th><th>Meaning</th>
* </tr>
* <tr><td>
* MF_CALLBACKS<br>
* 0x08000000
* </td>
* <td>
* The system sent a transaction to a DDE callback function. The DDE
* object contains a MONCBSTRUCT structure that provides information
* about the transaction.
* </td>
* </tr>
* <tr><td>
* MF_CONV<br>
* 0x40000000
* </td>
* <td>
* A DDE conversation was established or terminated. The DDE object
* contains a MONCONVSTRUCT structure that provides information about
* the conversation.
* </td>
* </tr>
* <tr><td>
* MF_ERRORS<br>
* 0x10000000
* </td>
* <td>
* A DDE error occurred. The DDE object contains a MONERRSTRUCT
* structure that provides information about the error.
* </td>
* </tr>
* <tr><td>
* MF_HSZ_INFO<br>
* 0x01000000
* </td>
* <td>
* A DDE application created, freed, or incremented the usage count of a
* string handle, or a string handle was freed as a result of a call to
* the DdeUninitialize function. The DDE object contains a MONHSZSTRUCT
* structure that provides information about the string handle.
* </td>
* </tr>
* <tr><td>
* MF_LINKS<br>
* 0x20000000
* </td>
* <td>
* A DDE application started or stopped an advise loop. The DDE object
* contains a MONLINKSTRUCT structure that provides information about
* the advise loop.
* </td>
* </tr>
* <tr><td>
* MF_POSTMSGS<br>
* 0x04000000
* </td>
* <td>
* The system or an application posted a DDE message. The DDE object
* contains a MONMSGSTRUCT structure that provides information about the
* message.
* </td>
* </tr>
* <tr><td>
* MF_SENDMSGS<br>
* 0x02000000
* </td>
* <td>
* The system or an application sent a DDE message. The DDE object
* contains a MONMSGSTRUCT structure that provides information about the
* message.
* </td>
* </tr>
* </table>
*/
void onMonitor(int transactionType, HDDEDATA hdata, int eventCode);
}
/**
* DdeAdapter implements DdeCallback and allow dynamic registration for
* mulitple handlers, that can be registered and unregistered at runtime.
*
* <dl>
* <dt>AdvstartHandler</dt>
* <dd>All registered AdvstartHandler are evaluated. If at least one returns
* true, the whole evaluation is considered true.</dd>
* <dt>AdvstopHandler</dt>
* <dd>All registered AdvstopHandler are invoked.</dd>
* <dt>ConnectHandler</dt>
* <dd>All registered ConnectHandler are evaluated. If at least one returns
* true, the whole evaluation is considered true.</dd>
* <dt>WildconnectHandler</dt>
* <dd>All registered WildconnectHandler are evaluated. The result is the
* union of all HSZPAIRs.</dd>
* <dt>ConnectConfirmHandler</dt>
* <dd>All registered ConnectConfirmHandler are evaluated.</dd>
* <dt>DisconnectHandler</dt>
* <dd>All registered DisconnectHandler are evaluated.</dd>
* <dt>ErrorHandler</dt>
* <dd>All registered ErrorHandler are evaluated.</dd>
* <dt>RegisterHandler</dt>
* <dd>All registered RegisterHandler are evaluated.</dd>
* <dt>XactCompleteHandler</dt>
* <dd>All registered XactCompleteHandler are evaluated.</dd>
* <dt>UnregisterHandler</dt>
* <dd>All registered UnregisterHandlers are evaluated.</dd>
* <dt>MonitorHandler</dt>
* <dd>All registered AdvstopHandler are invoked.</dd>
* <dt>AdvdataHandler</dt>
* <dd>The AdvdataHandlers are evaluated in registration order - evaluation
* stops after the first handler not returning Ddeml.FNOTPROCESSED.</dd>
* <dt>ExecuteHandler</dt>
* <dd>The ExecuteHandler are evaluated in registration order - evaluation
* stops after the first handler not returning Ddeml.FNOTPROCESSED.</dd>
* <dt>PokeHandler</dt>
* <dd>The PokeHandler are evaluated in registration order - evaluation
* stops after the first handler not returning Ddeml.FNOTPROCESSED.</dd>
* <dt>AdvreqHandler</dt>
* <dd>The AdvreqHandlers are evaluated in registration order - evaluation
* stops after the first handler returning a non null value.</dd>
* <dt>RequestHandler</dt>
* <dd>The RequestHandlers are evaluated in registration order - evaluation
* stops after the first handler returning a non null value.</dd>
* </dl>
*/
public static class DdeAdapter implements Ddeml.DdeCallback {
public static class BlockException extends RuntimeException{};
private static final Logger LOG = Logger.getLogger(DdeAdapter.class.getName());
private int idInst;
public void setInstanceIdentifier(int idInst) {
this.idInst = idInst;
}
public WinDef.PVOID ddeCallback(int wType, int wFmt, Ddeml.HCONV hConv, Ddeml.HSZ hsz1, Ddeml.HSZ hsz2, Ddeml.HDDEDATA hData, BaseTSD.ULONG_PTR lData1, BaseTSD.ULONG_PTR lData2) {
boolean booleanResult;
Ddeml.HDDEDATA data;
Ddeml.CONVCONTEXT convcontext;
int intResult;
String transactionTypeName = null;
try {
switch (wType) {
case Ddeml.XTYP_ADVSTART:
booleanResult = onAdvstart(wType, wFmt, hConv, hsz1, hsz2);
return new WinDef.PVOID(Pointer.createConstant(new WinDef.BOOL(booleanResult).intValue()));
case Ddeml.XTYP_CONNECT:
convcontext = null;
if (lData1.toPointer() != null) {
convcontext = new Ddeml.CONVCONTEXT(new Pointer(lData1.longValue()));
}
booleanResult = onConnect(wType, hsz1, hsz2, convcontext, lData2 != null && lData2.intValue() != 0);
return new WinDef.PVOID(Pointer.createConstant(new WinDef.BOOL(booleanResult).intValue()));
case Ddeml.XTYP_ADVREQ:
int count = lData1.intValue() & 0xFFFF;
data = onAdvreq(wType, wFmt, hConv, hsz1, hsz2, count);
if (data == null) {
return new WinDef.PVOID();
} else {
return new WinDef.PVOID(data.getPointer());
}
case Ddeml.XTYP_REQUEST:
data = onRequest(wType, wFmt, hConv, hsz1, hsz2);
if (data == null) {
return new WinDef.PVOID();
} else {
return new WinDef.PVOID(data.getPointer());
}
case Ddeml.XTYP_WILDCONNECT:
convcontext = null;
if (lData1.toPointer() != null) {
convcontext = new Ddeml.CONVCONTEXT(new Pointer(lData1.longValue()));
}
Ddeml.HSZPAIR[] hszPairs = onWildconnect(wType, hsz1, hsz2, convcontext, lData2 != null && lData2.intValue() != 0);
if (hszPairs == null || hszPairs.length == 0) {
return new WinDef.PVOID();
}
int size = 0;
for (Ddeml.HSZPAIR hp : hszPairs) {
hp.write();
size += hp.size();
}
data = Ddeml.INSTANCE.DdeCreateDataHandle(idInst,
hszPairs[0].getPointer(),
size,
0,
null,
wFmt,
0);
return new WinDef.PVOID(data.getPointer());
case Ddeml.XTYP_ADVDATA:
intResult = onAdvdata(wType, wFmt, hConv, hsz1, hsz2, hData);
return new WinDef.PVOID(Pointer.createConstant(intResult));
case Ddeml.XTYP_EXECUTE:
intResult = onExecute(wType, hConv, hsz1, hData);
Ddeml.INSTANCE.DdeFreeDataHandle(hData);
return new WinDef.PVOID(Pointer.createConstant(intResult));
case Ddeml.XTYP_POKE:
intResult = onPoke(wType, wFmt, hConv, hsz1, hsz2, hData);
return new WinDef.PVOID(Pointer.createConstant(intResult));
case Ddeml.XTYP_ADVSTOP:
onAdvstop(wType, wFmt, hConv, hsz1, hsz2);
break;
case Ddeml.XTYP_CONNECT_CONFIRM:
onConnectConfirm(wType, hConv, hsz1, hsz2, lData2 != null && lData2.intValue() != 0);
break;
case Ddeml.XTYP_DISCONNECT:
onDisconnect(wType, hConv, lData2 != null && lData2.intValue() != 0);
break;
case Ddeml.XTYP_ERROR:
onError(wType, hConv, (int) (lData2.longValue() & 0xFFFF));
break;
case Ddeml.XTYP_REGISTER:
onRegister(wType, hsz1, hsz2);
break;
case Ddeml.XTYP_XACT_COMPLETE:
onXactComplete(wType, wFmt, hConv, hsz1, hsz2, hData, lData1, lData2);
break;
case Ddeml.XTYP_UNREGISTER:
onUnregister(wType, hsz1, hsz2);
break;
case Ddeml.XTYP_MONITOR:
onMonitor(wType, hData, lData2.intValue());
break;
default:
LOG.log(Level.FINE, String.format("Not implemented Operation - Transaction type: 0x%X (%s)", wType, transactionTypeName));
}
} catch (BlockException ex) {
return new WinDef.PVOID(Pointer.createConstant(-1));
} catch (Throwable ex) {
LOG.log(Level.WARNING, "Exception in DDECallback", ex);
}
return new WinDef.PVOID();
};
private final List<AdvstartHandler> advstartHandler = new CopyOnWriteArrayList<AdvstartHandler>();
public void registerAdvstartHandler(AdvstartHandler handler) {
advstartHandler.add(handler);
}
public void unregisterAdvstartHandler(AdvstartHandler handler) {
advstartHandler.remove(handler);
}
private boolean onAdvstart(int transactionType, int dataFormat, Ddeml.HCONV hconv, Ddeml.HSZ topic, Ddeml.HSZ item) {
boolean oneHandlerTrue = false;
for (AdvstartHandler handler : advstartHandler) {
if (handler.onAdvstart(transactionType, dataFormat, hconv, topic, item)) {
oneHandlerTrue = true;
}
}
return oneHandlerTrue;
}
private final List<AdvstopHandler> advstopHandler = new CopyOnWriteArrayList<AdvstopHandler>();
public void registerAdvstopHandler(AdvstopHandler handler) {
advstopHandler.add(handler);
}
public void unregisterAdvstopHandler(AdvstopHandler handler) {
advstopHandler.remove(handler);
}
private void onAdvstop(int transactionType, int dataFormat, Ddeml.HCONV hconv, Ddeml.HSZ topic, Ddeml.HSZ item) {
for (AdvstopHandler handler : advstopHandler) {
handler.onAdvstop(transactionType, dataFormat, hconv, topic, item);
}
}
private final List<ConnectHandler> connectHandler = new CopyOnWriteArrayList<ConnectHandler>();
public void registerConnectHandler(ConnectHandler handler) {
connectHandler.add(handler);
}
public void unregisterConnectHandler(ConnectHandler handler) {
connectHandler.remove(handler);
}
private boolean onConnect(int transactionType, Ddeml.HSZ topic, Ddeml.HSZ service, Ddeml.CONVCONTEXT convcontext, boolean sameInstance) {
boolean oneHandlerTrue = false;
for (ConnectHandler handler : connectHandler) {
if (handler.onConnect( transactionType, topic, service, convcontext, sameInstance)) {
oneHandlerTrue = true;
}
}
return oneHandlerTrue;
}
private final List<AdvreqHandler> advReqHandler = new CopyOnWriteArrayList<AdvreqHandler>();
public void registerAdvReqHandler(AdvreqHandler handler) {
advReqHandler.add(handler);
}
public void unregisterAdvReqHandler(AdvreqHandler handler) {
advReqHandler.remove(handler);
}
private Ddeml.HDDEDATA onAdvreq(int transactionType, int dataFormat, Ddeml.HCONV hconv, Ddeml.HSZ topic, Ddeml.HSZ item, int count) {
for (AdvreqHandler handler : advReqHandler) {
HDDEDATA result = handler.onAdvreq(transactionType, dataFormat, hconv, topic, item, count);
if(result != null) {
return result;
}
}
return null;
}
private final List<RequestHandler> requestHandler = new CopyOnWriteArrayList<RequestHandler>();
public void registerRequestHandler(RequestHandler handler) {
requestHandler.add(handler);
}
public void unregisterRequestHandler(RequestHandler handler) {
requestHandler.remove(handler);
}
private Ddeml.HDDEDATA onRequest(int transactionType, int dataFormat, Ddeml.HCONV hconv, Ddeml.HSZ topic, Ddeml.HSZ item) {
for (RequestHandler handler : requestHandler) {
HDDEDATA result = handler.onRequest(transactionType, dataFormat, hconv, topic, item);
if(result != null) {
return result;
}
}
return null;
}
private final List<WildconnectHandler> wildconnectHandler = new CopyOnWriteArrayList<WildconnectHandler>();
public void registerWildconnectHandler(WildconnectHandler handler) {
wildconnectHandler.add(handler);
}
public void unregisterWildconnectHandler(WildconnectHandler handler) {
wildconnectHandler.remove(handler);
}
private Ddeml.HSZPAIR[] onWildconnect(int transactionType, HSZ topic, HSZ service, CONVCONTEXT convcontext, boolean sameInstance) {
List<HSZPAIR> hszpairs = new ArrayList<HSZPAIR>(1);
for(WildconnectHandler handler: wildconnectHandler) {
hszpairs.addAll(handler.onWildconnect(transactionType, topic, service, convcontext, sameInstance));
}
return hszpairs.toArray(new HSZPAIR[hszpairs.size()]);
}
private final List<AdvdataHandler> advdataHandler = new CopyOnWriteArrayList<AdvdataHandler>();
public void registerAdvdataHandler(AdvdataHandler handler) {
advdataHandler.add(handler);
}
public void unregisterAdvdataHandler(AdvdataHandler handler) {
advdataHandler.remove(handler);
}
private int onAdvdata(int transactionType, int dataFormat, HCONV hconv, HSZ topic, HSZ item, HDDEDATA hdata) {
for (AdvdataHandler handler : advdataHandler) {
int result = handler.onAdvdata(transactionType, dataFormat, hconv, topic, item, hdata);
if(result != Ddeml.DDE_FNOTPROCESSED) {
return result;
}
}
return Ddeml.DDE_FNOTPROCESSED;
}
private final List<ExecuteHandler> executeHandler = new CopyOnWriteArrayList<ExecuteHandler>();
public void registerExecuteHandler(ExecuteHandler handler) {
executeHandler.add(handler);
}
public void unregisterExecuteHandler(ExecuteHandler handler) {
executeHandler.remove(handler);
}
private int onExecute(int transactionType, HCONV hconv, HSZ topic, HDDEDATA commandString) {
for (ExecuteHandler handler : executeHandler) {
int result = handler.onExecute(transactionType, hconv, topic, commandString);
if(result != Ddeml.DDE_FNOTPROCESSED) {
return result;
}
}
return Ddeml.DDE_FNOTPROCESSED;
}
private final List<PokeHandler> pokeHandler = new CopyOnWriteArrayList<PokeHandler>();
public void registerPokeHandler(PokeHandler handler) {
pokeHandler.add(handler);
}
public void unregisterPokeHandler(PokeHandler handler) {
pokeHandler.remove(handler);
}
private int onPoke(int transactionType, int dataFormat, HCONV hconv, HSZ topic, HSZ item, HDDEDATA hdata) {
for (PokeHandler handler : pokeHandler) {
int result = handler.onPoke(transactionType, dataFormat, hconv, topic, item, hdata);
if(result != Ddeml.DDE_FNOTPROCESSED) {
return result;
}
}
return Ddeml.DDE_FNOTPROCESSED;
}
private final List<ConnectConfirmHandler> connectConfirmHandler = new CopyOnWriteArrayList<ConnectConfirmHandler>();
public void registerConnectConfirmHandler(ConnectConfirmHandler handler) {
connectConfirmHandler.add(handler);
}
public void unregisterConnectConfirmHandler(ConnectConfirmHandler handler) {
connectConfirmHandler.remove(handler);
}
private void onConnectConfirm(int transactionType, HCONV hconv, HSZ topic, HSZ service, boolean sameInstance) {
for(ConnectConfirmHandler handler: connectConfirmHandler) {
handler.onConnectConfirm(transactionType, hconv, topic, service, sameInstance);
}
}
private final List<DisconnectHandler> disconnectHandler = new CopyOnWriteArrayList<DisconnectHandler>();
public void registerDisconnectHandler(DisconnectHandler handler) {
disconnectHandler.add(handler);
}
public void unregisterDisconnectHandler(DisconnectHandler handler) {
disconnectHandler.remove(handler);
}
private void onDisconnect(int transactionType, Ddeml.HCONV hconv, boolean sameInstance) {
for(DisconnectHandler handler: disconnectHandler) {
handler.onDisconnect(transactionType, hconv, sameInstance);
}
}
private final List<ErrorHandler> errorHandler = new CopyOnWriteArrayList<ErrorHandler>();
public void registerErrorHandler(ErrorHandler handler) {
errorHandler.add(handler);
}
public void unregisterErrorHandler(ErrorHandler handler) {
errorHandler.remove(handler);
}
private void onError(int transactionType, Ddeml.HCONV hconv, int errorCode) {
for(ErrorHandler handler: errorHandler) {
handler.onError(transactionType, hconv, errorCode);
}
}
private final List<RegisterHandler> registerHandler = new CopyOnWriteArrayList<RegisterHandler>();
public void registerRegisterHandler(RegisterHandler handler) {
registerHandler.add(handler);
}
public void unregisterRegisterHandler(RegisterHandler handler) {
registerHandler.remove(handler);
}
private void onRegister(int transactionType, Ddeml.HSZ baseServiceName, Ddeml.HSZ instanceSpecificServiceName) {
for(RegisterHandler handler: registerHandler) {
handler.onRegister(transactionType, baseServiceName, instanceSpecificServiceName);
}
}
private final List<XactCompleteHandler> xactCompleteHandler = new CopyOnWriteArrayList<XactCompleteHandler>();
public void registerXactCompleteHandler(XactCompleteHandler handler) {
xactCompleteHandler.add(handler);
}
public void xactCompleteXactCompleteHandler(XactCompleteHandler handler) {
xactCompleteHandler.remove(handler);
}
private void onXactComplete(int transactionType, int dataFormat, HCONV hConv, HSZ topic, HSZ item, HDDEDATA hdata, ULONG_PTR transactionIdentifier, ULONG_PTR statusFlag) {
for(XactCompleteHandler handler: xactCompleteHandler) {
handler.onXactComplete(transactionType, dataFormat, hConv, topic, item, hdata, transactionIdentifier, statusFlag);
}
}
private final List<UnregisterHandler> unregisterHandler = new CopyOnWriteArrayList<UnregisterHandler>();
public void registerUnregisterHandler(UnregisterHandler handler) {
unregisterHandler.add(handler);
}
public void unregisterUnregisterHandler(UnregisterHandler handler) {
unregisterHandler.remove(handler);
}
private void onUnregister(int transactionType, HSZ baseServiceName, HSZ instanceSpecificServiceName) {
for(UnregisterHandler handler: unregisterHandler) {
handler.onUnregister(transactionType, baseServiceName, instanceSpecificServiceName);
}
}
private final List<MonitorHandler> monitorHandler = new CopyOnWriteArrayList<MonitorHandler>();
public void registerMonitorHandler(MonitorHandler handler) {
monitorHandler.add(handler);
}
public void unregisterMonitorHandler(MonitorHandler handler) {
monitorHandler.remove(handler);
}
private void onMonitor(int transactionType, HDDEDATA hdata, int dwData2) {
for(MonitorHandler handler: monitorHandler) {
handler.onMonitor(transactionType, hdata, dwData2);
}
}
}
/**
* DdemlException wraps error codes reported by the DDEML functions as an
* exception.
*/
public static class DdemlException extends RuntimeException {
private static final Map<Integer,String> ERROR_CODE_MAP;
static {
Map<Integer,String> errorCodeMapBuilder = new HashMap<Integer,String>();
for(Field f: Ddeml.class.getFields()) {
String name = f.getName();
if(name.startsWith("DMLERR_") && (! name.equals("DMLERR_FIRST")) && (! name.equals("DMLERR_LAST"))) {
try {
errorCodeMapBuilder.put(f.getInt(null), name);
} catch (IllegalArgumentException ex) {
throw new RuntimeException(ex);
} catch (IllegalAccessException ex) {
throw new RuntimeException(ex);
}
}
}
ERROR_CODE_MAP = Collections.unmodifiableMap(errorCodeMapBuilder);
}
private final int errorCode;
public static DdemlException create(int errorCode) {
String errorName = ERROR_CODE_MAP.get(errorCode);
return new DdemlException(errorCode, String.format("%s (Code: 0x%X)",
errorName != null ? errorName : "",
errorCode));
}
public DdemlException(int errorCode, String message) {
super(message);
this.errorCode = errorCode;
}
public int getErrorCode() {
return errorCode;
}
}
/**
* The IDdeConnection defines the functions, that work an a concrete
* connection/conversation.
*/
public interface IDdeConnection extends Closeable {
public Ddeml.HCONV getConv();
/**
* Run an XTYP_EXECUTE client transaction.
*
* @param executeString The string passed to the server for execution
* @param timeout The maximum amount of time, in milliseconds, that
* the client will wait for a response from the server application in a
* synchronous transaction. This parameter should be TIMEOUT_ASYNC for
* asynchronous transactions.
* @param result A pointer to a variable that receives the result of
* the transaction. An application that does not check the result can
* use NULL for this value. For synchronous transactions, the low-order
* word of this variable contains any applicable DDE_ flags resulting
* from the transaction. This provides support for applications
* dependent on DDE_APPSTATUS bits. It is, however, recommended that
* applications no longer use these bits because they may not be
* supported in future versions of the Dynamic Data Exchange Management
* Library (DDEML). For asynchronous transactions, this variable is
* filled with a unique transaction identifier for use with the
* DdeAbandonTransaction function and the XTYP_XACT_COMPLETE
* transaction.
* @param userHandle data to associate with the transaction
*
* <p>
* If an error occurs, a DdemlException is raised with the appropriate
* error code:</p>
*
* <ul>
* <li>DMLERR_BUSY</li>
* <li>DMLERR_NOTPROCESSED</li>
* </ul>
*/
public void execute(String executeString, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle);
/**
* Run an XTYP_POKE client transaction
*
* @param data The beginning of the data the client must pass to the
* server.
*
* <p>
* Optionally, an application can specify the data handle (HDDEDATA) to
* pass to the server and in that case the cbData parameter should be
* set to -1. This parameter is required only if the wType parameter is
* XTYP_EXECUTE or XTYP_POKE. Otherwise, this parameter should be
* NULL.</p>
*
* <p>
* For the optional usage of this parameter, XTYP_POKE transactions
* where pData is a data handle, the handle must have been created by a
* previous call to the DdeCreateDataHandle function, employing the same
* data format specified in the wFmt parameter.</p>
*
* @param dataLength The length, in bytes, of the data pointed to by the
* pData parameter, including the terminating NULL, if the data is a
* string. A value of -1 indicates that pData is a data handle that
* identifies the data being sent.
*
* @param item A handle to the data item for which data is being
* exchanged during the transaction. This handle must have been created
* by a previous call to the DdeCreateStringHandle function. This
* parameter is ignored (and should be set to 0L) if the wType parameter
* is XTYP_EXECUTE.
*
* @param wFmt The standard clipboard format in which the data item is
* being submitted or requested.
*
* <p>
* If the transaction specified by the wType parameter does not pass
* data or is XTYP_EXECUTE, this parameter should be zero.</p>
*
* <p>
* If the transaction specified by the wType parameter references
* non-execute DDE data ( XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP,
* XTYP_REQUEST), the wFmt value must be either a valid predefined (CF_)
* DDE format or a valid registered clipboard format.</p>
*
* @param timeout The maximum amount of time, in milliseconds, that
* the client will wait for a response from the server application in a
* synchronous transaction. This parameter should be TIMEOUT_ASYNC for
* asynchronous transactions.
*
* @param userHandle data to associate with the transaction
*
* @param result A pointer to a variable that receives the result of
* the transaction. An application that does not check the result can
* use NULL for this value. For synchronous transactions, the low-order
* word of this variable contains any applicable DDE_ flags resulting
* from the transaction. This provides support for applications
* dependent on DDE_APPSTATUS bits. It is, however, recommended that
* applications no longer use these bits because they may not be
* supported in future versions of the Dynamic Data Exchange Management
* Library (DDEML). For asynchronous transactions, this variable is
* filled with a unique transaction identifier for use with the
* DdeAbandonTransaction function and the XTYP_XACT_COMPLETE
* transaction.
*
* <p>
* If an error occurs, a DdemlException is raised with the appropriate
* error code:</p>
*
* <ul>
* <li>DMLERR_BUSY</li>
* <li>DMLERR_NOTPROCESSED</li>
* </ul>
*/
public void poke(Pointer data, int dataLength, Ddeml.HSZ item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle);
/**
* Run an XTYP_POKE client transaction
*
* @param data The beginning of the data the client must pass to the
* server.
*
* <p>
* Optionally, an application can specify the data handle (HDDEDATA) to
* pass to the server and in that case the cbData parameter should be
* set to -1. This parameter is required only if the wType parameter is
* XTYP_EXECUTE or XTYP_POKE. Otherwise, this parameter should be
* NULL.</p>
*
* <p>
* For the optional usage of this parameter, XTYP_POKE transactions
* where pData is a data handle, the handle must have been created by a
* previous call to the DdeCreateDataHandle function, employing the same
* data format specified in the wFmt parameter.</p>
*
* @param dataLength The length, in bytes, of the data pointed to by the
* pData parameter, including the terminating NULL, if the data is a
* string. A value of -1 indicates that pData is a data handle that
* identifies the data being sent.
*
* @param item The data item for which data is being exchanged during
* the transaction. This parameter is ignored (and should be set to NULL)
* if the wType parameter is XTYP_EXECUTE.
*
* @param wFmt The standard clipboard format in which the data item is
* being submitted or requested.
*
* <p>
* If the transaction specified by the wType parameter does not pass
* data or is XTYP_EXECUTE, this parameter should be zero.</p>
*
* <p>
* If the transaction specified by the wType parameter references
* non-execute DDE data ( XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP,
* XTYP_REQUEST), the wFmt value must be either a valid predefined (CF_)
* DDE format or a valid registered clipboard format.</p>
*
* @param timeout The maximum amount of time, in milliseconds, that
* the client will wait for a response from the server application in a
* synchronous transaction. This parameter should be TIMEOUT_ASYNC for
* asynchronous transactions.
*
* @param userHandle data to associate with the transaction
*
* @param result A pointer to a variable that receives the result of
* the transaction. An application that does not check the result can
* use NULL for this value. For synchronous transactions, the low-order
* word of this variable contains any applicable DDE_ flags resulting
* from the transaction. This provides support for applications
* dependent on DDE_APPSTATUS bits. It is, however, recommended that
* applications no longer use these bits because they may not be
* supported in future versions of the Dynamic Data Exchange Management
* Library (DDEML). For asynchronous transactions, this variable is
* filled with a unique transaction identifier for use with the
* DdeAbandonTransaction function and the XTYP_XACT_COMPLETE
* transaction.
*
* <p>
* If an error occurs, a DdemlException is raised with the appropriate
* error code:</p>
*
* <ul>
* <li>DMLERR_BUSY</li>
* <li>DMLERR_NOTPROCESSED</li>
* </ul>
*/
public void poke(Pointer data, int dataLength, String item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle);
/**
* Begins a data transaction between a client and a server. Only a
* Dynamic Data Exchange (DDE) client application can call this
* function, and the application can use it only after establishing a
* conversation with the server.
*
* @param item A handle to the data item for which data is being
* exchanged during the transaction. This handle must have been created
* by a previous call to the DdeCreateStringHandle function. This
* parameter is ignored (and should be set to 0L) if the wType parameter
* is XTYP_EXECUTE.
*
* @param wFmt The standard clipboard format in which the data item is
* being submitted or requested.
*
* <p>
* If the transaction specified by the wType parameter references
* non-execute DDE data ( XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP,
* XTYP_REQUEST), the wFmt value must be either a valid predefined (CF_)
* DDE format or a valid registered clipboard format.</p>
*
* @param timeout The maximum amount of time, in milliseconds, that
* the client will wait for a response from the server application in a
* synchronous transaction. This parameter should be TIMEOUT_ASYNC for
* asynchronous transactions.
*
* @param result A pointer to a variable that receives the result of
* the transaction. An application that does not check the result can
* use NULL for this value. For synchronous transactions, the low-order
* word of this variable contains any applicable DDE_ flags resulting
* from the transaction. This provides support for applications
* dependent on DDE_APPSTATUS bits. It is, however, recommended that
* applications no longer use these bits because they may not be
* supported in future versions of the Dynamic Data Exchange Management
* Library (DDEML). For asynchronous transactions, this variable is
* filled with a unique transaction identifier for use with the
* DdeAbandonTransaction function and the XTYP_XACT_COMPLETE
* transaction.
*
* @param userHandle data to associate with the transaction
*
* @return If the function succeeds, the return value is a data handle
* that identifies the data for successful synchronous transactions in
* which the client expects data from the server. The return value is
* nonzero for successful asynchronous transactions and for synchronous
* transactions in which the client does not expect data. The return
* value is zero for all unsuccessful transactions.
*
* <p>
* If an error occurs, a DdemlException is raised with the appropriate
* error code:</p>
*
* <ul>
* <li>DMLERR_NOTPROCESSED</li>
* </ul>
*/
public Ddeml.HDDEDATA request(Ddeml.HSZ item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle);
/**
* Begins a data transaction between a client and a server. Only a
* Dynamic Data Exchange (DDE) client application can call this
* function, and the application can use it only after establishing a
* conversation with the server.
*
* @param item The data item for which data is being exchanged during
* the transaction. This parameter is ignored (and should be set to NULL)
* if the wType parameter is XTYP_EXECUTE.
*
* @param wFmt The standard clipboard format in which the data item is
* being submitted or requested.
*
* <p>
* If the transaction specified by the wType parameter references
* non-execute DDE data ( XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP,
* XTYP_REQUEST), the wFmt value must be either a valid predefined (CF_)
* DDE format or a valid registered clipboard format.</p>
*
* @param timeout The maximum amount of time, in milliseconds, that
* the client will wait for a response from the server application in a
* synchronous transaction. This parameter should be TIMEOUT_ASYNC for
* asynchronous transactions.
*
* @param result A pointer to a variable that receives the result of
* the transaction. An application that does not check the result can
* use NULL for this value. For synchronous transactions, the low-order
* word of this variable contains any applicable DDE_ flags resulting
* from the transaction. This provides support for applications
* dependent on DDE_APPSTATUS bits. It is, however, recommended that
* applications no longer use these bits because they may not be
* supported in future versions of the Dynamic Data Exchange Management
* Library (DDEML). For asynchronous transactions, this variable is
* filled with a unique transaction identifier for use with the
* DdeAbandonTransaction function and the XTYP_XACT_COMPLETE
* transaction.
*
* @param userHandle data to associate with the transaction
*
* @return If the function succeeds, the return value is a data handle
* that identifies the data for successful synchronous transactions in
* which the client expects data from the server. The return value is
* nonzero for successful asynchronous transactions and for synchronous
* transactions in which the client does not expect data. The return
* value is zero for all unsuccessful transactions.
*
* <p>
* If an error occurs, a DdemlException is raised with the appropriate
* error code:</p>
*
* <ul>
* <li>DMLERR_NOTPROCESSED</li>
* </ul>
*/
public Ddeml.HDDEDATA request(String item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle);
/**
* Begins a data transaction between a client and a server. Only a
* Dynamic Data Exchange (DDE) client application can call this
* function, and the application can use it only after establishing a
* conversation with the server.
*
* @param data The beginning of the data the client must pass to the
* server.
*
* <p>
* Optionally, an application can specify the data handle (HDDEDATA) to
* pass to the server and in that case the cbData parameter should be
* set to -1. This parameter is required only if the wType parameter is
* XTYP_EXECUTE or XTYP_POKE. Otherwise, this parameter should be
* NULL.</p>
*
* <p>
* For the optional usage of this parameter, XTYP_POKE transactions
* where pData is a data handle, the handle must have been created by a
* previous call to the DdeCreateDataHandle function, employing the same
* data format specified in the wFmt parameter.</p>
*
* @param dataLength The length, in bytes, of the data pointed to by the
* pData parameter, including the terminating NULL, if the data is a
* string. A value of -1 indicates that pData is a data handle that
* identifies the data being sent.
*
* @param item A handle to the data item for which data is being
* exchanged during the transaction. This handle must have been created
* by a previous call to the DdeCreateStringHandle function. This
* parameter is ignored (and should be set to 0L) if the wType parameter
* is XTYP_EXECUTE.
*
* @param wFmt The standard clipboard format in which the data item is
* being submitted or requested.
*
* <p>
* If the transaction specified by the wType parameter does not pass
* data or is XTYP_EXECUTE, this parameter should be zero.</p>
*
* <p>
* If the transaction specified by the wType parameter references
* non-execute DDE data ( XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP,
* XTYP_REQUEST), the wFmt value must be either a valid predefined (CF_)
* DDE format or a valid registered clipboard format.</p>
*
* @param transaction The transaction type. This parameter can be one of the
* following values.
*
* <table>
* <tr><th>Value</th><th>Meaning</th></tr>
* <tr><td>XTYP_ADVSTART</td><td>Begins an advise loop. Any number of
* distinct advise loops can exist within a conversation. An application
* can alter the advise loop type by combining the XTYP_ADVSTART
* transaction type with one or more of the following flags:
* <dl>
* <dt>XTYPF_NODATA.</dt><dd>Instructs the server to notify the client
* of any data changes without actually sending the data. This flag
* gives the client the option of ignoring the notification or
* requesting the changed data from the server.</dd>
* <dt>XTYPF_ACKREQ.</dt><dd>Instructs the server to wait until the
* client acknowledges that it received the previous data item before
* sending the next data item. This flag prevents a fast server from
* sending data faster than the client can process it.</dd>
* </dl>
* </td></tr>
* <tr><td>XTYP_ADVSTOP</td><td>Ends an advise loop.</td></tr>
* <tr><td>XTYP_EXECUTE</td><td>Begins an execute transaction.</td></tr>
* <tr><td>XTYP_POKE</td><td>Begins a poke transaction.</td></tr>
* <tr><td>XTYP_REQUEST</td><td>Begins a request transaction.</td></tr>
* </table>
*
* @param timeout The maximum amount of time, in milliseconds, that
* the client will wait for a response from the server application in a
* synchronous transaction. This parameter should be TIMEOUT_ASYNC for
* asynchronous transactions.
*
* @param result A pointer to a variable that receives the result of
* the transaction. An application that does not check the result can
* use NULL for this value. For synchronous transactions, the low-order
* word of this variable contains any applicable DDE_ flags resulting
* from the transaction. This provides support for applications
* dependent on DDE_APPSTATUS bits. It is, however, recommended that
* applications no longer use these bits because they may not be
* supported in future versions of the Dynamic Data Exchange Management
* Library (DDEML). For asynchronous transactions, this variable is
* filled with a unique transaction identifier for use with the
* DdeAbandonTransaction function and the XTYP_XACT_COMPLETE
* transaction.
*
* @param userHandle data to associate with the transaction
*
* @return If the function succeeds, the return value is a data handle
* that identifies the data for successful synchronous transactions in
* which the client expects data from the server. The return value is
* nonzero for successful asynchronous transactions and for synchronous
* transactions in which the client does not expect data. The return
* value is zero for all unsuccessful transactions.
*
* <p>
* If an error occurs, a DdemlException is raised with the appropriate
* error code:</p>
*
* <ul>
* <li>DMLERR_ADVACKTIMEOUT</li>
* <li>DMLERR_BUSY</li>
* <li>DMLERR_DATAACKTIMEOUT</li>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_EXECACKTIMEOUT</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_MEMORY_ERROR</li>
* <li>DMLERR_NO_CONV_ESTABLISHED</li>
* <li>DMLERR_NO_ERROR</li>
* <li>DMLERR_NOTPROCESSED</li>
* <li>DMLERR_POKEACKTIMEOUT</li>
* <li>DMLERR_POSTMSG_FAILED</li>
* <li>DMLERR_REENTRANCY</li>
* <li>DMLERR_SERVER_DIED</li>
* <li>DMLERR_UNADVACKTIMEOUT</li>
* </ul>
*/
public Ddeml.HDDEDATA clientTransaction(Pointer data, int dataLength, Ddeml.HSZ item, int wFmt, int transaction, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle);
/**
* Begins a data transaction between a client and a server. Only a
* Dynamic Data Exchange (DDE) client application can call this
* function, and the application can use it only after establishing a
* conversation with the server.
*
* @param data The beginning of the data the client must pass to the
* server.
*
* <p>
* Optionally, an application can specify the data handle (HDDEDATA) to
* pass to the server and in that case the cbData parameter should be
* set to -1. This parameter is required only if the wType parameter is
* XTYP_EXECUTE or XTYP_POKE. Otherwise, this parameter should be
* NULL.</p>
*
* <p>
* For the optional usage of this parameter, XTYP_POKE transactions
* where pData is a data handle, the handle must have been created by a
* previous call to the DdeCreateDataHandle function, employing the same
* data format specified in the wFmt parameter.</p>
*
* @param dataLength The length, in bytes, of the data pointed to by the
* pData parameter, including the terminating NULL, if the data is a
* string. A value of -1 indicates that pData is a data handle that
* identifies the data being sent.
*
* @param item The data item for which data is being exchanged during
* the transaction. This parameter is ignored (and should be set to NULL)
* if the wType parameter is XTYP_EXECUTE.
*
* @param wFmt The standard clipboard format in which the data item is
* being submitted or requested.
*
* <p>
* If the transaction specified by the wType parameter does not pass
* data or is XTYP_EXECUTE, this parameter should be zero.</p>
*
* <p>
* If the transaction specified by the wType parameter references
* non-execute DDE data ( XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP,
* XTYP_REQUEST), the wFmt value must be either a valid predefined (CF_)
* DDE format or a valid registered clipboard format.</p>
*
* @param transaction The transaction type. This parameter can be one of the
* following values.
*
* <table>
* <tr><th>Value</th><th>Meaning</th></tr>
* <tr><td>XTYP_ADVSTART</td><td>Begins an advise loop. Any number of
* distinct advise loops can exist within a conversation. An application
* can alter the advise loop type by combining the XTYP_ADVSTART
* transaction type with one or more of the following flags:
* <dl>
* <dt>XTYPF_NODATA.</dt><dd>Instructs the server to notify the client
* of any data changes without actually sending the data. This flag
* gives the client the option of ignoring the notification or
* requesting the changed data from the server.</dd>
* <dt>XTYPF_ACKREQ.</dt><dd>Instructs the server to wait until the
* client acknowledges that it received the previous data item before
* sending the next data item. This flag prevents a fast server from
* sending data faster than the client can process it.</dd>
* </dl>
* </td></tr>
* <tr><td>XTYP_ADVSTOP</td><td>Ends an advise loop.</td></tr>
* <tr><td>XTYP_EXECUTE</td><td>Begins an execute transaction.</td></tr>
* <tr><td>XTYP_POKE</td><td>Begins a poke transaction.</td></tr>
* <tr><td>XTYP_REQUEST</td><td>Begins a request transaction.</td></tr>
* </table>
*
* @param timeout The maximum amount of time, in milliseconds, that
* the client will wait for a response from the server application in a
* synchronous transaction. This parameter should be TIMEOUT_ASYNC for
* asynchronous transactions.
*
* @param result A pointer to a variable that receives the result of
* the transaction. An application that does not check the result can
* use NULL for this value. For synchronous transactions, the low-order
* word of this variable contains any applicable DDE_ flags resulting
* from the transaction. This provides support for applications
* dependent on DDE_APPSTATUS bits. It is, however, recommended that
* applications no longer use these bits because they may not be
* supported in future versions of the Dynamic Data Exchange Management
* Library (DDEML). For asynchronous transactions, this variable is
* filled with a unique transaction identifier for use with the
* DdeAbandonTransaction function and the XTYP_XACT_COMPLETE
* transaction.
*
* @param userHandle data to associate with the transaction
*
* @return If the function succeeds, the return value is a data handle
* that identifies the data for successful synchronous transactions in
* which the client expects data from the server. The return value is
* nonzero for successful asynchronous transactions and for synchronous
* transactions in which the client does not expect data. The return
* value is zero for all unsuccessful transactions.
*
* <p>
* If an error occurs, a DdemlException is raised with the appropriate
* error code:</p>
*
* <ul>
* <li>DMLERR_ADVACKTIMEOUT</li>
* <li>DMLERR_BUSY</li>
* <li>DMLERR_DATAACKTIMEOUT</li>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_EXECACKTIMEOUT</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_MEMORY_ERROR</li>
* <li>DMLERR_NO_CONV_ESTABLISHED</li>
* <li>DMLERR_NO_ERROR</li>
* <li>DMLERR_NOTPROCESSED</li>
* <li>DMLERR_POKEACKTIMEOUT</li>
* <li>DMLERR_POSTMSG_FAILED</li>
* <li>DMLERR_REENTRANCY</li>
* <li>DMLERR_SERVER_DIED</li>
* <li>DMLERR_UNADVACKTIMEOUT</li>
* </ul>
*/
public Ddeml.HDDEDATA clientTransaction(Pointer data, int dataLength, String item, int wFmt, int transaction, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle);
/**
* Begins a data transaction between a client and a server. Only a
* Dynamic Data Exchange (DDE) client application can call this
* function, and the application can use it only after establishing a
* conversation with the server.
*
* @param item A handle to the data item for which data is being
* exchanged during the transaction. This handle must have been created
* by a previous call to the DdeCreateStringHandle function. This
* parameter is ignored (and should be set to 0L) if the wType parameter
* is XTYP_EXECUTE.
*
* @param wFmt The standard clipboard format in which the data item is
* being submitted or requested.
*
* @param timeout The maximum amount of time, in milliseconds, that
* the client will wait for a response from the server application in a
* synchronous transaction. This parameter should be TIMEOUT_ASYNC for
* asynchronous transactions.
*
* @param result A pointer to a variable that receives the result of
* the transaction. An application that does not check the result can
* use NULL for this value. For synchronous transactions, the low-order
* word of this variable contains any applicable DDE_ flags resulting
* from the transaction. This provides support for applications
* dependent on DDE_APPSTATUS bits. It is, however, recommended that
* applications no longer use these bits because they may not be
* supported in future versions of the Dynamic Data Exchange Management
* Library (DDEML). For asynchronous transactions, this variable is
* filled with a unique transaction identifier for use with the
* DdeAbandonTransaction function and the XTYP_XACT_COMPLETE
* transaction.
*
* @param userHandle data to associate with the transaction
*
* <p>
* If an error occurs, a DdemlException is raised with the appropriate
* error code:</p>
*
* <ul>
* <li>DMLERR_NOTPROCESSED</li>
* </ul>
*/
public void advstart(Ddeml.HSZ item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle);
/**
* Begins a data transaction between a client and a server. Only a
* Dynamic Data Exchange (DDE) client application can call this
* function, and the application can use it only after establishing a
* conversation with the server.
*
* @param item The data item for which data is being exchanged during
* the transaction. This parameter is ignored (and should be set to NULL)
* if the wType parameter is XTYP_EXECUTE.
*
* @param wFmt The standard clipboard format in which the data item is
* being submitted or requested.
*
* @param timeout The maximum amount of time, in milliseconds, that
* the client will wait for a response from the server application in a
* synchronous transaction. This parameter should be TIMEOUT_ASYNC for
* asynchronous transactions.
*
* @param result A pointer to a variable that receives the result of
* the transaction. An application that does not check the result can
* use NULL for this value. For synchronous transactions, the low-order
* word of this variable contains any applicable DDE_ flags resulting
* from the transaction. This provides support for applications
* dependent on DDE_APPSTATUS bits. It is, however, recommended that
* applications no longer use these bits because they may not be
* supported in future versions of the Dynamic Data Exchange Management
* Library (DDEML). For asynchronous transactions, this variable is
* filled with a unique transaction identifier for use with the
* DdeAbandonTransaction function and the XTYP_XACT_COMPLETE
* transaction.
*
* @param userHandle data to associate with the transaction
*
* <p>
* If an error occurs, a DdemlException is raised with the appropriate
* error code:</p>
*
* <ul>
* <li>DMLERR_NOTPROCESSED</li>
* </ul>
*/
public void advstart(String item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle);
/**
* A client uses the XTYP_ADVSTOP transaction to end an advise loop with
* a server. A Dynamic Data Exchange (DDE) server callback function,
* DdeCallback, receives this transaction when a client specifies
* XTYP_ADVSTOP in the DdeClientTransaction function.
*
* @param item A handle to the data item for which data is being
* exchanged during the transaction. This handle must have been created
* by a previous call to the DdeCreateStringHandle function. This
* parameter is ignored (and should be set to 0L) if the wType parameter
* is XTYP_EXECUTE.
*
* @param wFmt The standard clipboard format in which the data item is
* being submitted or requested.
*
* @param timeout The maximum amount of time, in milliseconds, that
* the client will wait for a response from the server application in a
* synchronous transaction. This parameter should be TIMEOUT_ASYNC for
* asynchronous transactions.
*
* @param result A pointer to a variable that receives the result of
* the transaction. An application that does not check the result can
* use NULL for this value. For synchronous transactions, the low-order
* word of this variable contains any applicable DDE_ flags resulting
* from the transaction. This provides support for applications
* dependent on DDE_APPSTATUS bits. It is, however, recommended that
* applications no longer use these bits because they may not be
* supported in future versions of the Dynamic Data Exchange Management
* Library (DDEML). For asynchronous transactions, this variable is
* filled with a unique transaction identifier for use with the
* DdeAbandonTransaction function and the XTYP_XACT_COMPLETE
* transaction.
*
* @param userHandle data to associate with the transaction
*
* <p>
* If an error occurs, a DdemlException is raised with the appropriate
* error code:</p>
*
* <ul>
* <li>DMLERR_NOTPROCESSED</li>
* </ul>
*/
public void advstop(Ddeml.HSZ item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle);
/**
* A client uses the XTYP_ADVSTOP transaction to end an advise loop with
* a server. A Dynamic Data Exchange (DDE) server callback function,
* DdeCallback, receives this transaction when a client specifies
* XTYP_ADVSTOP in the DdeClientTransaction function.
*
* @param item The data item for which data is being exchanged during
* the transaction. This parameter is ignored (and should be set to NULL)
* if the wType parameter is XTYP_EXECUTE.
*
* @param wFmt The standard clipboard format in which the data item is
* being submitted or requested.
*
* @param timeout The maximum amount of time, in milliseconds, that
* the client will wait for a response from the server application in a
* synchronous transaction. This parameter should be TIMEOUT_ASYNC for
* asynchronous transactions.
*
* @param result A pointer to a variable that receives the result of
* the transaction. An application that does not check the result can
* use NULL for this value. For synchronous transactions, the low-order
* word of this variable contains any applicable DDE_ flags resulting
* from the transaction. This provides support for applications
* dependent on DDE_APPSTATUS bits. It is, however, recommended that
* applications no longer use these bits because they may not be
* supported in future versions of the Dynamic Data Exchange Management
* Library (DDEML). For asynchronous transactions, this variable is
* filled with a unique transaction identifier for use with the
* DdeAbandonTransaction function and the XTYP_XACT_COMPLETE
* transaction.
*
* @param userHandle data to associate with the transaction
*
* <p>
* If an error occurs, a DdemlException is raised with the appropriate
* error code:</p>
*
* <ul>
* <li>DMLERR_NOTPROCESSED</li>
* </ul>
*/
public void advstop(String item, int wFmt, int timeout, WinDef.DWORDByReference result, DWORD_PTR userHandle);
/**
* Abandons the specified asynchronous transaction and releases all
* resources associated with the transaction.
*
* @param transactionId The identifier of the transaction to be
* abandoned. If this parameter is 0L, all active transactions in the
* specified conversation are abandoned.
*
* <p>
* If the method fails a DdeException will be raised with the
* corresponding errorCode:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* <li>DMLERR_UNFOUND_QUEUE_ID</li>
* </ul>
*/
public void abandonTransaction(int transactionId);
/**
* Abandons all transactions of this conversation and releases all
* resources associated with the transaction.
*
* <p>
* If the method fails a DdeException will be raised with the
* corresponding errorCode:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* <li>DMLERR_UNFOUND_QUEUE_ID</li>
* </ul>
*/
public void abandonTransactions();
/**
* Impersonates a Dynamic Data Exchange (DDE) client application in a
* DDE client conversation.
*/
public void impersonateClient();
/**
* Terminates a conversation started by either the DdeConnect or
* DdeConnectList function and invalidates the specified conversation
* handle.
*
* <p>Note: This wraps the DdeDisconnect function and aligns the name
* with the Closable-wording.</p>
*
* <p>
* If the method fails a DdeException will be raised with the
* corresponding errorCode:</p>
*
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_NO_CONV_ESTABLISHED</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public void close();
/**
* Enables a client Dynamic Data Exchange Management Library (DDEML)
* application to attempt to reestablish a conversation with a service
* that has terminated a conversation with the client. When the
* conversation is reestablished, the Dynamic Data Exchange Management
* Library (DDEML) attempts to reestablish any preexisting advise loops.
*
* <p>
* If the method fails a DdeException will be raised with the
* corresponding errorCode:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_CONV_ESTABLISHED</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public void reconnect();
/**
* Enables or disables transactions for a specific conversation or for
* all conversations currently established by the calling application.
*
* @param wCmd The function code. This parameter can be one of the
* following values.
* <table>
* <tr><th>Value</th><th>Meaning</th></tr>
* <tr><td>EC_ENABLEALL</td><td>Enables all transactions for the
* specified conversation.</td></tr>
* <tr><td>EC_ENABLEONE</td><td>Enables one transaction for the
* specified conversation.</td></tr>
* <tr><td>EC_DISABLE</td><td>Disables all blockable transactions for
* the specified conversation.
*
* <p>
* A server application can disable the following transactions:</p>
* <ul>
* <li>XTYP_ADVSTART</li>
* <li>XTYP_ADVSTOP</li>
* <li>XTYP_EXECUTE</li>
* <li>XTYP_POKE</li>
* <li>XTYP_REQUEST</li>
* </ul>
* <p>
* A client application can disable the following transactions:</p>
* <ul>
* <li>XTYP_ADVDATA</li>
* <li>XTYP_XACT_COMPLETE</li>
* </ul>
* </td></tr>
* <tr><td>EC_QUERYWAITING</td><td>Determines whether any transactions
* are in the queue for the specified conversation.</td></tr>
* </table>
*
* @return If the function succeeds, the return value is nonzero.
*
* <p>
* If the function fails, the return value is zero.</p>
*
* <p>
* If the wCmd parameter is EC_QUERYWAITING, and the application
* transaction queue contains one or more unprocessed transactions that
* are not being processed, the return value is TRUE; otherwise, it is
* FALSE.</p>
*
* <p>
* If the method fails a DdeException will be raised with the
* corresponding errorCode:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public boolean enableCallback(int wCmd);
/**
* Associates an application-defined value with a conversation handle or
* a transaction identifier. This is useful for simplifying the
* processing of asynchronous transactions. An application can use the
* DdeQueryConvInfo function to retrieve this value.
*
* @param id The transaction identifier to associate with the value
* specified by the hUser parameter. An application should set this
* parameter to QID_SYNC to associate hUser with the conversation
* identified by the hConv parameter.
* @param hUser The value to be associated with the conversation handle.
*
* <p>
* If the method fails a DdeException will be raised with the
* corresponding errorCode:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* <li>DMLERR_UNFOUND_QUEUE_ID</li>
* </ul>
*/
public void setUserHandle(int id, DWORD_PTR hUser) throws DdemlException;
/**
* Retrieves information about a Dynamic Data Exchange (DDE) transaction
* and about the conversation in which the transaction takes place.
*
* @param idTransaction The transaction. For asynchronous transactions,
* this parameter should be a transaction identifier returned by the
* DdeClientTransaction function. For synchronous transactions, this
* parameter should be QID_SYNC.
* @return The CONVINFO structure
*
* <p>
* If the method fails a DdeException will be raised with the
* corresponding errorCode:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_NO_CONV_ESTABLISHED</li>
* <li>DMLERR_NO_ERROR</li>
* <li>DMLERR_UNFOUND_QUEUE_ID</li>
* </ul>
*/
public CONVINFO queryConvInfo(int idTransaction) throws DdemlException;
}
/**
* The IDdeClient defines functions that wrap a ddeml instance. and are
* not tied to conversation.
*/
public interface IDdeClient extends Closeable {
public Integer getInstanceIdentitifier();
/**
* Registers an application with the Dynamic Data Exchange Management
* Library (DDEML). An application must call this function before
* calling any other Dynamic Data Exchange Management Library (DDEML)
* function.
*
* @param afCmd A set of APPCMD_, CBF_, and MF_ flags. The APPCMD_ flags
* provide special instructions to DdeInitialize. The CBF_ flags specify
* filters that prevent specific types of transactions from reaching the
* callback function. The MF_ flags specify the types of DDE activity
* that a DDE monitoring application monitors. Using these flags
* enhances the performance of a DDE application by eliminating
* unnecessary calls to the callback function.
*
* <p>
* This parameter can be one or more of the following values.</p>
*
* <table>
* <tr ><th>Value</th><th>Meaning</th></tr>
* <tr><td><dl>
* <dt><strong>APPCLASS_MONITOR</strong></dt>
* <dt>0x00000001L</dt>
* </dl>
* </td><td>
* <p>
* Makes it possible for the application to monitor DDE activity in the
* system. This flag is for use by DDE monitoring applications. The
* application specifies the types of DDE activity to monitor by
* combining one or more monitor flags with the APPCLASS_MONITOR flag.
* For details, see the following Remarks section.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>APPCLASS_STANDARD</strong></dt>
* <dt>0x00000000L</dt>
* </dl>
* </td><td>
* <p>
* Registers the application as a standard (nonmonitoring) DDEML
* application.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>APPCMD_CLIENTONLY</strong></dt>
* <dt>0x00000010L</dt>
* </dl>
* </td><td>
* <p>
* Prevents the application from becoming a server in a DDE
* conversation. The application can only be a client. This flag reduces
* consumption of resources by the DDEML. It includes the functionality
* of the CBF_FAIL_ALLSVRXACTIONS flag.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>APPCMD_FILTERINITS</strong></dt>
* <dt>0x00000020L</dt>
* </dl>
* </td><td>
* <p>
* Prevents the DDEML from sending XTYP_CONNECT and XTYP_WILDCONNECT
* transactions to the application until the application has created its
* string handles and registered its service names or has turned off
* filtering by a subsequent call to the DdeNameService or DdeInitialize
* function. This flag is always in effect when an application calls
* DdeInitialize for the first time, regardless of whether the
* application specifies the flag. On subsequent calls to DdeInitialize,
* not specifying this flag turns off the application's service-name
* filters, but specifying it turns on the application's service name
* filters.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>CBF_FAIL_ALLSVRXACTIONS</strong></dt>
* <dt>0x0003f000</dt>
* </dl>
* </td><td>
* <p>
* Prevents the callback function from receiving server transactions.
* The system returns DDE_FNOTPROCESSED to each client that sends a
* transaction to this application. This flag is equivalent to combining
* all CBF_FAIL_ flags.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>CBF_FAIL_ADVISES</strong></dt>
* <dt>0x00004000</dt>
* </dl>
* </td><td>
* <p>
* Prevents the callback function from receiving XTYP_ADVSTART and
* XTYP_ADVSTOP transactions. The system returns DDE_FNOTPROCESSED to
* each client that sends an XTYP_ADVSTART or XTYP_ADVSTOP transaction
* to the server.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>CBF_FAIL_CONNECTIONS</strong></dt>
* <dt>0x00002000</dt>
* </dl>
* </td><td>
* <p>
* Prevents the callback function from receiving XTYP_CONNECT and
* XTYP_WILDCONNECT transactions.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>CBF_FAIL_EXECUTES</strong></dt>
* <dt>0x00008000</dt>
* </dl>
* </td><td>
* <p>
* Prevents the callback function from receiving XTYP_EXECUTE
* transactions. The system returns DDE_FNOTPROCESSED to a client that
* sends an XTYP_EXECUTE transaction to the server.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>CBF_FAIL_POKES</strong></dt>
* <dt>0x00010000</dt>
* </dl>
* </td><td>
* <p>
* Prevents the callback function from receiving XTYP_POKE transactions.
* The system returns DDE_FNOTPROCESSED to a client that sends an
* XTYP_POKE transaction to the server.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>CBF_FAIL_REQUESTS</strong></dt>
* <dt>0x00020000</dt>
* </dl>
* </td><td>
* <p>
* Prevents the callback function from receiving XTYP_REQUEST
* transactions. The system returns DDE_FNOTPROCESSED to a client that
* sends an XTYP_REQUEST transaction to the server.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>CBF_FAIL_SELFCONNECTIONS</strong></dt>
* <dt>0x00001000</dt>
* </dl>
* </td><td>
* <p>
* Prevents the callback function from receiving XTYP_CONNECT
* transactions from the application's own instance. This flag prevents
* an application from establishing a DDE conversation with its own
* instance. An application should use this flag if it needs to
* communicate with other instances of itself but not with itself.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>CBF_SKIP_ALLNOTIFICATIONS</strong></dt>
* <dt>0x003c0000</dt>
* </dl>
* </td><td>
* <p>
* Prevents the callback function from receiving any notifications. This
* flag is equivalent to combining all CBF_SKIP_ flags.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>CBF_SKIP_CONNECT_CONFIRMS</strong></dt>
* <dt>0x00040000</dt>
* </dl>
* </td><td>
* <p>
* Prevents the callback function from receiving XTYP_CONNECT_CONFIRM
* notifications.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>CBF_SKIP_DISCONNECTS</strong></dt>
* <dt>0x00200000</dt>
* </dl>
* </td><td>
* <p>
* Prevents the callback function from receiving XTYP_DISCONNECT
* notifications.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>CBF_SKIP_REGISTRATIONS</strong></dt>
* <dt>0x00080000</dt>
* </dl>
* </td><td>
* <p>
* Prevents the callback function from receiving XTYP_REGISTER
* notifications.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>CBF_SKIP_UNREGISTRATIONS</strong></dt>
* <dt>0x00100000</dt>
* </dl>
* </td><td>
* <p>
* Prevents the callback function from receiving XTYP_UNREGISTER
* notifications.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>MF_CALLBACKS</strong></dt>
* <dt>0x08000000</dt>
* </dl>
* </td><td>
* <p>
* Notifies the callback function whenever a transaction is sent to any
* DDE callback function in the system.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>MF_CONV</strong></dt>
* <dt>0x40000000</dt>
* </dl>
* </td><td>
* <p>
* Notifies the callback function whenever a conversation is established
* or terminated.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>MF_ERRORS</strong></dt>
* <dt>0x10000000</dt>
* </dl>
* </td><td>
* <p>
* Notifies the callback function whenever a DDE error occurs.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>MF_HSZ_INFO</strong></dt>
* <dt>0x01000000</dt>
* </dl>
* </td><td>
* <p>
* Notifies the callback function whenever a DDE application creates,
* frees, or increments the usage count of a string handle or whenever a
* string handle is freed as a result of a call to the DdeUninitialize
* function.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>MF_LINKS</strong></dt>
* <dt>0x20000000</dt>
* </dl>
* </td><td>
* <p>
* Notifies the callback function whenever an advise loop is started or
* ended.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>MF_POSTMSGS</strong></dt>
* <dt>0x04000000</dt>
* </dl>
* </td><td>
* <p>
* Notifies the callback function whenever the system or an application
* posts a DDE message.</p>
* </td></tr>
* <tr><td><dl>
* <dt><strong>MF_SENDMSGS</strong></dt>
* <dt>0x02000000</dt>
* </dl>
* </td><td>
* <p>
* Notifies the callback function whenever the system or an application
* sends a DDE message.</p>
* </td></tr>
* </table>
*
* <p>
* If the function failsa DdemlException is raised with one of the
* following errroCodes:</p>
* <ul>
* <li>DMLERR_DLL_USAGE</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_SYS_ERROR</li>
* </ul>
*/
public void initialize(int afCmd) throws DdemlException;
/**
* Creates a handle that identifies the specified string. A Dynamic Data
* Exchange (DDE) client or server application can pass the string
* handle as a parameter to other Dynamic Data Exchange Management
* Library (DDEML) functions.
*
* @param value The string for which a handle is to be
* created. This string can be up to 255 characters. The reason for this
* limit is that DDEML string management functions are implemented using
* atoms.
*
* @return If the function succeeds, the return value is a string
* handle. A parameter NULL will cause NULL to be returned.
*
* <p>If the function fails, a DdemlException is raised with the
* corresponding errorCode:</p>
* <ul>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* <li>DMLERR_SYS_ERROR</li>
* </ul>
*/
public Ddeml.HSZ createStringHandle(String value) throws DdemlException;
/**
* Copies text associated with a string handle into a buffer.
*
* @param value A handle to the string to copy. This handle must have been
* created by a previous call to the DdeCreateStringHandle function.
* @return String corresponding to the supplied handle
*/
public String queryString(Ddeml.HSZ value) throws DdemlException;
/**
* Frees a string handle in the calling application.
*
* @param value A handle to the string handle to be freed. This handle
* must have been created by a previous call to the
* createStringHandle function. A NULL value will be silently ignored.
*
* @return true if the function succeeds.
*/
public boolean freeStringHandle(Ddeml.HSZ value);
/**
* Increments the usage count associated with the specified handle. This
* function enables an application to save a string handle passed to the
* application's Dynamic Data Exchange (DDE) callback function.
* Otherwise, a string handle passed to the callback function is deleted
* when the callback function returns. This function should also be used
* to keep a copy of a string handle referenced by the CONVINFO
* structure returned by the DdeQueryConvInfo function.
*
* @param value A handle to the string handle to be saved.
* @return true if the function succeeded
*/
public boolean keepStringHandle(Ddeml.HSZ value);
/**
* Registers or unregisters the service names a Dynamic Data Exchange
* (DDE) server supports. This function causes the system to send
* XTYP_REGISTER or XTYP_UNREGISTER transactions to other running
* Dynamic Data Exchange Management Library (DDEML) client applications.
*
* @param name A handle to the string that specifies the service name
* the server is registering or unregistering. An application that is
* unregistering all of its service names should set this parameter to
* 0L.
* @param afCmd The service name options. This parameter can be one of
* the following values.
*
* <table>
* <tr><th>Value</th><th>Meaning</th></tr>
* <tr><td>DNS_REGISTER</td><td>Registers the error code service
* name.</td></tr>
* <tr><td>DNS_UNREGISTER</td><td>Unregisters the error code service
* name. If the hsz1 parameter is 0L, all service names registered by
* the server will be unregistered.</td></tr>
* <tr><td>DNS_FILTERON</td><td>Turns on service name initiation
* filtering. The filter prevents a server from receiving XTYP_CONNECT
* transactions for service names it has not registered. This is the
* default setting for this filter.
* <br><br>
* If a server application does not register any service names, the
* application cannot receive XTYP_WILDCONNECT transactions.
* </td></tr>
* <tr><td>DNS_FILTEROFF</td><td>Turns off service name initiation
* filtering. If this flag is specified, the server receives an
* XTYP_CONNECT transaction whenever another DDE application calls the
* DdeConnect function, regardless of the service name.</td></tr>
* </table>
* <p>
* If the function fails, a DdemlException is raised with the
* corresponding errorCode:</p>
*
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_DLL_USAGE</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public void nameService(Ddeml.HSZ name, int afCmd) throws DdemlException;
/**
* Registers or unregisters the service names a Dynamic Data Exchange
* (DDE) server supports. This function causes the system to send
* XTYP_REGISTER or XTYP_UNREGISTER transactions to other running
* Dynamic Data Exchange Management Library (DDEML) client applications.
*
* @param name A string that specifies the service name the server is
* registering or unregistering. An application that is unregistering
* all of its service names should set this parameter to NULL.
* @param afCmd The service name options. This parameter can be one of
* the following values.
*
* <table>
* <tr><th>Value</th><th>Meaning</th></tr>
* <tr><td>DNS_REGISTER</td><td>Registers the error code service
* name.</td></tr>
* <tr><td>DNS_UNREGISTER</td><td>Unregisters the error code service
* name. If the hsz1 parameter is 0L, all service names registered by
* the server will be unregistered.</td></tr>
* <tr><td>DNS_FILTERON</td><td>Turns on service name initiation
* filtering. The filter prevents a server from receiving XTYP_CONNECT
* transactions for service names it has not registered. This is the
* default setting for this filter.
* <br><br>
* If a server application does not register any service names, the
* application cannot receive XTYP_WILDCONNECT transactions.
* </td></tr>
* <tr><td>DNS_FILTEROFF</td><td>Turns off service name initiation
* filtering. If this flag is specified, the server receives an
* XTYP_CONNECT transaction whenever another DDE application calls the
* DdeConnect function, regardless of the service name.</td></tr>
* </table>
* <p>
* If the function fails, a DdemlException is raised with the
* corresponding errorCode:</p>
*
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_DLL_USAGE</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public void nameService(String name, int afCmd) throws DdemlException;
/**
* @return See {@link Ddeml}.DMLERR_*
*/
public int getLastError();
/**
* Establishes a conversation with a server application that supports
* the specified service name and topic name pair. If more than one such
* server exists, the system selects only one.
*
* @param service A handle to the string that specifies the service
* name of the server application with which a conversation is to be
* established. This handle must have been created by a previous call to
* the DdeCreateStringHandle function. If this parameter is 0L, a
* conversation is established with any available server.
*
* @param topic A handle to the string that specifies the name of the
* topic on which a conversation is to be established. This handle must
* have been created by a previous call to DdeCreateStringHandle. If
* this parameter is 0L, a conversation on any topic supported by the
* selected server is established.
*
* @param convcontext A pointer to the CONVCONTEXT structure that contains
* conversation context information. If this parameter is NULL, the
* server receives the default CONVCONTEXT structure during the
* XTYP_CONNECT or XTYP_WILDCONNECT transaction.
*
* @return an established connection
*
* <p>If the function fails, a DdemlException is raised with the
* corresponding errorCode:</p>
*
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_CONV_ESTABLISHED</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public IDdeConnection connect(Ddeml.HSZ service, Ddeml.HSZ topic, Ddeml.CONVCONTEXT convcontext);
/**
* Establishes a conversation with a server application that supports
* the specified service name and topic name pair. If more than one such
* server exists, the system selects only one.
*
* @param service The service name of the server application with which
* a conversation is to be established. If this parameter is NULL, a
* conversation is established with any available server.
*
* @param topic The name of the topic on which a conversation is to be
* established. If this parameter is NULL, a conversation on any topic
* supported by the selected server is established.
*
* @param convcontext A pointer to the CONVCONTEXT structure that contains
* conversation context information. If this parameter is NULL, the
* server receives the default CONVCONTEXT structure during the
* XTYP_CONNECT or XTYP_WILDCONNECT transaction.
*
* @return an established connection
*
* <p>If the function fails, a DdemlException is raised with the
* corresponding errorCode:</p>
*
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_CONV_ESTABLISHED</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public IDdeConnection connect(String service, String topic, Ddeml.CONVCONTEXT convcontext);
/**
* Creates a Dynamic Data Exchange (DDE) object and fills the object
* with data from the specified buffer. A DDE application uses this
* function during transactions that involve passing data to the partner
* application.
*
* @param pSrc The data to be copied to the DDE object. If this
* parameter is NULL, no data is copied to the object.
*
* @param cb The amount of memory, in bytes, to copy from the buffer
* pointed to by pSrc. (include the terminating NULL, if the data is a
* string). If this parameter is zero, the pSrc parameter is ignored.
*
* @param cbOff An offset, in bytes, from the beginning of the buffer
* pointed to by the pSrc parameter. The data beginning at this offset
* is copied from the buffer to the DDE object.
*
* @param hszItem A handle to the string that specifies the data item
* corresponding to the DDE object. This handle must have been created
* by a previous call to the DdeCreateStringHandle function. If the data
* handle is to be used in an XTYP_EXECUTE transaction, this parameter
* must be 0L.
*
* @param wFmt The standard clipboard format of the data.
*
* @param afCmd The creation flags. This parameter can be
* HDATA_APPOWNED, which specifies that the server application calling
* the DdeCreateDataHandle function owns the data handle this function
* creates. This flag enables the application to share the data handle
* with other DDEML applications rather than creating a separate handle
* to pass to each application. If this flag is specified, the
* application must eventually free the shared memory object associated
* with the handle by using the DdeFreeDataHandle function. If this flag
* is not specified, the handle becomes invalid in the application that
* created the handle after the data handle is returned by the
* application's DDE callback function or is used as a parameter in
* another DDEML function.
*
* @return If the function succeeds, the return value is a data handle.
*
* <p>
* If the function fails a DdeException is raised with the following
* errorCodes:</p>
*
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_MEMORY_ERROR</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public Ddeml.HDDEDATA createDataHandle(
Pointer pSrc,
int cb,
int cbOff,
Ddeml.HSZ hszItem,
int wFmt,
int afCmd);
/**
* Frees a Dynamic Data Exchange (DDE) object and deletes the data
* handle associated with the object.
*
* @param hData A handle to the DDE object to be freed. This handle must
* have been created by a previous call to the DdeCreateDataHandle
* function or returned by the DdeClientTransaction function.
*
* <p>
* If the function fails a DdeException is raised with the following
* errorCodes:</p>
*
* <ul>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public void freeDataHandle(Ddeml.HDDEDATA hData);
/**
* Adds data to the specified Dynamic Data Exchange (DDE) object. An
* application can add data starting at any offset from the beginning of
* the object. If new data overlaps data already in the object, the new
* data overwrites the old data in the bytes where the overlap occurs.
* The contents of locations in the object that have not been written to
* are undefined.
*
* @param hData A handle to the DDE object that receives additional
* data.
*
* @param pSrc The data to be added to the DDE object.
*
* @param cb The length, in bytes, of the data to be added to the DDE
* object, including the terminating NULL, if the data is a string.
*
* @param cbOff An offset, in bytes, from the beginning of the DDE
* object. The additional data is copied to the object beginning at this
* offset.
*
* @return If the function succeeds, the return value is a new handle to
* the DDE object. The new handle is used in all references to the
* object.
*
* <p>
* If the function fails a DdeException is raised with the following
* errorCodes:</p>
*
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_MEMORY_ERROR</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public Ddeml.HDDEDATA addData(Ddeml.HDDEDATA hData, Pointer pSrc, int cb, int cbOff);
/**
* Copies data from the specified Dynamic Data Exchange (DDE) object to
* the specified local buffer.
*
* @param hData A handle to the DDE object that contains the data to
* copy.
*
* @param pDst A pointer to the buffer that receives the data. If this
* parameter is NULL, the DdeGetData function returns the amount of
* data, in bytes, that would be copied to the buffer.
*
* @param cbMax The maximum amount of data, in bytes, to copy to the
* buffer pointed to by the pDst parameter. Typically, this parameter
* specifies the length of the buffer pointed to by pDst.
*
* @param cbOff An offset within the DDE object. Data is copied from the
* object beginning at this offset.
*
* @return If the pDst parameter points to a buffer, the return value is
* the size, in bytes, of the memory object associated with the data
* handle or the size specified in the cbMax parameter, whichever is
* lower.
*
* <p>
* If the function fails a DdeException is raised with the following
* errorCodes:</p>
*
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public int getData(Ddeml.HDDEDATA hData, Pointer pDst, int cbMax, int cbOff);
/**
* An application must call the DdeUnaccessData function when it has
* finished accessing the data in the object.
*
* @param hData A handle to the DDE object to be accessed.
*
* @param pcbDataSize A pointer to a variable that receives the size, in
* bytes, of the DDE object identified by the hData parameter. If this
* parameter is NULL, no size information is returned.
*
* @return If the function succeeds, the return value is a pointer to
* the first byte of data in the DDE object.
*
* <p>
* If the function fails a DdeException is raised with the following
* errorCodes:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public Pointer accessData(Ddeml.HDDEDATA hData, WinDef.DWORDByReference pcbDataSize);
/**
* Unaccesses a Dynamic Data Exchange (DDE) object. An application must
* call this function after it has finished accessing the object.
*
* @param hData A handle to the DDE object.
*
* <p>
* If the function fails a DdeException is raised with the following
* errorCodes:</p>
*
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public void unaccessData(Ddeml.HDDEDATA hData);
/**
* Causes the system to send an XTYP_ADVREQ transaction to the calling
* (server) application's Dynamic Data Exchange (DDE) callback function
* for each client with an active advise loop on the specified topic and
* item. A server application should call this function whenever the
* data associated with the topic name or item name pair changes.
*
* @param hszTopic A handle to a string that specifies the topic name.
* To send notifications for all topics with active advise loops, an
* application can set this parameter to 0L.
*
* @param hszItem A handle to a string that specifies the item name. To
* send notifications for all items with active advise loops, an
* application can set this parameter to 0L.
*
* <p>
* If the function fails a DdeException is raised with the following
* errorCodes:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_DLL_USAGE</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*
*/
public void postAdvise(Ddeml.HSZ hszTopic, Ddeml.HSZ hszItem);
/**
* Causes the system to send an XTYP_ADVREQ transaction to the calling
* (server) application's Dynamic Data Exchange (DDE) callback function
* for each client with an active advise loop on the specified topic and
* item. A server application should call this function whenever the
* data associated with the topic name or item name pair changes.
*
* @param hszTopic A string that specifies the topic name. To send
* notifications for all topics with active advise loops, an application
* can set this parameter to NULL.
*
* @param hszItem A string that specifies the item name. To send
* notifications for all items with active advise loops, an application
* can set this parameter to NULL.
*
* <p>
* If the function fails a DdeException is raised with the following
* errorCodes:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_DLL_USAGE</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*
*/
public void postAdvise(String hszTopic, String hszItem);
/**
* Abandons all asynchronous transaction and releases all
* resources associated with the transaction.
*
* <p>
* If the method fails a DdeException will be raised with the
* corresponding errorCode:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* <li>DMLERR_UNFOUND_QUEUE_ID</li>
* </ul>
*/
public void abandonTransactions();
/**
* Establishes a conversation with all server applications that support
* the specified service name and topic name pair. An application can
* also use this function to obtain a list of conversation handles by
* passing the function an existing conversation handle. The Dynamic
* Data Exchange Management Library removes the handles of any
* terminated conversations from the conversation list. The resulting
* conversation list contains the handles of all currently established
* conversations that support the specified service name and topic name.
*
* @param service A handle to the string that specifies the service
* name of the server application with which a conversation is to be
* established. If this parameter is 0L, the system attempts to
* establish conversations with all available servers that support the
* specified topic name.
*
* @param topic A handle to the string that specifies the name of the
* topic on which a conversation is to be established. This handle must
* have been created by a previous call to the DdeCreateStringHandle
* function. If this parameter is 0L, the system will attempt to
* establish conversations on all topics supported by the selected
* server (or servers).
*
* @param existingList An existinct conversation list to be enumerated.
* This parameter should be NULL if a new conversation list is to be
* established.
*
* @param ctx A pointer to the CONVCONTEXT structure that contains
* conversation-context information. If this parameter is NULL, the
* server receives the default CONVCONTEXT structure during the
* XTYP_CONNECT or XTYP_WILDCONNECT transaction.
*
* @return The new ConnectionList
*
* <p>
* If the function fails a DdeException is raised with the
* appropriate errorCode:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_CONV_ESTABLISHED</li>
* <li>DMLERR_NO_ERROR</li>
* <li>DMLERR_SYS_ERROR</li>
* </ul>
*/
public IDdeConnectionList connectList(Ddeml.HSZ service, Ddeml.HSZ topic, IDdeConnectionList existingList, Ddeml.CONVCONTEXT ctx);
/**
* Establishes a conversation with all server applications that support
* the specified service name and topic name pair. An application can
* also use this function to obtain a list of conversation handles by
* passing the function an existing conversation handle. The Dynamic
* Data Exchange Management Library removes the handles of any
* terminated conversations from the conversation list. The resulting
* conversation list contains the handles of all currently established
* conversations that support the specified service name and topic name.
*
* @param service A string that specifies the service name of the server
* application with which a conversation is to be established. If this
* parameter is NULL, the system attempts to establish conversations with
* all available servers that support the specified topic name.
*
* @param topic A string that specifies the name of the topic on which a
* conversation is to be established. If this parameter is NULL, the
* system will attempt to establish conversations on all topics
* supported by the selected server (or servers).
*
* @param existingList An existinct conversation list to be enumerated.
* This parameter should be NULL if a new conversation list is to be
* established.
*
* @param ctx A pointer to the CONVCONTEXT structure that contains
* conversation-context information. If this parameter is NULL, the
* server receives the default CONVCONTEXT structure during the
* XTYP_CONNECT or XTYP_WILDCONNECT transaction.
*
* @return The new ConnectionList
*
* <p>
* If the function fails a DdeException is raised with the
* appropriate errorCode:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_CONV_ESTABLISHED</li>
* <li>DMLERR_NO_ERROR</li>
* <li>DMLERR_SYS_ERROR</li>
* </ul>
*/
public IDdeConnectionList connectList(String service, String topic, IDdeConnectionList existingList, Ddeml.CONVCONTEXT ctx);
/**
* Enables or disables transactions for a specific conversation or for
* all conversations currently established by the calling application.
*
* @param wCmd The function code. This parameter can be one of the
* following values.
* <table>
* <tr><th>Value</th><th>Meaning</th></tr>
* <tr><td>EC_ENABLEALL</td><td>Enables all transactions for the
* specified conversation.</td></tr>
* <tr><td>EC_ENABLEONE</td><td>Enables one transaction for the
* specified conversation.</td></tr>
* <tr><td>EC_DISABLE</td><td>Disables all blockable transactions for
* the specified conversation.
*
* <p>
* A server application can disable the following transactions:</p>
* <ul>
* <li>XTYP_ADVSTART</li>
* <li>XTYP_ADVSTOP</li>
* <li>XTYP_EXECUTE</li>
* <li>XTYP_POKE</li>
* <li>XTYP_REQUEST</li>
* </ul>
* <p>
* A client application can disable the following transactions:</p>
* <ul>
* <li>XTYP_ADVDATA</li>
* <li>XTYP_XACT_COMPLETE</li>
* </ul>
* </td></tr>
* <tr><td>EC_QUERYWAITING</td><td>Determines whether any transactions
* are in the queue for the specified conversation.</td></tr>
* </table>
*
* @return If the function succeeds, the return value is nonzero.
*
* <p>
* If the function fails, the return value is zero.</p>
*
* <p>
* If the wCmd parameter is EC_QUERYWAITING, and the application
* transaction queue contains one or more unprocessed transactions that
* are not being processed, the return value is TRUE; otherwise, it is
* FALSE.</p>
*
* <p>
* If the function fails a DdeException is raised with the
* appropriate errorCode:</p>
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*/
public boolean enableCallback(int wCmd);
/**
* Frees all Dynamic Data Exchange Management Library (DDEML) resources
* associated with the calling application.
*
* @return true if function succeeded
*/
public boolean uninitialize();
/**
* Wrap a connection handle into a IDdeConnection helper class.
*
* @param conv HCONV structure to wrap
* @return wrapped IDdeConnection
*/
public IDdeConnection wrap(HCONV conv);
public void registerAdvstartHandler(AdvstartHandler handler);
public void unregisterAdvstartHandler(AdvstartHandler handler);
public void registerAdvstopHandler(AdvstopHandler handler);
public void unregisterAdvstopHandler(AdvstopHandler handler);
public void registerConnectHandler(ConnectHandler handler);
public void unregisterConnectHandler(ConnectHandler handler);
public void registerAdvReqHandler(AdvreqHandler handler);
public void unregisterAdvReqHandler(AdvreqHandler handler);
public void registerRequestHandler(RequestHandler handler);
public void unregisterRequestHandler(RequestHandler handler);
public void registerWildconnectHandler(WildconnectHandler handler);
public void unregisterWildconnectHandler(WildconnectHandler handler);
public void registerAdvdataHandler(AdvdataHandler handler);
public void unregisterAdvdataHandler(AdvdataHandler handler);
public void registerExecuteHandler(ExecuteHandler handler);
public void unregisterExecuteHandler(ExecuteHandler handler);
public void registerPokeHandler(PokeHandler handler);
public void unregisterPokeHandler(PokeHandler handler);
public void registerConnectConfirmHandler(ConnectConfirmHandler handler);
public void unregisterConnectConfirmHandler(ConnectConfirmHandler handler);
public void registerDisconnectHandler(DisconnectHandler handler);
public void unregisterDisconnectHandler(DisconnectHandler handler);
public void registerErrorHandler(ErrorHandler handler);
public void unregisterErrorHandler(ErrorHandler handler);
public void registerRegisterHandler(RegisterHandler handler);
public void unregisterRegisterHandler(RegisterHandler handler);
public void registerXactCompleteHandler(XactCompleteHandler handler);
public void unregisterXactCompleteHandler(XactCompleteHandler handler);
public void registerUnregisterHandler(UnregisterHandler handler);
public void unregisterUnregisterHandler(UnregisterHandler handler);
public void registerMonitorHandler(MonitorHandler handler);
public void unregisterMonitorHandler(MonitorHandler handler);
}
/**
* The IDdeConnectionList wraps a connectionlist.
*/
public interface IDdeConnectionList extends Closeable {
public Ddeml.HCONVLIST getHandle();
/**
* Retrieves the next conversation handle in the specified conversation
* list.
*
* @param prevConnection A handle to the conversation handle previously
* returned by this function. If this parameter is NULL, the function
* returns the first conversation handle in the list.
*
* @return If the list contains any more conversation handles, the
* return value is the next conversation IDdeConnection in the list;
* otherwise it is NULL.
*/
public IDdeConnection queryNextServer(IDdeConnection prevConnection);
/**
* Destroys the specified conversation list and terminates all
* conversations associated with the list.
*
* <p>
* If the function fails a DdeException is raised with the
* appropriate errorCode:</p>
*
* <ul>
* <li>DMLERR_DLL_NOT_INITIALIZED</li>
* <li>DMLERR_INVALIDPARAMETER</li>
* <li>DMLERR_NO_ERROR</li>
* </ul>
*
* <p>Note: This wraps DdeDisconnectList to align with Closeable wording.</p>
*/
public void close();
}
}