CeCallUserProc (Compact 2013)
3/28/2014
This function loads the user interface (UI) proxy device driver.
Syntax
BOOL CeCallUserProc(
LPCWSTR pszDllName,
LPCWSTR pszFuncName,
LPVOID lpInBuffer,
DWORD nInBufferSize,
LPVOID lpOutBuffer,
DWORD nOutBufferSize,
LPDWORD lpBytesReturned
);
Parameters
- pszDllName
[in] UI proxy device driver to load.
- pszFuncName
[in] UI proxy device driver entry point. For information about this entry point, see PFN_UIENTRYPOINT.
- lpInBuffer
[in] Data to pass to the UI proxy device driver.
- nInBufferSize
[in] Size of the data passed to the UI proxy device driver.
- lpOutBuffer
[out] Data returned by the UI proxy device driver.
- nOutBufferSize
[out] Size of the data returned by the UI proxy device driver.
- lpBytesReturned
[out] Size in bytes of the data returned by the UI proxy device driver.
Return Value
TRUE indicates success. The lpOutBuffer parameter contains the data returned by the UI proxy device driver, and lpBytesReturned contains the amount of data returned by the UI proxy device driver.
FALSE indicates failure. Call GetLastError on the thread that made the function call to obtain error information. In this case, lpOutBuffer and lpBytesReturned remain unchanged.
Remarks
Include the UI proxy device driver in your run-time image by setting SYSGEN_UIPROXY. By setting this Sysgen variable, the UI proxy device driver is automatically included in the run-time image and loaded the first time it is used.
If this function is called from user mode, the implementation is in Coredll, so it can run in the same process as the caller. If the function is called from a kernel-mode driver, the implementation is delegated to a UI proxy device driver loaded in udevice.exe.
The purpose of this function is for a kernel mode driver to call an API in a DLL that must be loaded outside the kernel. The driver defines a wrapper function with the specific signature and then passes the wrapper function and it's parameters to CeCallUserProc.
This function marshals the data from the kernel mode driver (or dll) to the user mode driver, the uiproxy driver. The user mode driver can use those arguments as is. No copying is required. On the call return, the [out] argument is marshaled back from the uiproxy driver to the kernel mode driver/dll.
The [in] and [out] arguments for this function cannot contain any embedded pointers.
One example of using this function is when a kernel mode driver wants to display UI to the user. Since displaying UI in the kernel is discouraged, the UI portion of the kernel mode driver can be written as a normal DLL. Then the kernel mode driver can call this function with the UI DLL name and the function name to load the UI DLL outside the kernel. The kernel makes sure that the UI DLL is loaded outside the kernel, calls the function in the DLL, passing the input parameters from the kernel mode driver, and returns the output parameter from the UI DLL to the kernel-mode driver once the UI operation is complete.
There is one limitation to the UI DLL design. Since the call to the UI DLL function comes in as a Program Static Library (PSL) call, none of the Transport Level Security (TLS) functions can be called in that UI DLL function implementation. If the UI DLL needs to use TLS functions, it should spawn a thread and do all the TLS operations on that thread.
Requirements
Header |
pkfuncs.h |
Library |
coredll.lib |