Share via

CeAllocDuplicateBuffer (Compact 2013)

  • Article

3/28/2014

This function abstracts the work required to make secure copies of API parameters. The duplicated buffer will not 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, 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.

When using a buffer marshaled by CeOpenCallerBuffer, have CeOpenCallerBuffer do the duplication instead of CeAllocDuplicateBuffer.

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

Header

kernsdk.h

Library

coredll.lib

See Also

Reference

Kernel Buffer Marshaling Functions
DuplicatedBuffer_t
CeFreeDuplicateBuffer
CeOpenCallerBuffer
CeAllocAsynchronousBuffer