Functions
int	mdlWin32_DdeCmpStringHandles (HSZ hsz1, HSZ hsz2)
	The mdlWin32_DdeCmpStringHandles function compares the values of two string handles. More...

BOOL	mdlWin32_DdeKeepStringHandle (DWORD idInst, HSZ hsz)
	mdlWin32_DdeKeepStringHandle increments the usage count (by one) associated with the given handle. More...

BOOL	mdlWin32_DdeFreeStringHandle (DWORD idInst, HSZ hsz)
	The mdlWin32_DdeFreeStringHandle function frees a string handle in the calling application. More...

DWORD	mdlWin32_DdeQueryString (DWORD idInst, HSZ hsz, LPSTR psz, DWORD cchMax, int iCodePage)
	mdlWin32_DdeQueryString copies text associated with a string handle into a buffer. More...

HSZ	mdlWin32_DdeCreateStringHandle (DWORD idInst, LPSTR psz, int iCodePage)
	The mdlWin32_DdeCreateStringHandle function creates a handle that identifies the string pointed to by the psz parameter. More...

UINT	mdlWin32_DdeGetLastError (DWORD idInst)
	The mdlWin32_DdeGetLastError function returns the most recent error value set by a MDL-DDEML function and resets the error value to DMLERR_NO_ERROR. More...

BOOL	mdlWin32_DdeFreeDataHandle (HDDEDATA hData)
	The mdlWin32_DdeFreeDataHandle function frees a DDE data object and deletes the data handle associated with the object. More...

BOOL	mdlWin32_DdeUnaccessData (HDDEDATA hData)
	mdlWin32_DdeUnaccessData unaccesses a DDE data object. More...

LPBYTE	mdlWin32_DdeAccessData (HDDEDATA hData, LPDWORD pcbDataSize)
	mdlWin32_DdeAccessData returns a pointer to the data in the DDE object identified by the hData parameter. More...

HDDEDATA	mdlWin32_DdeAddData (HDDEDATA hData, LPBYTE pSrc, DWORD cb, DWORD cbOff)
	mdlWin32_DdeAddData adds data to the given DDE data object. More...

HDDEDATA	mdlWin32_DdeCreateDataHandle (DWORD idInst, LPBYTE pSrc, DWORD cb, DWORD cbOff, HSZ hszItem, UINT wFmt, UINT afCmd)
	mdlWin32_DdeCreateDataHandle creates a DDE data object and fills the object with the data pointed to by the pSrcBuf parameter. More...

HDDEDATA	mdlWin32_DdeNameService (DWORD idInst, HSZ hsz1, HSZ hsz2, UINT afCmd)
	The mdlWin32_DdeNameService function registers or unregisters the service names that a DDE server supports. More...

BOOL	mdlWin32_DdeImpersonateClient (HCONV hConv)
	This function sets MicroStation to assume the client's security settings for the specified DDE conversation to test access to a requested object. More...

BOOL	mdlWin32_DdeEnableCallback (DWORD idInst, HCONV hConv, UINT wCmd)
	mdlWin32_DdeEnableCallback enables or disables transactions for a specific conversation or for all conversations that the calling application currently has established. More...

BOOL	mdlWin32_DdePostAdvise (DWORD idInst, HSZ hszTopic, HSZ hszItem)
	mdlWin32_DdePostAdvise causes the system to send an XTYP_ADVREQ transaction to the calling (server) application's DDE callback function for each client that has an advise loop active on the specified topic or item name pair. More...

BOOL	mdlWin32_DdeAbandonTransaction (DWORD idInst, HCONV hConv, DWORD idTransaction)
	The mdlWin32_DdeAbandonTransaction function abandons the asynchronous transaction identified by the idTransaction parameter and releases all resources associated with the transaction. More...

BOOL	mdlWin32_DdeSetUserHandle (HCONV hConv, DWORD id, DWORD hUser)
	mdlWin32_DdeSetUserHandle associates an application-defined 32-bit value with a conversation handle or a transaction identifier. More...

UINT	mdlWin32_DdeQueryConvInfo (HCONV hConv, DWORD idTransaction, PCONVINFO pConvInfo)
	mdlWin32_DdeQueryConvInfo retrieves information about a DDE transaction and about the conversation in which the transaction takes place. More...

HCONV	mdlWin32_DdeReconnect (HCONV hConv)
	mdlWin32_DdeReconnect allows a client application to attempt to reestablish a conversation with a service that has terminated. More...

BOOL	mdlWin32_DdeDisconnect (HCONV hConv)
	The mdlWin32_DdeDisconnect function terminates a conversation started by either the mdlWin32_DdeConnect or mdlWin32_DdeConnectList function and invalidates the given conversation handle. More...

BOOL	mdlWin32_DdeDisconnectList (HCONVLIST hConvList)
	The mdlWin32_DdeDisconnectList function destroys the given conversation list and terminates all conversations associated with the list. More...

HCONV	mdlWin32_DdeQueryNextServer (HCONVLIST hConvList, HCONV hConvPrev)
	mdlWin32_DdeQueryNextServer obtains the next conversation handle in the given conversation list. More...

HCONVLIST	mdlWin32_DdeConnectList (DWORD idInst, HSZ hszService, HSZ hszTopic, HCONVLIST hConvList, PCONVCONTEXT pCC)
	mdlWin32_DdeConnectList establishes a conversation with all server applications that support the specified service and topic name pair. More...

BOOL	mdlWin32_DdeUninitialize (DWORD idInst)
	The mdlWin32_DdeUninitialize function terminates any conversations currently open and frees all of the DDE resources associated with the calling application. More...

DWORD	mdlWin32_DdeGetData (HDDEDATA hData, LPBYTE pDst, DWORD cbMax, DWORD cbOff)
	The mdlWin32_DdeGetData function copies data from the given DDE data object to the specified local buffer. More...

HDDEDATA	mdlWin32_DdeClientTransaction (LPBYTE pData, DWORD cbData, HCONV hConv, HSZ hszItem, UINT wFmt, UINT wType, DWORD dwTimeout, LPDWORD pdwResult)
	The mdlWin32_DdeClientTransaction function begins a data transaction between a client and a server. More...

HCONV	mdlWin32_DdeConnect (DWORD idInst, HSZ hszService, HSZ hszTopic, PCONVCONTEXT pCC)
	The mdlWin32_DdeConnect function establishes a conversation with a server application that supports the specified service name and topic name pair. More...

UINT	mdlWin32_DdeInitialize (LPDWORD lpidInst, PFNMdlDdeCallback pfnCallbackFunc, DWORD afCmdFilterFlags, DWORD uReserved)
	mdlWin32_DdeInitialize registers an asynchronous DDE function with MicroStation. More...

Detailed Description

Function Documentation

