DdeAddData

3.1

  #include <ddeml.h>    

  HDDEDATA DdeAddData(hData, lpvSrcBuf, cbAddData, offObj)    
  HDDEDATA hData; /* handle of global memory object */
  void FAR* lpvSrcBuf; /* address of source buffer */
  DWORD cbAddData; /* length of data, */  
  DWORD offObj; /* offset within global memory object */

The DdeAddData function adds data to the given global memory 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.

Parameters

hData

Identifies the global memory object that receives additional data.

lpvSrcBuf

Points to a buffer containing the data to add to the global memory object.

cbAddData

Specifies the length, in bytes, of the data to be added to the global memory object.

offObj

Specifies an offset, in bytes, from the beginning of the global memory object. The additional data is copied to the object beginning at this offset.

Return Value

The return value is a new handle of the global memory object if the function is successful. The new handle should be used in all references to the object. The return value is zero if an error occurs.

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

After a data handle has been used as a parameter in another Dynamic Data Exchange Management Library (DDEML) function or returned by a DDE callback function, the handle may only be used for read access to the global memory object identified by the handle.

If the amount of global memory originally allocated is not large enough to hold the added data, the DdeAddData function will reallocate a global memory object of the appropriate size.

Example

The following example creates a global memory object, uses the DdeAddData function to add data to the object, and then passes the data to a client with an XTYP_POKE transaction:

DWORD idInst;          /* instance identifier     */
HDDEDATA hddeStrings;  /* data handle             */
HSZ hszMyItem;         /* item-name string handle */
DWORD offObj = 0;      /* offset in global object */
char szMyBuf[16];      /* temporary string buffer */
HCONV hconv;           /* conversation handle     */
DWORD dwResult;        /* transaction results     */
BOOL fAddAString;      /* TRUE if strings to add  */

/* Create a global memory object. */

hddeStrings = DdeCreateDataHandle(idInst, NULL, 0, 0,
    hszMyItem, CF_TEXT, 0);

/*
 * If a string is available, the application-defined function
 * IsThereAString() copies it to szMyBuf and returns TRUE. Otherwise,
 * it returns FALSE.
 */

while ((fAddAString = IsThereAString())) {

    /* Add the string to the global memory object. */

    DdeAddData(hddeStrings,             /* data handle        */
        &szMyBuf,                       /* string buffer      */
        (DWORD) strlen(szMyBuf) + 1,    /* character count    */
        offObj);                        /* offset in object   */

    offObj = (DWORD) strlen(szMyBuf) + 1; /* adjust offset */
}

/* No more data to add, so poke it to the server. */

DdeClientTransaction((void FAR*) hddeStrings, -1L, hconv, hszMyItem,
    CF_TEXT, XTYP_POKE, 1000, &dwResult);

See Also

DdeAccessData, DdeCreateDataHandle, DdeGetLastError, DdeUnaccessData