CeRapiInitEx (RAPI)

Article
08/28/2006

This function asyncronously initializes the communication layers between the desktop and the target Windows CE-based remote device. CeRapiInit or CeRapiInitEx must be called before calling any of the other RAPI methods.

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 Values

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

Pocket PC: Pocket PC 2002 and later
Smartphone: Smartphone 2002 and later
OS Versions: Windows CE 3.0 and later
Header: Rapi.h
Library: Rapi.lib

Share via