BOOL mdlWin32_DdeAbandonTransaction	(	DWORD	idInst,
		HCONV	hConv,
		DWORD	idTransaction
	)

The mdlWin32_DdeAbandonTransaction function abandons the asynchronous

transaction identified by the idTransaction parameter and releases all resources associated with the transaction.

Parameters

[in]	idInst	specifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function.
[in]	hConv	identifies the conversation in which the transaction was initiated. If NULL, all transactions are abandoned (the idTransaction parameter is ignored).
[in]	idTransaction	identifies the transaction to terminate. If this parameter is NULL, all active transactions in the specified conversation are abandoned.

Returns: mdlWin32_DdeAbandonTransaction returns true if the function is successful and false otherwise. Use the mdlWin32_DdeGetLastError function to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_INVALIDPARAMETER, DMLERR_NO_ERROR, DMLERR_UNFOUND_QUEUE_ID.

See also: mdlWin32_DdeClientTransaction mdlWin32_DdeGetLastError mdlWin32_DdeInitialize mdlWin32_DdeQueryConvInfo

Remarks: Required Library: mdlbltin.lib

LPBYTE mdlWin32_DdeAccessData	(	HDDEDATA	hData,
		LPDWORD	pcbDataSize
	)

mdlWin32_DdeAccessData returns a pointer to the data in the DDE object

identified by the hData parameter.

An application must call mdlWin32_DdeUnaccessData when it is finished accessing the data in the object.

Parameters

[in]	hData	identifies the DDE object to access.
[out]	pcbDataSize	points to a variable that receives the size, in bytes, of the DDE object identified by hData. If this parameter is NULL, no size information is returned.

Remarks: If the hData parameter has not been passed to a DDEML function, an application can use the pointer returned by mdlWin32_DdeAccessData for read-write access to the DDE object's data area. If hData has already been passed to a DDEML function, the pointer can only be used for read-only access to the memory object.

Returns: mdlWin32_DdeAccessData returns a pointer to the first byte of data in the DDE object associated with the hData parameter. Otherwise, the return value is NULL. Use the mdlWin32_DdeGetLastError function to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_INVALIDPARAMETER, DMLERR_NO_ERROR.

See also: mdlWin32_DdeAddData mdlWin32_DdeCreateDataHandle mdlWin32_DdeFreeDataHandle mdlWin32_DdeGetLastError mdlWin32_DdeUnaccessData

Remarks: Required Library: mdlbltin.lib

HDDEDATA mdlWin32_DdeAddData	(	HDDEDATA	hData,
		LPBYTE	pSrc,
		DWORD	cb,
		DWORD	cbOff
	)

mdlWin32_DdeAddData adds data to the given DDE data object.

An application can add data beginning 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. After a data handle has been used as a parameter in another DDEML function or returned by a DDE callback function, the handle may only be used for read access to the data object identified by the handle.

Remarks: If the amount of memory originally allocated is not large enough to hold the added data, mdlWin32_DdeAddData will reallocate a DDE data object of the appropriate size.

Parameters

[in]	hData	identifies the DDE data object that receives additional data.
[in]	pSrc	points to a buffer containing the data to add to the DDE data object.
[in]	cb	specifies the length, in bytes, of the data to be added to the DDE data object.
[in]	cbOff	specifies an offset, in bytes, from the beginning of the DDE data object. The additional data is copied to the object beginning at this offset.

Returns: If the mdlWin32_DdeAddData function succeeds, the return value is a new handle of the DDE data object. The new handle should be used in all references to the object. If an error occurs, the return value is zero. Use the mdlWin32_DdeGetLastError function to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_INVALIDPARAMETER, DMLERR_MEMORY_ERROR, DMLERR_NO_ERROR.

See also: mdlWin32_DdeAccessData mdlWin32_DdeCreateDataHandle mdlWin32_DdeGetLastError mdlWin32_DdeUnaccessData

Remarks: Required Library: mdlbltin.lib

HDDEDATA mdlWin32_DdeClientTransaction	(	LPBYTE	pData,
		DWORD	cbData,
		HCONV	hConv,
		HSZ	hszItem,
		UINT	wFmt,
		UINT	wType,
		DWORD	dwTimeout,
		LPDWORD	pdwResult
	)

The mdlWin32_DdeClientTransaction function begins a data transaction

between a client and a server.

Only a client application can call this function, and only after establishing a conversation with a server. When the application is finished using the data handle returned by the mdlWin32_DdeClientTransaction function, the application should free the handle by calling the mdlWin32_DdeFreeDataHandle function.

Remarks: Transactions can be synchronous or asynchronous. During a synchronous transaction, the mdlWin32_DdeClientTransaction function does not return until the transaction completes successfully or fails. Synchronous transactions cause the client to enter a modal DDE loop while waiting for various asynchronous events. Because of this, the client application can still respond to user input while waiting on a synchronous transaction but cannot begin a second synchronous transaction because of the activity associated with the first.; During an asynchronous transaction, this function returns after the transaction is begun, passing a transaction identifier for reference. When the server's DDE callback function finishes processing an asynchronous transaction, the system sends an XTYP_XACT_COMPLETE transaction to the client. This transaction provides the client with the results of the asynchronous transaction that it initiated by calling the mdlWin32_DdeClientTransaction function. A client application can choose to abandon an asynchronous transaction by calling the mdlWin32_DdeAbandonTransaction function.

Parameters

[in]	pData	points to the beginning of the data that the client needs to pass to the server. Optionally, an application can specify a data handle (HDDEDATA) to pass to the server, in which case the cbData parameter should be set to 0xFFFFFFFF. This parameter is required only if the uType parameter is XTYP_EXECUTE or XTYP_POKE. Otherwise, this parameter should be NULL.
[in]	cbData	specifies the length, in bytes, of the data pointed to by the pData parameter. A value of 0xFFFFFFFF indicates that pData is a data handle that identifies the data being sent.
[in]	hConv	identifies the conversation in which the transaction is to take place.
[in]	hszItem	identifies the data item for which data is being exchanged during the transaction. This handle must have been created by a previous call to the mdlWin32_DdeCreateStringHandle function. This parameter is ignored and should be set to NULL if the uType parameter is XTYP_EXECUTE.
[in]	wFmt	specifies a standard clipboard format in which the data item is being submitted or requested. If the transaction specified by the uType parameter does not pass data or is XTYP_EXECUTE, this parameter should be set to zero.
[in]	wType	specifies the transaction type and can have of the following values:


wType value	meaning
XTYP_ADVSTART	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: XTYPF_NODATA 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. XTYPF_ACKREQ 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.
XTYP_ADVSTOP	Ends an advise loop.
XTYP_EXECUTE	Begins an execute transaction.
XTYP_POKE	Begins a poke transaction.
XTYP_REQUEST	Begins a request transaction.

Parameters

