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... | |
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.
[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. |
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.
[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. |
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.
[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. |
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.
[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. |
[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. |
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).
[in] | hsz1 | specifies the second string handle to compare. |
[in] | hsz2 | specifies the second string handle to compare. |
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. |
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.
[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. |
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).
[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. |
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.
[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. |
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.
[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. |
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.
[in] | hConv | identifies the active conversation to be terminated. |
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.
[in] | hConvList | identifies the conversation list. This handle must have been created by a previous call to the mdlWin32_DdeConnectList function. |
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.
[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. |
BOOL mdlWin32_DdeFreeDataHandle | ( | HDDEDATA | hData | ) |
The mdlWin32_DdeFreeDataHandle function frees a DDE data object and deletes
the data handle associated with the object.
[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. |
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.
[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. |
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.
[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. |
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.
[in] | idInst | specifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function. |
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. |
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.
[in] | hConv | a handle to the DDE conversation |
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.
[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. |
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. |
[in] | uReserved | is reserved and must be set to 0. |
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.
[in] | idInst | specifies the application-instance identifier obtained by a previous call to mdlWin32_DdeInitialize. |
[in] | hsz | identifies the string handle to be saved. |
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.
[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:
|
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.
[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. |
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.
[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. |
HCONV mdlWin32_DdeQueryNextServer | ( | HCONVLIST | hConvList, |
HCONV | hConvPrev | ||
) |
mdlWin32_DdeQueryNextServer obtains the next conversation handle in the
given conversation list.
[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. |
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.
[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. |
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.
[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. |
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.
[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. |
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.
[in] | hData | identifies the DDE data object. |
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.
[in] | idInst | specifies the application-instance identifier obtained by a previous call to the mdlWin32_DdeInitialize function. |