CeAllocDuplicateBuffer (Windows Embedded CE 6.0)

1/6/2010

This function abstracts the work required to make secure copies of API parameters. Do not use it for buffers other than API parameters. Do not expect the duplicated buffer to be accessible after the API call returns.

Syntax

HRESULT CeAllocDuplicateBuffer(
   PVOID * ppDestDuplicate,
  PVOID pSrcMarshalled,
  DWORD cbSrc,
   DWORD ArgumentDescriptor
);

Parameters

• ppDestDuplicate
  [out] Receives a pointer to a newly allocated heap buffer.

• pSrcMarshalled
  [in] Pointer to the caller's data that has already been marshaled.

• cbSrc
  [in] Size of the caller's buffer, in bytes. If ArgumentDescriptor is a WSTR or ASTR, a size of zero can be used. If the size of a string is non-zero, it must include a terminating NULL.

• ArgumentDescriptor
  [in] Descriptor explaining what kind of API parameter the buffer is. For example, ARG_I_WSTR or ARG_O_PTR. ARG_DW is not a valid descriptor for duplicating.

Return Value

• E_ACCESSDENIED
  The source buffer was an invalid address, possibly a pointer that has not been marshaled.

• E_INVALIDARG
  The pSrcMarshalled parameter was NULL, or the length was zero.

• E_OUTOFMEMORY
  The memory allocation failed.

• S_OK
  The allocation and copy succeeded.

Remarks

This function allocates a new heap buffer, copies data from the source buffer to the heap buffer, if necessary due to in descriptors ARG_I* or ARG_IO*, and returns the new heap buffer. This function allocates resources that must be freed by a subsequent call to CeFreeDuplicateBuffer. Any required write-back to the source buffer is managed by CeFreeDuplicateBuffer, if necessary due to out descriptors ARG_IO* or ARG_O*.

Duplication prevents asynchronous modification of the buffer by the caller. If duplication is not required for security purposes, do not use it. Just access the caller's buffer as passed to your API.

This function does not allocate any memory if the call fails or if the source buffer was NULL. If no memory is allocated, the pointer returned in ppDestDuplicate is NULL.

Do not use CeAllocDuplicateBuffer with a buffer marshaled by CeOpenCallerBuffer. Instead, have CeOpenCallerBuffer do the duplication.

You do not need to call CeAllocAsynchronousBuffer to use the buffer returned by CeAllocDuplicateBuffer asynchronously. The duplicate buffer can be used until it is closed by CeCloseCallerBuffer. CeAllocAsynchronousBuffer does not work on buffers that have been duplicated by CeAllocDuplicateBuffer.

This function is protected by __try/__except so that it does not to throw an exception while accessing the input pointer pSrcMarshalled.

Requirements

See Also

Reference

Kernel Buffer Marshaling Functions
DuplicatedBuffer_t
CeFreeDuplicateBuffer
CeOpenCallerBuffer
CeAllocAsynchronousBuffer

Other Resources

Kernel Migration