[in]	dwTimeout	specifies the maximum length of time (milliseconds) that the client will wait for a response from the server application in a synchronous transaction. This parameter should be set to TIMEOUT_ASYNC for asynchronous transactions.
[out]	pdwResult	points to a variable that receives the result of the transaction. An application that does not check the result can set this value to NULL. For synchronous transactions, the low-order word of this variable will contain any applicable DDE_ flags resulting from the transaction. This provides support for existing applications dependent on DDE_APPSTATUS bits. (It is recommended that applications no longer use these bits because they may not be supported in future versions). For asynchronous transactions, this variable is filled with a unique transaction identifier for use with the mdlWin32_DdeAbandonTransaction function and the XTYP_XACT_COMPLETE transaction.

Returns: mdlWin32_DdeClientTransaction 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 true for successful asynchronous transactions and for synchronous transactions in which the client does not expect data. The return value is false for all unsuccessful transactions.

Remarks: Use the mdlWin32_DdeGetLastError function to retrieve the error value, which may be one of the following: DMLERR_ADVACKTIMEOUT, DMLERR_BUSY, DMLERR_DATAACKTIMEOUT, DMLERR_DLL_NOT_INITIALIZED, DMLERR_EXECACKTIMEOUT, DMLERR_INVALIDPARAMETER, DMLERR_MEMORY_ERROR, DMLERR_NO_CONV_ESTABLISHED, DMLERR_NO_ERROR, DMLERR_NOTPROCESSED, DMLERR_POKEACKTIMEOUT, DMLERR_POSTMSG_FAILED, DMLERR_REENTRANCY, DMLERR_SERVER_DIED, DMLERR_UNADVACKTIMEOUT.

See also: mdlWin32_DdeAbandonTransaction mdlWin32_DdeAccessData mdlWin32_DdeConnect mdlWin32_DdeConnectList mdlWin32_DdeCreateStringHandle

Remarks: Required Library: mdlbltin.lib

int mdlWin32_DdeCmpStringHandles	(	HSZ	hsz1,
		HSZ	hsz2
	)

The mdlWin32_DdeCmpStringHandles function compares the values of two

string handles.

The value of a string handle is not related to the case of the associated string. An application that needs to do a case-sensitive comparison of two string handles should compare the string handles directly; however, this is strongly discouraged. An application should use mdlWin32_DdeCmpStringHandles for all other comparisons to preserve the case-insensitive nature of dynamic data exchange (DDE).

Parameters

[in]	hsz1	specifies the second string handle to compare.
[in]	hsz2	specifies the second string handle to compare.

Returns

mdlWin32_DdeCmpStringHandles returns one of the following values:


value	meaning
-1	The value of hsz1 is either 0 or less than the value of hsz2.
0	The values of hsz1 and hsz2 are equal (both can be 0).
1	The value of hsz2 is either 0 or less than the value of hsz1.

See also: mdlWin32_DdeAccessData mdlWin32_DdeCreateStringHandle mdlWin32_DdeFreeStringHandle

Remarks: Required Library: mdlbltin.lib

HCONV mdlWin32_DdeConnect	(	DWORD	idInst,
		HSZ	hszService,
		HSZ	hszTopic,
		PCONVCONTEXT	pCC
	)

The mdlWin32_DdeConnect function 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.

