Functions
DDEFunctions

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]idInstspecifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function.
[in]hConvidentifies the conversation in which the transaction was initiated. If NULL, all transactions are abandoned (the idTransaction parameter is ignored).
[in]idTransactionidentifies 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]hDataidentifies the DDE object to access.
[out]pcbDataSizepoints 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]hDataidentifies the DDE data object that receives additional data.
[in]pSrcpoints to a buffer containing the data to add to the DDE data object.
[in]cbspecifies the length, in bytes, of the data to be added to the DDE data object.
[in]cbOffspecifies 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]pDatapoints 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]cbDataspecifies 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]hConvidentifies the conversation in which the transaction is to take place.
[in]hszItemidentifies 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]wFmtspecifies 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]wTypespecifies 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]dwTimeoutspecifies 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]pdwResultpoints 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]hsz1specifies the second string handle to compare.
[in]hsz2specifies 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]idInstspecifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function.
[in]hszServicespecifies 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]hszTopicspecifies 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]pCCpoints 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]idInstspecifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize.
[in]hszServiceidentifies 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]hszTopicidentifies 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]hConvListidentifies the conversation list to be enumerated. This parameter should be set to NULL if a new conversation list is to be established.
[in]pCCpoints 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]idInstspecifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize.
[in]pSrcpoints 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]cbspecifies the amount, in bytes, of memory to allocate for the DDE data object. If this parameter is zero, the pSrcBuf parameter is ignored.
[in]cbOffspecifies 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]hszItemidentifies 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]wFmtspecifies the standard clipboard format number of the data.
[in]afCmdspecifies 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]idInstspecifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function.
[in]pszpoints to a buffer that contains the NULL terminated string for which a handle is to be created. This string may be any length.
[in]iCodePagespecifies 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]hConvidentifies 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]hConvListidentifies 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]idInstspecifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function.
[in]hConvidentifies the conversation to enable or disable. If this parameter is NULL, the function affects all conversations.
[in]wCmdspecifies 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]hDataidentifies 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]idInstspecifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function.
[in]hszidentifies 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]hDataidentifies the DDE data object that contains the data to copy.
[in,out]pDstpoints 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]cbMaxspecifies 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]cbOffspecifies 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]idInstspecifies 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]hConva 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]lpidInstreturns 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]pfnCallbackFuncpoints 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]afCmdFilterFlagsspecifies 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]uReservedis 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]idInstspecifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize.
[in]hszidentifies 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]idInstspecifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize.
[in]hsz1identifies 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]hsz2is reserved and should be set to NULL.
[in]afCmdspecifies 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]idInstspecifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize.
[in]hszTopicidentifies 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]hszItemidentifies 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]hConvidentifies the conversation.
[in]idTransactionspecifies 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]pConvInfopoints 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]hConvListidentifies the conversation list. This handle must have been created by a previous call to mdlWin32_DdeConnectList.
[in]hConvPrevidentifies 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]idInstspecifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize.
[in]hszidentifies the string to copy. This handle must have been created by a previous call to mdlWin32_DdeCreateStringHandle.
[in]pszpoints to a buffer that receives the string. To obtain the length of the string, this parameter should be set to NULL.
[in]cchMaxspecifies 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]iCodePagespecifies 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]hConvidentifies 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]hConvidentifies the conversation.
[in]idspecifies 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]hUseridentifies 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]hDataidentifies 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]idInstspecifies 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

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.