DdeCreateDataHandle

3.1

#include <ddeml.h>

HDDEDATA DdeCreateDataHandle(idInst, lpvSrcBuf, cbInitData, offSrcBuf, hszItem, uFmt, afCmd)
DWORD idInst;	/* instance identifier, */
void FAR* lpvSrcBuf;	/* address of source buffer	*/
DWORD cbInitData;	/* length of global memory object	*/
DWORD offSrcBuf;	/* offset from beginning of source buffer	*/
HSZ hszItem;	/* handle of item-name string	*/
UINT uFmt;	/* clipboard data format, */
UINT afCmd;	/* creation flags, */

The DdeCreateDataHandle function creates a global memory object and fills the object with the data pointed to by the lpvSrcBuf parameter. A dynamic data exchange (DDE) application uses this function during transactions that involve passing data to the partner application.

Parameters

idInst

Specifies the application-instance identifier obtained by a previous call to the DdeInitialize function.

lpvSrcBuf

Points to a buffer that contains data to be copied to the global memory object. If this parameter is NULL, no data is copied to the object.

cbInitData

Specifies the amount, in bytes, of memory to allocate for the global memory object. If this parameter is zero, the lpvSrcBuf parameter is ignored.

offSrcBuf

Specifies an offset, in bytes, from the beginning of the buffer pointed to by the lpvSrcBuf parameter. The data beginning at this offset is copied from the buffer to the global memory object.

hszItem

Identifies the string that specifies the data item corresponding to the global memory object. This handle must have been created by a previous call to the DdeCreateStringHandle function. If the data handle is to be used in an XTYP_EXECUTE transaction, this parameter must be set to NULL.

uFmt

Specifies the standard clipboard format of the data.

afCmd

Specifies the creation flags. This parameter can be HDATA_APPOWNED, which specifies that the server application that calls the DdeCreateDataHandle function will own the data handle that this function creates. This makes it possible for the server to share the data handle with multiple clients instead of creating a separate handle for each request. If this flag is set, the server must eventually free the shared memory object associated with this handle by using the DdeFreeDataHandle function. If this flag is not set, after the data handle is returned by the server's DDE callback function or used as a parameter in another DDE Management Library function, the handle becomes invalid in the application that creates the handle.

Return Value

The return value is a data handle if the function is successful. Otherwise, it is NULL.

Errors

Use the 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

Comments

Any locations in the global memory 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 global memory object identified by the handle.

If the application will be adding data to the global memory object (using the DdeAddData function) so that the object exceeds 64K in length, then the application should specify a total length (cbInitData + offSrcData) that is equal to the anticipated maximum length of the object. This avoids unnecessary data copying and memory reallocation by the system.

Example

The following example processes the XTYP_WILDCONNECT transaction by returning a data handle to an array of HSZPAIR structures—one for each topic name supported:

#define CTOPICS 2

UINT type;
UINT fmt;
HSZPAIR ahp[(CTOPICS + 1)];
HSZ ahszTopicList[CTOPICS];
HSZ hszServ, hszTopic;
WORD i, j;

if (type == XTYP_WILDCONNECT) {

     /*
      * Scan the topic list and create array of HSZPAIR data
      * structures.
      */
    j = 0;
    for (i = 0; i < CTOPICS; i++) {
        if (hszTopic == (HSZ) NULL ||
                hszTopic == ahszTopicList[i]) {
            ahp[j].hszSvc = hszServ;
            ahp[j++].hszTopic = ahszTopicList[i];
        }
    }

    /*
     * End the list with an HSZPAIR structure that contains NULL
     * string handles as its members.
     */

    ahp[j].hszSvc = NULL;
    ahp[j++].hszTopic = NULL;

    /*
     * Return a handle to a global memory object containing the
     * HSZPAIR structures.
     */

    return DdeCreateDataHandle(
        idInst,          /* instance identifier     */
        &ahp,            /* points to HSZPAIR array */
        sizeof(HSZ) * j, /* length of the array     */
        0,               /* start at the beginning  */
        NULL,            /* no item-name string     */
        fmt,             /* return the same format  */
        0);              /* let the system own it   */
}