Remarks: The client application should not make assumptions regarding which server will be selected. If an instance-specific service name is specified in hszService, a conversation will be established only with the specified instance. (Instance-specific service names are passed to an application's DDE callback function (i.e., userWin32_DdeUserCallback) during the XTYP_REGISTER and XTYP_UNREGISTER transactions).; All members of the default CONVCONTEXT data structure are set to zero except cb, which specifies the size of the structure, and iCodePage, which specifies CP_WINANSI (the default code page).

Parameters

[in]	idInst	specifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function.
[in]	hszService	specifies the string handle service name of the server application to which a conversation is to be established. This handle must have been created by a previous call to the mdlWin32_DdeCreateStringHandle function. If this parameter is NULL, a conversation will be established with any available server.
[in]	hszTopic	specifies the string handle topic name of the server to which a conversation is to be established. This handle must have been created by a previous call to the mdlWin32_DdeCreateStringHandle function. If this parameter is NULL, a conversation on any topic supported by the selected server will be established.
[in]	pCC	points 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.

Returns: mdlWin32_DdeConnect returns the value of the handle of the established conversation; otherwise, it is NULL. Use the mdlWin32_DdeGetLastError function to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_INVALIDPARAMETER, DMLERR_NO_CONV_ESTABLISHED, DMLERR_NO_ERROR.

See also: mdlWin32_DdeConnectList mdlWin32_DdeCreateStringHandle mdlWin32_DdeDisconnect mdlWin32_DdeDisconnectList mdlWin32_DdeInitialize

Remarks: Required Library: mdlbltin.lib

HCONVLIST mdlWin32_DdeConnectList	(	DWORD	idInst,
		HSZ	hszService,
		HSZ	hszTopic,
		HCONVLIST	hConvList,
		PCONVCONTEXT	pCC
	)

mdlWin32_DdeConnectList establishes a conversation with all server

applications that support the specified service and topic name pair.

An application can also use this function to enumerate a list of conversation handles by passing in an existing conversation handle. During enumeration, the DDEML removes the handles of any terminated conversations from the conversation list. The resulting conversation list contains the handles of all conversations currently established that support the specified service and topic name pair. An application must free the conversation-list handle returned by this function, regardless of whether any conversation handles within the list are active. To free the handle, an application can call mdlWin32_DdeDisconnectList. All members of the default CONVCONTEXT data structure are set to zero except cb, which specifies the size of the structure, and iCodePage, which specifies CP_WINANSI (the default code page).

Parameters

[in]	idInst	specifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize.
[in]	hszService	identifies the 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 will attempt to establish conversations with all available servers that support the specified topic name.
[in]	hszTopic	identifies the string specifying the name of the topic on which a conversation is to be established. This handle must have been created by a previous call to mdlWin32_DdeCreateStringHandle. If this parameter is NULL, the system will attempt to establish conversations on all topics supported by the selected server (or servers).
[in]	hConvList	identifies the conversation list to be enumerated. This parameter should be set to NULL if a new conversation list is to be established.
[in]	pCC	points to the CONVCONTEXT structure containing conversation-context information. If this parameter is NULL, the server receives the default CONVCONTEXT structure during the XTYP_CONNECT or XTYP_WILDCONNECT transaction.

Returns: mdlWin32_DdeConnectList returns the handle of a new conversation list if successful, and NULL otherwise. The handle of the old conversation list is no longer valid. Use mdlWin32_DdeGetLastError to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_INVALID_PARAMETER, DMLERR_NO_CONV_ESTABLISHED, DMLERR_NO_ERROR, DMLERR_SYS_ERROR.

See also: mdlWin32_DdeConnect mdlWin32_DdeCreateStringHandle mdlWin32_DdeDisconnect mdlWin32_DdeDisconnectList mdlWin32_DdeInitialize mdlWin32_DdeQueryNextServer

Remarks: Required Library: mdlbltin.lib

HDDEDATA mdlWin32_DdeCreateDataHandle	(	DWORD	idInst,
		LPBYTE	pSrc,
		DWORD	cb,
		DWORD	cbOff,
		HSZ	hszItem,
		UINT	wFmt,
		UINT	afCmd
	)

mdlWin32_DdeCreateDataHandle creates a DDE data object and fills the object

with the data pointed to by the pSrcBuf parameter.

An application uses this function during transactions that involve passing data to the partner application. Any locations in the DDE data object that are not filled are undefined. After a data handle has been used as a parameter in another DDEML function or has been returned by a DDE callback function, the handle may be used only for read access to the DDE data object identified by the handle.

Parameters

[in]	idInst	specifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize.
[in]	pSrc	points to a buffer that contains data to be copied to the DDE data object. If this parameter is NULL, no data is copied to the object.
[in]	cb	specifies the amount, in bytes, of memory to allocate for the DDE data object. If this parameter is zero, the pSrcBuf parameter is ignored.
[in]	cbOff	specifies an offset, in bytes, from the beginning of the buffer pointed to by the pSrcBuf parameter. The data beginning at this offset is copied from the buffer to the DDE data object.
[in]	hszItem	identifies the string that specifies the data item corresponding to the DDE data object. This handle must have been created by a previous call to mdlWin32_DdeCreateStringHandle. If the data handle is to be used in an XTYP_EXECUTE transaction, this parameter must be set to NULL.
[in]	wFmt	specifies the standard clipboard format number of the data.
[in]	afCmd	specifies the creation flags. This parameter can be HDATA_APPOWNED, which specifies that the application that calls mdlWin32_DdeCreateDataHandle will own the data handle that this function creates. This makes it possible for the application to share the data handle with other DDEML applications instead of creating a separate handle to pass to each application. If this flag is set, the application must eventually free the shared memory object associated with this handle by using mdlWin32_DdeFreeDataHandle. If this flag is not set, after the data handle is returned by the application's DDE callback function (i.e., userWin32_DdeUserCallback) or used as a parameter in another DDE Management Library function, the handle becomes invalid in the application that creates the handle.

Returns: mdlWin32_DdeCreateDataHandle returns a data handle; otherwise, it is NULL. Use the mdlWin32_DdeGetLastError function to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_INVALIDPARAMETER, DMLERR_MEMORY_ERROR, DMLERR_NO_ERROR.

See also: mdlWin32_DdeAccessData mdlWin32_DdeFreeDataHandle mdlWin32_DdeGetData mdlWin32_DdeInitialize XTYP_EXECUTEC

Remarks: Required Library: mdlbltin.lib

HSZ mdlWin32_DdeCreateStringHandle	(	DWORD	idInst,
		LPSTR	psz,
		int	iCodePage
	)

The mdlWin32_DdeCreateStringHandle function creates a handle that

identifies the string pointed to by the psz parameter.

A client or server application can pass the string handle as a parameter to other DDEML functions. When an application has either created a string handle or received one in the callback function (i.e., userWin32_DdeUserCallback) and has used the mdlWin32_DdeKeepStringHandle function to keep it, the application must free that string handle when it is no longer needed. An instance-specific string handle is not mappable from string handle to string to string handle again. There can be two unique string handles for the same underlining string.

Parameters

[in]	idInst	specifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function.
[in]	psz	points to a buffer that contains the NULL terminated string for which a handle is to be created. This string may be any length.
[in]	iCodePage	specifies the code page used to render the string. This value should be either CP_WINANSI (the default code page) or CP_WINUNICODE, depending on whether the ANSI or Unicode version of the mdlWin32_DdeInitialize function was called by the client application.

Returns: mdlWin32_DdeCreateStringHandle returns a string handle; otherwise, it is NULL. Use the mdlWin32_DdeGetLastError function to retrieve the error value, which may be one of the following: DMLERR_INVALIDPARAMETER, DMLERR_NO_ERROR, DMLERR_SYS_ERROR.

See also: mdlWin32_DdeAccessData mdlWin32_DdeCmpStringHandles mdlWin32_DdeFreeStringHandle mdlWin32_DdeInitialize mdlWin32_DdeKeepStringHandle mdlWin32_DdeQueryString

Remarks: Required Library: mdlbltin.lib

BOOL mdlWin32_DdeDisconnect ( HCONV hConv )

The mdlWin32_DdeDisconnect function terminates a conversation started by

either the mdlWin32_DdeConnect or mdlWin32_DdeConnectList function and invalidates the given conversation handle.

Any incomplete transactions started before calling mdlWin32_DdeDisconnect are immediately abandoned. The XTYP_DISCONNECT transaction type is sent to the callback function (i.e., userWin32_DdeUserCallback) of the partner in the conversation. Generally, only client applications need to terminate conversations.

Parameters

[in] hConv identifies the active conversation to be terminated.

Returns: mdlWin32_DdeDisconnect returns If the function succeeds, the return value is true, otherwise, it is false. Use the mdlWin32_DdeGetLastError function to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_NO_CONV_ESTABLISHED, DMLERR_NO_ERROR.

See also: mdlWin32_DdeConnect mdlWin32_DdeConnectList mdlWin32_DdeDisconnectList

Remarks: Required Library: mdlbltin.lib

BOOL mdlWin32_DdeDisconnectList ( HCONVLIST hConvList )

The mdlWin32_DdeDisconnectList function destroys the given conversation

list and terminates all conversations associated with the list.

An application can use the mdlWin32_DdeDisconnect function to terminate individual conversations in the list.

Parameters

[in] hConvList identifies the conversation list. This handle must have been created by a previous call to the mdlWin32_DdeConnectList function.

Returns: mdlWin32_DdeDisconnectList returns true if the function succeeds; otherwise, it is false. Use the mdlWin32_DdeGetLastError function to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_INVALIDPARAMETER, DMLERR_NO_ERROR.

See also: mdlWin32_DdeConnect mdlWin32_DdeConnectList mdlWin32_DdeDisconnect

Remarks: Required Library: mdlbltin.lib

BOOL mdlWin32_DdeEnableCallback	(	DWORD	idInst,
		HCONV	hConv,
		UINT	wCmd
	)

mdlWin32_DdeEnableCallback enables or disables transactions for a specific

conversation or for all conversations that the calling application currently has established.

After disabling transactions for a conversation, the system places the transactions for that conversation in a transaction queue associated with the application. The application should reenable the conversation as soon as possible to avoid losing queued transactions.

Remarks: An application can disable transactions for a specific conversation by returning CBR_BLOCK from its DDE callback function (i.e., userWin32_DdeUserCallback). When the conversation is reenabled by mdlWin32_DdeEnableCallback, the system generates the same transaction as was in process when the conversation was disabled.; Using the EC_QUERYWAITING flag does not change the enable state of the conversation and does not cause transactions to be issued within the context of the call to mdlWin32_DdeEnableCallback.

Parameters

[in]	idInst	specifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function.
[in]	hConv	identifies the conversation to enable or disable. If this parameter is NULL, the function affects all conversations.
[in]	wCmd	specifies the function code. This parameter can be one of the following values:


value	description
EC_ENABLEALL	Enables all transactions for the specified conversation.
EC_ENABLEONE	Enables one transaction for the specified conversation.
EC_DISABLE	Disables all blockable transactions for the specified conversation. A server application can disable the following transactions: XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_EXECUTE, XTYP_POKE, XTYP_REQUEST. A client application can disable the following transactions: XTYP_ADVDATA, XTYP_XACT_COMPLETE.
EC_QUERYWAITING	Determines whether any transactions are in the queue for the specified conversation.

Returns: mdlWin32_DdeEnableCallback returns If the function succeeds, the return value is true; otherwise, it is false. If the uCmd parameter is EC_QUERYWAITING and the queue contains one or more transactions, the return value is true; otherwise, it is false. Use mdlWin32_DdeGetLastError to retrieve the error value, which may be DMLERR_DLL_NOT_INITIALIZED, DMLERR_NO_ERROR or DMLERR_INVALIDPARAMETER.

See also: mdlWin32_DdeConnect mdlWin32_DdeConnectList mdlWin32_DdeDisconnect mdlWin32_DdeInitialize

Remarks: Required Library: mdlbltin.lib

BOOL mdlWin32_DdeFreeDataHandle ( HDDEDATA hData )

The mdlWin32_DdeFreeDataHandle function frees a DDE data object and deletes

the data handle associated with the object.

Parameters

[in] hData identifies the DDE data object to be freed. This handle must have been created by a previous call to the mdlWin32_DdeCreateDataHandle function or returned by the mdlWin32_DdeClientTransaction function.

Returns: mdlWin32_DdeFreeDataHandle returns true if the function succeeds; otherwise, it is false. Use the mdlWin32_DdeGetLastError function to retrieve the error value, which may be one of the following: DMLERR_INVALIDPARAMETER, DMLERR_NO_ERROR.

Remarks

An application must call mdlWin32_DdeFreeDataHandle under the following circumstances:

To free a DDE data object that the application allocated by calling the mdlWin32_DdeCreateDataHandle function if the object's data handle was never passed by the application to another MDL-DDEML function.
To free a DDE data object that the application allocated by specifying the HDATA_APPOWNED flag in a call to the mdlWin32_DdeCreateDataHandle function.
To free a DDE data object whose handle the application received from the mdlWin32_DdeClientTransaction function.

The system automatically frees an unowned object when its handle is returned by a DDE callback function (i.e., userWin32_DdeUserCallback) or used as a parameter in a DDEML function.

See also: mdlWin32_DdeAccessData mdlWin32_DdeCreateDataHandle

Remarks: Required Library: mdlbltin.lib

BOOL mdlWin32_DdeFreeStringHandle	(	DWORD	idInst,
		HSZ	hsz
	)

The mdlWin32_DdeFreeStringHandle function frees a string handle in the

calling application.

An application can free string handles that it creates with the mdlWin32_DdeCreateStringHandle function but should not free those that the system passed to the application's DDE callback function (i.e., userWin32_DdeUserCallback) or those returned in the CONVINFO structure by the mdlWin32_DdeQueryConvInfo function.

Parameters

[in]	idInst	specifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function.
[in]	hsz	identifies the string handle to be freed. This handle must have been created by a previous call to the mdlWin32_DdeCreateStringHandle function.

Returns: mdlWin32_DdeFreeStringHandle returns true for success; false otherwise.

See also: mdlWin32_DdeCmpStringHandles mdlWin32_DdeCreateStringHandle mdlWin32_DdeInitialize mdlWin32_DdeKeepStringHandle mdlWin32_DdeQueryString

Remarks: Required Library: mdlbltin.lib

DWORD mdlWin32_DdeGetData	(	HDDEDATA	hData,
		LPBYTE	pDst,
		DWORD	cbMax,
		DWORD	cbOff
	)

The mdlWin32_DdeGetData function copies data from the given DDE data

object to the specified local buffer.

Parameters

[in]	hData	identifies the DDE data object that contains the data to copy.
[in,out]	pDst	points to the buffer that receives the data. If this parameter is NULL, the mdlWin32_DdeGetData function returns the amount, in bytes, of data that would be copied to the buffer.
[in]	cbMax	specifies the maximum amount, in bytes, of data to copy to the buffer pointed to by the pDst parameter. Typically, this parameter specifies the length of the buffer pointed to by pDst.
[in]	cbOff	specifies an offset within the DDE data object. Data is copied from the object beginning at this offset.

Returns: If pDst parameter points to a buffer, mdlWin32_DdeGetData returns the lesser of the cbMax parameter or the size, in bytes, of the memory object associated with the data handle. If the pDst parameter is NULL, the return value is the size, in bytes, of the memory object associated with the data handle. Use mdlWin32_DdeGetLastError to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_INVALID_HDDEDATA, DMLERR_INVALIDPARAMETER, DMLERR_NO_ERROR.

See also: mdlWin32_DdeAccessData mdlWin32_DdeCreateDataHandle mdlWin32_DdeFreeDataHandle

Remarks: Required Library: mdlbltin.lib

UINT mdlWin32_DdeGetLastError ( DWORD idInst )

The mdlWin32_DdeGetLastError function returns the most recent error

value set by a MDL-DDEML function and resets the error value to DMLERR_NO_ERROR.

Parameters

[in] idInst specifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function.

Remarks

mdlWin32_DdeGetLastError returns one of the following values:


flag	description
DMLERR_ADVACKTIMEOUT	A request for a synchronous advise transaction has timed out.
DMLERR_BUSY	The response to the transaction caused the DDE_FBUSY bit to be set.
DMLERR_DATAACKTIMEOUT	A request for a synchronous data transaction has timed out.
DMLERR_DLL_NOT_INITIALIZED	A DDEML function was called without first calling the mdlWin32_DdeInitialize function, or an invalid instance identifier was passed to a DDEML function.
DMLERR_DLL_USAGE	An application initialized as APPCLASS_MONITOR has attempted to perform a DDE transaction, or an application initialized as APPCMD_CLIENTONLY has attempted to perform server transactions.
MLERR_EXECACKTIMEOUT	A request for a synchronous execute transaction has timed out.
DMLERR_INVALIDPARAMETER	A parameter failed to be validated by the DDEML. Some of the possible causes are: · The application used a data handle initialized with a different item-name handle than that required by the transaction. · The application used a data handle that was initialized with a different clipboard data format than that required by the transaction. · The application used a client-side conversation handle with a server-side function or vice versa. · The application used a freed data handle or string handle. · More than one instance of the application used the same object.
DMLERR_LOW_MEMORY	A DDEML application has created a prolonged race condition (where the server application outruns the client), causing large amounts of memory to be consumed.
DMLERR_MEMORY_ERROR	A memory allocation failed.
DMLERR_NO_CONV_ESTABLISHED	A client's attempt to establish a conversation has failed.
DMLERR_NOTPROCESSED	A transaction failed.
DMLERR_POKEACKTIMEOUT	A request for a synchronous poke transaction has timed out.
DMLERR_POSTMSG_FAILED	An internal call to the Windows NT PostMessage function has failed.
DMLERR_REENTRANCY	An application instance with a synchronous transaction already in progress attempted to initiate another synchronous transaction, or mdlWin32_DdeEnableCallback was called from within a DDEML callback function, i.e., userWin32_DdeUserCallback.
DMLERR_SERVER_DIED	A server-side transaction was attempted on a conversation that was terminated by the client, or the server terminated before completing a transaction.
DMLERR_SYS_ERROR	An internal error has occurred in the DDEML.
DMLERR_UNADVACKTIMEOUT	A request to end an advise transaction has timed out.
DMLERR_UNFOUND_QUEUE_ID	An invalid transaction identifier was passed to a function. Once the application has returned from an XTYP_XACT_COMPLETE callback, the transaction identifier for that callback is no longer valid.

Returns: The most recent error value set by a MDL-DDEML function.

See also: mdlWin32_DdeInitialize

Remarks: Required Library: mdlbltin.lib

BOOL mdlWin32_DdeImpersonateClient ( HCONV hConv )

This function sets MicroStation to assume the client's security settings for the specified DDE conversation to test access to a requested object.

Parameters

[in] hConv a handle to the DDE conversation

Returns: true if the function succeeds, false if it does not

Remarks: When a client requests access to an object, the system verifies the access by impersonating the client. When the impersonation is complete, the server normally calls the RevertToSelf function.; Required Library: mdlbltin.lib

UINT mdlWin32_DdeInitialize	(	LPDWORD	lpidInst,
		PFNMdlDdeCallback	pfnCallbackFunc,
		DWORD	afCmdFilterFlags,
		DWORD	uReserved
	)

mdlWin32_DdeInitialize registers an asynchronous DDE function with

MicroStation.

An application must call this function before calling any other MDL- DDEML functions.

Remarks: A DDE monitoring application should not attempt to perform DDE (establish conversations, issue transactions, and so on) within the context of the same application instance.; A synchronous transaction will fail with a DMLERR_REENTRANCY error if any instance of the same task has a synchronous transaction already in progress.; The CBF_FAIL_ALLSVRXACTIONS flag causes the DDEML to filter all server transactions and may be changed by a subsequent call to mdlWin32_DdeInitialize.; The APPCMD_CLIENTONLY flag prevents the DDEML from creating key resources for the server and cannot be changed by a subsequent call to mdlWin32_DdeInitialize.; There is an ANSI version and a Unicode version of this function. The version called determines the type of the window procedures used to control DDE conversations (ANSI or Unicode), and the default value for the iCodePage member of the CONVCONTXT structure (CP_WINANSI or CP_WINUNICODE).

Parameters

[in,out]	lpidInst	returns a pointer to the application-instance identifier. At initialization, this parameter should point to 0. However, this parameter must not be NULL. If the function succeeds, this parameter points to the instance identifier for the MDL application. This value should be passed as the idInst parameter in all other DDEML functions that require it. If pidInst points to a nonzero value, this implies a reinitialization of the DDEML. In this case, pidInst must point to a valid application-instance identifier.
[in]	pfnCallbackFunc	points to the application-defined DDE callback function. This function processes DDE transactions sent by other applications. For more information, see the description of the userWin32_DdeUserCallback callback function.
[in]	afCmdFilterFlags	specifies a logical expression of APPCMD_, CBF_ and MF_ flags. The APPCMD_ flags provide special instructions to mdlWin32_DdeInitialize. The CBF_ flags set 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 will monitor. Using these flags enhances the performance of a DDE application by eliminating unnecessary calls to the callback function. This parameter can be a combination of the flags listed below.

Remarks

Possible flag values for afCmdFilterFlags:


flag	description
APPCLASS_MONITOR	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.
APPCLASS_STANDARD	Registers the application as a standard (nonmonitoring) DDEML application. Most applications will use this flag.
APPCMD_CLIENTONLY	Prevents the application from becoming a server in a DDE conversation. The application can be only a client. This flag reduces resource consumption by the DDEML. It includes the functionality of the CBF_FAIL_ALLSVRXACTIONS flag.
APPCMD_FILTERINITS	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 mdlWin32_DdeNameService or mdlWin32_DdeInitialize functions. This flag is always in effect when an application calls mdlWin32_DdeInitialize for the first time, regardless of whether the application specifies this flag. On subsequent calls to mdlWin32_DdeInitialize, not specifying this flag turns off the application's service-name filters; specifying this flag turns on the application's service-name filters.
CBF_FAIL_ALLSVRXACTIONS	Prevents the callback function from receiving server transactions. The system will return DDE_FNOTPROCESSED to each client that sends a transaction to this application. This flag is equivalent to combining all CBF_FAIL_ flags.
CBF_FAIL_ADVISES	Prevents the callback function from receiving XTYP_ADVSTART and XTYP_ADVSTOP transactions. The system will return DDE_FNOTPROCESSED to each client that sends an XTYP_ADVSTART or XTYP_ADVSTOP transaction to the server.
CBF_FAIL_CONNECTIONS	Prevents the callback function from receiving XTYP_CONNECT and XTYP_WILDCONNECT transactions.
CBF_FAIL_EXECUTES	Prevents the callback function from receiving XTYP_EXECUTE transactions. The system will return DDE_FNOTPROCESSED to a client that sends an XTYP_EXECUTE transaction to the server.
CBF_FAIL_POKES	Prevents the callback function from receiving XTYP_POKE transactions. The system will return DDE_FNOTPROCESSED to a client that sends an XTYP_POKE transaction to the server.
CBF_FAIL_REQUESTS	Prevents the callback function from receiving XTYP_REQUEST transactions. The system will return DDE_FNOTPROCESSED to a client that sends an XTYP_REQUEST transaction to the server.
CBF_FAIL_SELFCONNECTIONS	Prevents the callback function from receiving XTYP_CONNECT transactions from the application's own instance. This prevents an application from establishing a DDE conversation with its self. An application should use this flag if it needs to communicate with other instances of itself but not with itself.
CBF_SKIP_ALLNOTIFICATIONS	Prevents the callback function from receiving any notifications. This flag is equivalent combining all CBF_SKIP_ flags.
CBF_SKIP_CONNECT_CONFIRMS	Prevents the callback function from receiving XTYP_CONNECT_CONFIRM notifications.
CBF_SKIP_DISCONNECTS	Prevents the callback function from receiving XTYP_DISCONNECT notifications.
CBF_SKIP_REGISTRATIONS	Prevents the callback function from receiving XTYP_REGISTER notifications.
CBF_SKIP_UNREGISTRATIONS	Prevents the callback function from receiving XTYP_UNREGISTER notifications
MF_CALLBACKS	Notifies the callback function whenever a transaction is sent to any DDE callback function in the system
MF_CONV	Notifies the callback function whenever a conversation is established or terminated.
MF_ERRORS	Notifies the callback function whenever a DDE error occurs.
MF_HSZ_INFO	Notifies the callback function whenever a DDE application creates, frees or increments the use count of a string handle or whenever a string handle is freed as a result of a call to mdlWin32_DdeUninitialize.
MF_LINKS	Notifies the callback function whenever an advise loop is started or ended.
MF_POSTMSGS	Notifies the callback function whenever the system or an application posts a DDE message.
MF_SENDMSGS	Notifies the callback function whenever the system or an application sends a DDE message.

Parameters

[in] uReserved is reserved and must be set to 0.

Returns: mdlWin32_DdeInitialize returns one of the following: DMLERR_DLL_USAGE, DMLERR_INVALIDPARAMETER, DMLERR_NO_ERROR, DMLERR_SYS_ERROR.

See also: mdlWin32_DdeClientTransaction mdlWin32_DdeConnect mdlWin32_DdeCreateDataHandle mdlWin32_DdeEnableCallback mdlWin32_DdeNameService mdlWin32_DdePostAdvise mdlWin32_DdeUninitialize

Remarks: Required Library: mdlbltin.lib

BOOL mdlWin32_DdeKeepStringHandle	(	DWORD	idInst,
		HSZ	hsz
	)

mdlWin32_DdeKeepStringHandle increments the usage count (by one)

associated with the given handle.

This function makes it possible for an application to save a string handle that was passed to the application's 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 mdlWin32_DdeQueryConvInfo.

Parameters

[in]	idInst	specifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize.
[in]	hsz	identifies the string handle to be saved.

Returns: mdlWin32_DdeKeepStringHandle returns true for success; false otherwise.

See also: mdlWin32_DdeCreateStringHandle mdlWin32_DdeFreeStringHandle mdlWin32_DdeInitialize mdlWin32_DdeQueryConvInfo mdlWin32_DdeQueryString

Remarks: Required Library: mdlbltin.lib

HDDEDATA mdlWin32_DdeNameService	(	DWORD	idInst,
		HSZ	hsz1,
		HSZ	hsz2,
		UINT	afCmd
	)

The mdlWin32_DdeNameService function registers or unregisters the service

names that a DDE server supports.

This function causes the system to send XTYP_REGISTER or XTYP_UNREGISTER transactions to other running client applications. A server application should call this function to register each service name that it supports and to unregister names that it previously registered but no longer supports. A server should also call this function to unregister its service names just before terminating. The service name identified by the hsz1 parameter should be a base name (that is, the name should contain no instance-specific information). The system generates an instance-specific name and sends it along with the base name during the XTYP_REGISTER and XTYP_UNREGISTER transactions. The receiving applications can then connect to the specific application instance.

Parameters

[in] idInst specifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize.

[in] hsz1 identifies the string that specifies the service name that the server is registering or unregistering. An application that is unregistering all of its service names should set this parameter to NULL.

[in] hsz2 is reserved and should be set to NULL.

[in]

afCmd

specifies the service-name flags. This parameter can be one of the following values:


value	description
DNS_REGISTER	Registers the given service name.
DNS_UNREGISTER	Unregisters the given service name. If the hsz1 parameter is NULL, all service names registered by the server will be unregistered.
DNS_FILTERON	Turns on service-name initiation filtering. This filter prevents a server from receiving XTYP_CONNECT transactions for service names that it has not registered. This is the default setting for this filter. If a server application does not register any service names, the application cannot receive XTYP_WILDCONNECT transactions.
DNS_FILTEROFF	Turns off service-name initiation filtering. If this flag is set, the server will receive an XTYP_CONNECT transaction whenever another DDE application calls the mdlWin32_DdeConnect function, regardless of the service name.

Returns: mdlWin32_DdeNameService returns true if the function succeeds; false otherwise. Use mdlWin32_DdeGetLastError to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_DLL_USAGE, DMLERR_INVALIDPARAMETER, DMLERR_NO_ERROR.

See also: mdlWin32_DdeConnect mdlWin32_DdeConnectList mdlWin32_DdeInitialize

Remarks: Required Library: mdlbltin.lib

BOOL mdlWin32_DdePostAdvise	(	DWORD	idInst,
		HSZ	hszTopic,
		HSZ	hszItem
	)

mdlWin32_DdePostAdvise causes the system to send an XTYP_ADVREQ transaction

to the calling (server) application's DDE callback function for each client that has an advise loop active on the specified topic or item name pair.

A server application should call this function whenever the data associated with the topic or item name pair changes. A server that has nonenumerable topics or items should set the hszTopic and hszItem parameters to NULL so that the system will generate transactions for all active advise loops. The server's DDE callback function returns NULL for any advise loops that do not need to be updated. If a server calls mdlWin32_DdePostAdvise with a topic/item/format name set that includes the set currently being handled in a XTYP_ADVREQ callback, a stack overflow may result.

Parameters

[in]	idInst	specifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize.
[in]	hszTopic	identifies 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.
[in]	hszItem	identifies 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.

Returns: mdlWin32_DdePostAdvise returns true if function succeeds, otherwise, it is false. Use mdlWin32_DdeGetLastError to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_DLL_USAGE, DMLERR_NO_ERROR.

See also: mdlWin32_DdeInitialize

Remarks: Required Library: mdlbltin.lib

UINT mdlWin32_DdeQueryConvInfo	(	HCONV	hConv,
		DWORD	idTransaction,
		PCONVINFO	pConvInfo
	)

mdlWin32_DdeQueryConvInfo retrieves information about a DDE transaction

and about the conversation in which the transaction takes place.

An application should not free a string handle referenced by the CONVINFO structure. If an application needs to use one of these string handles, it should call the mdlWin32_DdeKeepStringHandle to create a copy of the handle for itself.

Remarks: If idTransaction is set to QID_SYNC, the hUser member of the CONVINFO structure is associated with the conversation and can be used to hold data associated with the conversation. If idTransaction is the identifier of an asynchronous transaction, the hUser member is associated only with the current transaction and is valid only for the duration of the transaction.

Parameters

[in]	hConv	identifies the conversation.
[in]	idTransaction	specifies the transaction. For asynchronous transactions, this parameter should be a transaction identifier returned by mdlWin32_DdeClientTransaction. For synchronous transactions, this parameter should be QID_SYNC.
[out]	pConvInfo	points to the CONVINFO structure that will receive information about the transaction and conversation. The cb member of the CONVINFO structure must specify the length of the buffer allocated for the structure.

Returns: mdlWin32_DdeQueryConvInfo returns number of bytes copied into the CONVINFO structure or zero for an error. Use mdlWin32_DdeGetLastError to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_NO_CONV_ESTABLISHED, DMLERR_NO_ERROR, DMLERR_UNFOUND_QUEUE_ID.

See also: mdlWin32_DdeConnect mdlWin32_DdeConnectList mdlWin32_DdeKeepStringHandle mdlWin32_DdeQueryNextServer

Remarks: Required Library: mdlbltin.lib

HCONV mdlWin32_DdeQueryNextServer	(	HCONVLIST	hConvList,
		HCONV	hConvPrev
	)

mdlWin32_DdeQueryNextServer obtains the next conversation handle in the

given conversation list.

Parameters

[in]	hConvList	identifies the conversation list. This handle must have been created by a previous call to mdlWin32_DdeConnectList.
[in]	hConvPrev	identifies the conversation handle previously returned by this function. If this parameter is NULL, this function returns the first conversation handle in the list.

Returns: mdlWin32_DdeQueryNextServer returns the next conversation handle in the list. A NULL is returned when there are no more conversations.

See also: mdlWin32_DdeConnectList mdlWin32_DdeDisconnectList

Remarks: Required Library: mdlbltin.lib

DWORD mdlWin32_DdeQueryString	(	DWORD	idInst,
		HSZ	hsz,
		LPSTR	psz,
		DWORD	cchMax,
		int	iCodePage
	)

mdlWin32_DdeQueryString copies text associated with a string handle

into a buffer.

The string returned in the buffer is always NULL-terminated. If the string is longer than (cchMax - 1), only the first (cchMax - 1) characters of the string are copied. If the lpsz parameter is NULL, this function obtains the length, in bytes, of the string associated with the string handle. The length does not include the terminating NULL character.

Parameters

[in]	idInst	specifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize.
[in]	hsz	identifies the string to copy. This handle must have been created by a previous call to mdlWin32_DdeCreateStringHandle.
[in]	psz	points to a buffer that receives the string. To obtain the length of the string, this parameter should be set to NULL.
[in]	cchMax	specifies the length, in characters, of the buffer pointed to by the lpsz parameter. If the string is longer than (cchMax - 1), it will be truncated. If the lpsz parameter is set to NULL, this parameter is ignored.
[in]	iCodePage	specifies the code page used to render the string. This value should be either CP_WINANSI or CP_WINUNICODE.

Returns: mdlWin32_DdeQueryString returns 0 (meaning an error occurred) or a length. If psz specified a valid pointer, the return value is the length (in characters) of the returned text (not including the terminating NULL character). If the psz parameter specified a NULL pointer, the return value is the length of the text associated with the hsz parameter (not including the terminating NULL character).

See also: mdlWin32_DdeCmpStringHandles mdlWin32_DdeCreateStringHandle mdlWin32_DdeFreeStringHandle mdlWin32_DdeInitializeC

Remarks: Required Library: mdlbltin.lib

HCONV mdlWin32_DdeReconnect ( HCONV hConv )

mdlWin32_DdeReconnect allows a client application to attempt to reestablish

a conversation with a service that has terminated.

When the conversation is reestablished, the MDL-DDEML attempts to reestablish any preexisting advise loops.

Parameters

[in] hConv identifies the conversation to be reestablished. A client must have obtained the conversation handle by a previous call to mdlWin32_DdeConnect or from an XTYP_DISCONNECT transaction.

Returns: mdlWin32_DdeReconnect returns the value of the handle of the reestablished conversation; otherwise, it is NULL. Use mdlWin32_DdeGetLastError to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_INVALIDPARAMETER, DMLERR_NO_CONV_ESTABLISHED, DMLERR_NO_ERROR.

See also: mdlWin32_DdeConnect mdlWin32_DdeDisconnect

Remarks: Required Library: mdlbltin.lib

BOOL mdlWin32_DdeSetUserHandle	(	HCONV	hConv,
		DWORD	id,
		DWORD	hUser
	)

mdlWin32_DdeSetUserHandle associates an application-defined 32-bit value

with a conversation handle or a transaction identifier.

This is useful for simplifying the processing of asynchronous transactions. mdlWin32_DdeQueryConvInfo can be used to retrieve this value.

Parameters

[in]	hConv	identifies the conversation.
[in]	id	specifies 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.
[in]	hUser	identifies the value to associate with the conversation handle.

Returns: mdlWin32_DdeSetUserHandle returns true if the function succeeds; otherwise, it is false. Use mdlWin32_DdeGetLastError to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_INVALIDPARAMETER, DMLERR_NO_ERROR, DMLERR_UNFOUND_QUEUE_ID.

See also: mdlWin32_DdeQueryConvInfo

Remarks: Required Library: mdlbltin.lib

BOOL mdlWin32_DdeUnaccessData ( HDDEDATA hData )

mdlWin32_DdeUnaccessData unaccesses a DDE data object.

An application must call this function when it is finished accessing the object. This function is used with mdlWin32_DdeAccessData.

Parameters

[in] hData identifies the DDE data object.

Returns: mdlWin32_DdeUnaccessData returns true if the function succeeds, otherwise, false. Use the mdlWin32_DdeGetLastError function to retrieve the error value, which may be one of the following: DMLERR_DLL_NOT_INITIALIZED, DMLERR_INVALIDPARAMETER, DMLERR_NO_ERROR.

See also: mdlWin32_DdeAccessData mdlWin32_DdeAddData mdlWin32_DdeCreateDataHandle mdlWin32_DdeFreeDataHandle

Remarks: Required Library: mdlbltin.lib

BOOL mdlWin32_DdeUninitialize ( DWORD idInst )

The mdlWin32_DdeUninitialize function terminates any conversations

currently open and frees all of the DDE resources associated with the calling application.

Parameters

[in] idInst specifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function.

Returns: mdlWin32_DdeUninitialize returns true if the function succeeds, false otherwise.

See also: mdlWin32_DdeDisconnect mdlWin32_DdeDisconnectList mdlWin32_DdeInitialize

Remarks: Required Library: mdlbltin.lib

Functions

Detailed Description

Function Documentation