RAPI2 Initialization (Windows Embedded CE 6.0)

1/6/2010

The IRAPISession interface provides the methods that perform operations on the remote Windows Embedded CE-based device. This set of methods is essentially the same as the functions provided by the original RAPI library.

The IRAPISink interface should be implemented by RAPI2 applications in order to receive notifications from the connection manager when remote devices connect and disconnect.

The IRAPIDesktop, IRAPIEnumDevices, and IRAPIDevice interfaces are used to discover, query, and create a session with a connected device.

Use the following steps to initialize RAPI2 and create a session with a connected device.

1. Instantiate the IRAPIDesktop interface using COM's CoInitializeEx method.
2. Call IRAPIDesktop::Advise to register your applications implementation of the IRAPISink interface. This will alert your application when a device connects.
3. Once a device has connected, call IRAPIDesktop::EnumDevices to obtain an instance of the IRAPIEnumDevices interface.
4. Call IRAPIEnumDevices::Next to obtain an instance of the IRAPIDevice interface. This interface can be used to query for information about the selected device.
5. Call IRAPIDevice::CreateSession to establish a session with the selected device.
6. Initialize the underlying communications layer for the session by calling IRAPISession::CeRapiInit.
7. Call methods of the IRAPISession interface to perform operations on the connected device.

Code Example

The following code example illustrates the initialization of the RAPI2 interfaces.

int _tmain(int argc, _TCHAR* argv[])
{
      HRESULT hr = S_OK;

      // Initialize COM.
      hr = CoInitializeEx(NULL, COINIT_MULTITHREADED);

      // Create an instance of the IRAPIDesktop interface.
      IRAPIDesktop *pIRapiDesktop = NULL;
      hr = CoCreateInstance(CLSID_RAPI,
                            NULL,
                            CLSCTX_INPROC_SERVER,
                            IID_IRAPIDesktop,
                            (void**)&pIRapiDesktop);

      // Call EnumDevices to obtain an enumeration of connected devices.
      IRAPIEnumDevices *pIRapiEnumDevices = NULL;
      if (SUCCEEDED(hr) && pIRapiDesktop)
      {
            hr = pIRapiDesktop->EnumDevices(&pIRapiEnumDevices);
      }
      
      // Call Next to get an interface to the device.
      IRAPIDevice *pIRapiDevice = NULL;
      if (SUCCEEDED(hr) && pIRapiEnumDevices)
      {
            hr = pIRapiEnumDevices->Next(&pIRapiDevice);
      }

      // Call CreateSession to establish a session with the connected device.
      IRAPISession *pIRapiSession = NULL;
      if (SUCCEEDED(hr) && pIRapiDevice)
      {
            hr=pIRapiDevice->CreateSession(&pIRapiSession);
      }

      if (SUCCEEDED(hr) && pIRapiSession)
      {
            // Call CeRapiInit before you call any other IRAPISession methods.
            hr = pIRapiSession->CeRapiInit();
            if (FAILED(hr))
            {
                  hr = pIRapiSession->CeRapiGetError();
            }
            else
            {
                  // Make calls on the session object 
                  BOOL bRet = pIRapiSession->CeCheckPassword(TEXT("Password"));

                  if (!bRet)
                  {
                        hr = pIRapiSession->CeRapiGetError();
                        if(SUCCEEDED(hr)) // If no rapi errors, call CeGetLastError for the error on device
                        {
                              DWORD dwErr = pIRapiSession->CeGetLastError();
                        }
                  }
            }
      }
      
      return 0;

}

Note

When initializing the RAPI2 interfaces in a multi-threaded application, be mindful of the access restriction between apartments. If the RAPI2 interfaces are initialized in an STA thread, they will not be accessible from other apartments.

See Also

Other Resources

RAPI2 Application Development
RAPI2 Reference