CeRapiInitEx (RAPI)
A version of this page is also available for
4/8/2010
This function asyncronously initializes the communication layers between the desktop and the target Windows Embedded CE-based remote device. CeRapiInit or CeRapiInitEx must be called before calling any of the other RAPI methods.
Syntax
HRESULT CeRapiInitEx(
RAPIINIT * pRapiInit
);
Parameters
- pRapiInit
[in] Pointer to a RAPIINIT structure. The cbSize member of this structure contains the size of the structure being passed in. Initially, a handle to an event is passed back in the heRapiInit member of this structure. When the connection is made or an error occurs, the event is set. The hrRapiInit member of this structure contains the value S_OK if the connection is successful, or E_FAIL if an error occurred.
Return Value
S_OK indicates success. E_FAIL indicates failure. E_INVALIDARG indicates that an invalid value was encountered.
Remarks
Use CeRapiInitEx to initialize the RAPI session asynchronously. CeRapiInit can be used for synchronous initialization.
CeRapiInitEx returns immediately and continues asynchronous initialization until the connection is made, until an error occurs, or until there is a call to CeRapiUninit. When initialization is complete the event specified in the heRapiInit member of the RAPIINIT structure is set.
After calling CeRapiInitEx, check the return value to see if an error occurred. If the call was successful, call the MsgWaitForMultipleObjects function to wait for the event handle to be passed back in the heRapiInit member of the RAPIINIT structure. When the event is set, check the hrRapiInit member of the structure to determine whether the connection was successful.
To shut down or to abort the connection process, call the CeRapiUnInit function.
Code Example
The following code example illustrates how to use CeRapiInitEx to initialize RAPI asyncronously.
HRESULT TryRapiConnect(DWORD dwTimeOut)
{
HRESULT hr = E_FAIL;
RAPIINIT riCopy;
bool fInitialized = false;
ZeroMemory(&riCopy, sizeof(riCopy));
riCopy.cbSize = sizeof(riCopy);
hr = CeRapiInitEx(&riCopy);
if (SUCCEEDED(hr))
{
DWORD dwRapiInit = 0;
fInitialized = true;
dwRapiInit = WaitForSingleObject(
riCopy.heRapiInit,
dwTimeOut);
if (WAIT_OBJECT_0 == dwRapiInit)
{
// heRapiInit signaled:
// set return error code to return value of RAPI Init function
hr = riCopy.hrRapiInit;
}
else if (WAIT_TIMEOUT == dwRapiInit)
{
// timed out: device is probably not connected
// or not responding
hr = HRESULT_FROM_WIN32(ERROR_TIMEOUT);
}
else
{
// WaitForSingleObject failed
hr = HRESULT_FROM_WIN32(GetLastError());
}
}
if (fInitialized && FAILED(hr))
{
CeRapiUninit();
}
return hr;
}
Requirements
| Header | rapi.h |
| Library | rapi.lib |
| Windows Embedded CE | Windows CE 3.0 and later |
| Windows Mobile | Pocket PC 2002 and later, Smartphone 2002 and later |