Retrieving a Sensor Object

To retrieve a sensor object, you use the ISensorManager interface. You can think of this interface as the root interface for the Sensor API. To use ISensorManager, you must first call the COM CoCreateInstance method.

The following example code creates an instance of the sensor manager.

// Create the sensor manager.
hr = CoCreateInstance(CLSID_SensorManager, 
                        NULL, CLSCTX_INPROC_SERVER,
                        IID_PPV_ARGS(&pSensorManager));

if(hr == HRESULT_FROM_WIN32(ERROR_ACCESS_DISABLED_BY_POLICY))
{
    // Unable to retrieve sensor manager due to 
    // group policy settings. Alert the user.
}

After successfully retrieving a pointer to ISensorManager, you can retrieve sensors by category, type, or ID. If you retrieve sensors by type or category, you receive a pointer to an ISensorCollection interface that contains all the available sensors that belong to the requested category or type. If you retrieve a sensor by its ID, you receive a pointer to an ISensor interface that represents the unique sensor you requested.

The following example code retrieves a collection of sensors that belong to the category named SAMPLE_SENSOR_CATEGORY_DATE_TIME. The code then retrieves the first sensor in the collection by its index.

// Get the sensor collection.
hr = pSensorManager->GetSensorsByCategory(SAMPLE_SENSOR_CATEGORY_DATE_TIME, &pSensorColl);
  
if(SUCCEEDED(hr))
{
    ULONG ulCount = 0;

    // Verify that the collection contains
    // at least one sensor.
    hr = pSensorColl->GetCount(&ulCount);

    if(SUCCEEDED(hr))
    {
        if(ulCount < 1)
        {
            wprintf_s(L"\nNo sensors of the requested category.\n");
            hr = E_UNEXPECTED;
        }
    }
}

if(SUCCEEDED(hr))
{
    // Get the first available sensor.
    hr = pSensorColl->GetAt(0, &pSensor);
}

Note that you can retrieve all of the available sensors by using SENSOR_CATEGORY_ALL.

In a similar way, you can retrieve sensors of a particular type.

The following example code retrieves a collection of sensors of the type named SAMPLE_SENSOR_TYPE_TIME. The code then retrieves the first sensor in the collection by its index.

// Get the sensor collection.
hr = pSensorManager->GetSensorsByType(SAMPLE_SENSOR_TYPE_TIME, &pSensorColl);
  
if(SUCCEEDED(hr))
{
    ULONG ulCount = 0;

    // Verify that the collection contains
    // at least one sensor.
    hr = pSensorColl->GetCount(&ulCount);

    if(SUCCEEDED(hr))
    {
        if(ulCount < 1)
        {
            wprintf_s(L"\nNo sensors of the requested type.\n");
            hr = E_UNEXPECTED;
        }
    }
}

if(SUCCEEDED(hr))
{
    // Get the first available sensor.
    hr = pSensorColl->GetAt(0, &pSensor);
}

To retrieve a sensor by its ID, you must know the unique ID for the sensor. Sensors usually generate this ID when first connected to enable you to identify multiple sensors of the same make and model. This means that you probably will not know the sensor ID in advance. However, if you have stored a copy of a particular sensor ID that you previously retrieved, for example by calling ISensor::GetID, you may want to retrieve the same sensor again.

The following example code shows how to retrieve a sensor by using its ID.

ISensor* pSensor = NULL;

// Get the sensor collection.
hr = pSensorManager->GetSensorByID(SAMPLE_SENSOR_TIME_ID, &pSensor);

You can also retrieve sensors when they become available by receiving an event from the sensor manager. For more information, see ISensorManager::SetEventSink.

Related topics

ISensorManagerEvents::OnSensorEnter