| #include <ddeml.h> |
| UINT DdeInitialize(lpidInst, pfnCallback, afCmd, uRes) | |||||
| DWORD FAR* lpidInst; | /* address of instance identifier | */ | |||
| PFNCALLBACK pfnCallback; | /* address of callback function | */ | |||
| DWORD afCmd; | /* array of command and filter flags | */ | |||
| DWORD uRes; | /* reserved | */ | |||
The DdeInitialize function registers an application with the Dynamic Data Exchange Management Library (DDEML). An application must call this function before calling any other DDEML function.
lpidInst
Points to the application-instance identifier. At initialization, this parameter should point to 0L. If the function is successful, this parameter points to the instance identifier for the application. This value should be passed as the idInst parameter in all other DDEML functions that require it. If an application uses multiple instances of the DDEML dynamic link library, the application should provide a different callback function for each instance.
If lpidInst points to a nonzero value, this implies a reinitialization of the DDEML. In this case, lpidInst must point to a valid application-instance identifier.
pfnCallback
Points to the application-defined DDE callback function. This function processes DDE transactions sent by the system. For more information, see the description of the DdeCallback callback function.
afCmd
Specifies an array of APPCMD_ and CBF_ flags. The APPCMD_ flags provide special instructions to the DdeInitialize function. The CBF_ flags set filters that prevent specific types of transactions from reaching the callback function. 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 following flags:
| Flag | Meaning |
| 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. For details, see the following Comments section. |
| APPCLASS_STANDARD | Registers the application as a standard (nonmonitoring) DDEML application. |
| 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 DdeNameService or DdeInitialize function. This flag is always in effect when an application calls DdeInitialize for the first time, regardless of whether the application specifies this flag. On subsequent calls to 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 trans-actions. 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 own instance. 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. |
uRes
Reserved; must be set to 0L.
The return value is one of the following:
DMLERR_DLL_USAGE
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR
DMLERR_SYS_ERROR
An application that uses multiple instances of the DDEML must not pass DDEML objects between instances.
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.
A DDE monitoring application can combine one or more of the following monitor flags with the APPCLASS_MONITOR flag to specify the types of DDE activity to monitor:
| Flag | Meaning |
| 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 the DdeUninitialize function. |
| 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. |
The following example obtains a procedure-instance address for a DDE callback function, then initializes the application with the DDEML.
DWORD idInst = 0L;
FARPROC lpDdeProc;
lpDdeProc = MakeProcInstance((FARPROC) DDECallback, hInst);
if (DdeInitialize((LPDWORD) &idInst, (PFNCALLBACK) lpDdeProc,
APPCMD_CLIENTONLY, 0L))
return FALSE;DdeClientTransaction, DdeConnect, DdeCreateDataHandle, DdeEnableCallback, DdeNameService, DdePostAdvise, DdeUninitialize