Función DevCreateObjectQueryFromIds (devquery.h)

Crea una consulta de dispositivo para recuperar propiedades basadas en los parámetros de consulta especificados y una lista de identificadores de objeto.

Sintaxis

HRESULT DevCreateObjectQueryFromIds(
  [in]           DEV_OBJECT_TYPE                 ObjectType,
  [in]           PCZZWSTR                        pszzObjectIds,
  [in]           ULONG                           QueryFlags,
  [in]           ULONG                           cRequestedProperties,
  [in, optional] const DEVPROPCOMPKEY            *pRequestedProperties,
  [in]           ULONG                           cFilterExpressionCount,
  [in, optional] const DEVPROP_FILTER_EXPRESSION *pFilter,
  [in]           PDEV_QUERY_RESULT_CALLBACK      pCallback,
  [in, optional] PVOID                           pContext,
  [out]          PHDEVQUERY                      phDevQuery
);

Parámetros

[in] ObjectType

Valor de la enumeración DEV_OBJECT_TYPE que determina el tipo de objeto en el que debe funcionar esta consulta.

[in] pszzObjectIds

Una lista de varios sz de identificadores de objeto para los objetos en los que debe funcionar la consulta. Para obtener información sobre las cadenas de varios sz, vea REG_MULTI_SZ.

[in] QueryFlags

Combinación de DEV_QUERY_FLAGS valores que se combinan mediante una operación OR bit a bit.

[in] cRequestedProperties

Número de estructuras de DEVPROPCOMPKEY proporcionadas en pRequestedProperties. Si se especifica DevQueryFlagAllProperties, debe establecerse en 0.

[in, optional] pRequestedProperties

Opcionalmente, proporciona una matriz de estructuras de DEVPROPCOMPKEY que especifican las propiedades que se deben recuperar para los objetos del conjunto de resultados de la consulta cuando se llama a pCallback para notificar a la consulta una adición de un objeto a su conjunto de resultados.
Si se especificó DevQueryFlagUpdateResults en QueryFlags, se notificará a la consulta si el valor de cualquiera de estas propiedades cambia para cualquier objeto del conjunto de resultados de la consulta.

El campo LocaleName del estructura de DEVPROPCOMPKEY se omite y debe establecerse en NULL.

Si cRequestedProperties es 0, debe ser NULL.

[in] cFilterExpressionCount

Número de estructuras de DEVPROP_FILTER_EXPRESSION proporcionadas en pFilter.

[in, optional] pFilter

Opcionalmente, proporciona una matriz de estructuras de DEVPROP_FILTER_EXPRESSION que especifican criterios de filtro para qué objetos deben formar parte del conjunto de resultados de la consulta. Si cFilterExpressionCount es 0, debe ser NULL.

[in] pCallback

Una función de devolución de llamada PDEV_QUERY_RESULT_CALLBACK a la que se deben enviar los resultados de esta consulta.

[in, optional] pContext

Contexto proporcionado por el autor de la llamada. Este valor se pasa a la función de devolución de llamada sin modificar.

[out] phDevQuery

Puntero que recibe el identificador que representa la consulta. Si se especifica DevQueryFlagsUpdateResults, la consulta recibirá actualizaciones hasta que se cierre el identificador. Llame a DevCloseObjectQuery para cerrar este identificador para detener la consulta.

Valor devuelto

S_OK se devuelve si una consulta se creó correctamente; de lo contrario, es un valor de error adecuado.

Observaciones

Cuando un cliente quiere recuperar datos sobre un conjunto específico de objetos dado su identidad, use esta función en lugar de DevCreateObjectQuery con un filtro. Esta función es más eficaz.

Para obtener más información, vea la sección comentarios de DevCreateObjectQuery, que también se aplican a esta función.

Ejemplo

En el ejemplo siguiente, el método PDEV_QUERY_RESULT_CALLBACK se implementa para imprimir mensajes de estado cuando cambia el estado de la consulta, cuando los elementos se han agregado, actualizado o quitado del resultado de la consulta. A continuación, se implementa un escenario de consulta simple en el que se llama a DevCreateObjectQueryFromIds con una lista de varios sz de identificadores de objeto pasados a la función en el argumento InterfacePaths.

void WINAPI
Example1Callback(
    HDEVQUERY hDevQuery,
    PVOID pContext,
    const DEV_QUERY_RESULT_ACTION_DATA *pActionData
    )
{
    UNREFERENCED_PARAMETER(hDevQuery);
    UNREFERENCED_PARAMETER(pContext);

    switch (pActionData->Action)
    {
    case DevQueryResultStateChange:
        if (pActionData->Data.State == DevQueryStateEnumCompleted)
        {
            wprintf(L"Enumeration of current system state complete.\n");
        }
        else if (pActionData->Data.State == DevQueryStateAborted)
        {
            wprintf(L"Query has aborted. No further results will be received.\n");
            // Communicate back to the creator of the query that it has aborted
            // so it can handle that appropriately, such as by recreating the
            // query
        }
        break;

    case DevQueryResultAdd:
        wprintf(L"Object '%ws' has been added to the result set.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;

    case DevQueryResultUpdate:
        wprintf(L"Object '%ws' was updated.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;

    case DevQueryResultRemove:
        wprintf(L"Object '%ws' has been removed from the result set.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;
    }
}

void
Example1(PCZZWSTR InterfacePaths)
{
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_DeviceInterface_Enabled, DEVPROP_STORE_SYSTEM, NULL },
        { DEVPKEY_DeviceInterface_FriendlyName, DEVPROP_STORE_SYSTEM, NULL }
    };

    HDEVQUERY hDevQuery = NULL;
    HRESULT hr = DevCreateObjectQueryFromIds(DevObjectTypeDeviceInterface,
                                             InterfacePaths,
                                             DevQueryFlagUpdateResults,
                                             RTL_NUMBER_OF(RequestedProperties),
                                             RequestedProperties,
                                             0,
                                             NULL,
                                             Example1Callback,
                                             NULL,
                                             &hDevQuery);

    if (FAILED(hr))
    {
        wprintf(L"Failed to create query. hr = 0x%08x\n", hr);
        goto exit;
    }

    // do other work while the query monitors system state in the background

  exit:

    if (hDevQuery != NULL)
    {
        DevCloseObjectQuery(hDevQuery);
    }

    return;
}

Requisitos

Consulte también

DevCreateObjectQuery