CeAllocDuplicateBuffer
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
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
| Header | pkfuncs.h |
| Library | coredll.lib |
| Windows Embedded CE | Windows Embedded CE 6.0 and later |
See Also
Reference
Kernel Buffer Marshaling Functions
DuplicatedBuffer_t
CeFreeDuplicateBuffer
CeOpenCallerBuffer
CeAllocAsynchronousBuffer