CeRapiInitEx (RAPI) (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/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

Share via