CeOpenCallerBuffer

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

This function checks access and marshals a buffer pointer from the source process so that it can be accessed by the current process. It returns the marshaled pointer. This function allocates resources that must be freed by a subsequent call to CeCloseCallerBuffer.

Syntax

HRESULT CeOpenCallerBuffer(
  PVOID * ppDestMarshalled,
  PVOID pSrcUnmarshalled,
  DWORD cbSrc,
  DWORD ArgumentDescriptor
  BOOL ForceDuplicate
);

Parameters

• ppDestMarshalled
  [out] Receives a pointer that the current process can use to access the buffer synchronously.

• pSrcUnmarshalled
  [in] Pointer to the caller's data, to be access checked, marshaled, and possibly duplicated.

• cbSrc
  [in] Size of the caller's buffer, in bytes. If the 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 argument the buffer is. For example, ARG_I_WSTR or ARG_O_PTR. ARG_DW is not a valid descriptor for marshaling.

• ForceDuplicate
  [in] Indicates whether a temporary heap buffer must be allocated in the current process. Set to FALSE to allow CeOpenCallerBuffer to select the most efficient marshaling method.

Return Value

• E_ACCESSDENIED
  The source buffer was an invalid address, or your code does not have sufficient privileges to access the memory.

• E_INVALIDARG
  The pSrcUnmarshalled parameter was NULL, the length was zero, or some other argument was invalid.

• E_OUTOFMEMORY
  The memory allocation failed.

• S_OK
  The allocation and duplication, if necessary, succeeded.

Remarks

Duplication prevents asynchronous modification of the buffer by the caller. If duplication is not required for security purposes, do not use it. Then CeOpenCallerBuffer can select the most efficient marshaling method for best performance.

If duplication is required, 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. If duplication is not required, CeOpenCallerBuffer may still duplicate the buffer, or it may allocate virtual address space in the current process with the VirtualAlloc function and point it at the caller process' memory with the VirtualCopy function to create an alias to the same memory. In all cases, any required write-back to the source buffer is managed by CeCloseCallerBuffer.

This call uses ReadProcessMemory and WriteProcessMemory. If your code is running at a low enough privilege level that it does not have access to those APIs, this call fails and returns E_ACCESSDENIED.

This function does not allocate any resources if the call fails or if the source buffer is NULL. If this call fails for any reason, the pointer returned in ppDestMarshalled is not changed.

This function opens the caller buffer for synchronous access during an API call. You must call CeAllocAsynchronousBuffer to use the buffer returned by CeOpenCallerBuffer asynchronously. Do not close the caller buffer until after you have called CeFreeAsynchronousBuffer.

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

Use the SUCCEEDED and FAILED macros to test the return value of this function.

Requirements

See Also

Reference

Kernel Buffer Marshaling Functions
MarshalledBuffer_t
CeCloseCallerBuffer
VirtualCopy
CeAllocAsynchronousBuffer
CeAllocDuplicateBuffer

Other Resources

VirtualAlloc
ReadProcessMemory
WriteProcessMemory
Kernel Migration