IMLQuery (Compact 7)

3/12/2014

This interface contains methods to construct a query of items in the Media Library and enumerate the results of the query.

Methods

In addition to the methods inherited from IUnknown, this interface contains the following methods.

• IMLQuery::Reset
  Resets the IMLQuery object to its original empty state.

• IMLQuery::SetMAXResultsCount
  Sets the maximum number of rows to return from a query.

• IMLQuery::AddResultID
  Adds a Media Library property ID to the query results list.

• IMLQuery::AndBOOL
  Adds a logical AND clause with a Boolean property type to the query.

• IMLQuery::AndSHORT
  Adds a logical AND clause with a short integer property type to the query.

• IMLQuery::AndLONG
  Adds a logical AND clause with a long integer property type to the query.

• IMLQuery::AndLONGLONG
  Adds a logical AND clause with a long long integer property type to the query.

• IMLQuery::AndDATE
  Adds a logical AND clause with a date property type to the query.

• IMLQuery::AndBSTR
  Adds a logical AND clause with a Basic String (BSTR) property type to the query.

• IMLQuery::AndSTRING
  Adds a logical AND clause with a string property type to the query.

• IMLQuery::Prepare
  Prepares the IMLQuery object for use.

• IMLQuery::GetResultCount
  Returns the number of rows in the results set that the IMLCore::RunQuery object returned for this query.

• IMLQuery::GetResultByIndex
  Returns the property values for the indexed row in the query results.

• IMLQuery::SetDistinct
  Sets whether the query should be Distinct or not

Remarks

The IMLQuery interface builds a query that IMLCore uses to run the query (IMLCore::RunQuery). IMLCore::CountItemsretrieves the number of items that match the query call. IMLCore::Delete deletes items, and IMLCore::Update updates media entries in the library call.

Building a Query

The IMLQuery object must contain a valid query before you can use it in calls to IMLCore to run the query. The query is built with one or more calls to IMLQuery::And* methods. Each call to one of these methods adds a logical AND clause to the query with the property evaluation specified by the MLOperatorType operator.

After you build the query, you must call IMLQuery::Prepare to lock down the query. This call internally allocates memory for subsequent use of the IMLQuery object.

Before you call IMLCore::RunQuery, you must also set the property IDs to include the results set by calling IMLQuery::AddResultID. By default, the query only returns 10 results. To change the maximum number of results returned by the query, call IMLQuery::SetMAXResultsCount.

To view example code that shows how to create and build a query, see the Example section below.

The IMLQuery object can be used in calls to IMLCore to access the Media Library database

Retrieving Results from a Query

The call to IMLCore::RunQuery returns the results of the query to the IMLQuery object. You must call IMLQuery::GetResultCount to retrieve the number of rows in the results set and IMLQuery::GetResultByIndex to retrieve individual rows in the set. IMLQuery::GetResultByIndex returns an IMLPropertySet object that contains the list of properties in the row that can be enumerated based on index or property ID. IMLPropertySet only contains properties that were specifically requested by IMLQuery::AddResultID.

To view example code that shows how to retrieve results from a query, see the Code Example section below.

Obtaining a Pointer

This interface is created in the call to IMLFactory::CreateMLQuery.

Code Example

Example 1:

The following example code shows how to create and build the query.

HRESULT      hr = S_OK;
IMLCore     *pMLCore = NULL;
IMLFactory  *pMLFactory = NULL;
IMLQuery    *pQuery = NULL;
ULONG        cResults = 0;
ULONG        cTotalItems = 0;
ULONG        cTotalResults = 0;
MLRange      range;

hr = CoCreateInstance(CLSID_MLCore, NULL, CLSCTX_INPROC, IID_IMLCore, (LPVOID *)&pMLCore);

hr = pMLCore->GetFactory(&pMLFactory);
hr = pMLFactory->CreateMLQuery(&pQuery);

// Create a query using the properties
hr = pQuery->AndLONG(mlid_photo_height, GT, 1);
hr = pQuery->AndLONG(mlid_photo_height, LT, 4096);
    
// Specify the number of results to return
hr = pQuery->SetMAXResultsCount(10);

// Add a list of properties to the result list
hr = pQuery->AddResultID(mlid_photo_title);
hr = pQuery->AddResultID(mlid_photo_height);
hr = pQuery->AddResultID(mlid_photo_width);
hr = pQuery->AddResultID(mlid_photo_fileSize);
hr = pQuery->AddResultID(mlid_photo_fileURL);
hr = pQuery->AddResultID(mlid_photo_fileTime);

// Prepare the Query for repeated use
hr = pQuery->Prepare();

Example 2:

The following example code shows how to retrieve results from the query.

// Get the total count of items that match the IMLQuery
hr = pMLCore->CountItems(pQuery, &cTotalItems);

// Initialize the range object    
range.cSkip = 0;
range.cRequested = 10;
range.fReverse = FALSE;

do
{
    // Get the next batch of results
    hr = pMLCore->RunQuery(pQuery, range, NULL);
    hr = pQuery->GetResultCount(&cResults);
   
    if (cResults != 0)
    {
        // Iterate through the results and retrieve the properties
        for(ULONG iResult = 0; iResult < cResults; iResult++)
        {
            IMLPropertySet  *pResultProps = NULL;
            ULONG            cProps = 0;
            BSTR             bstrTitle = NULL;
            BSTR             bstrURL = NULL;
            LONG             width = 0;
            LONG             height = 0;
            MLDateTime       dtFile;
      
            hr = pQuery->GetResultByIndex(iResult, &pResultProps);

            if (pResultProps)
            {
                // Get the specific properties that should be
                // in the result set
                hr = pResultProps->GetBSTR(mlid_photo_title, &bstrTitle);
                hr = pResultProps->GetBSTR(mlid_photo_fileURL, &bstrURL);
                hr = pResultProps->GetLONG(mlid_photo_height, &height);
                hr = pResultProps->GetLONG(mlid_photo_width, &width);
                hr = pResultProps->GetDATE(mlid_photo_fileTime, &dtFile);
 
                // Do something interesting with the resulting values 
               // that are contained in bstrTitle, bstrURL, height,
                // width, dtFile here 
                // ...

                // Cleanup
                SysFreeString(bstrTitle);
                SysFreeString(bstrURL);

                // Release the interface retrieved by GetResultByIndex
                pResultProps->Release();
            }
        }
        
        // Move on to the next block of results
        cTotalResults += cResults;
        range.cSkip += cResults;
    }
} while(cResults != 0);

pMLFactory->Release();
pMLCore->Release();
 
return S_OK;
}

Requirements

See Also

Reference

Media Library Interfaces