CITextToSelectTree

[This is preliminary documentation and subject to change.]

CITextToSelectTree creates a DBCOMMANDTREE from an Index Server query language string. The command tree returned by this function can be used as the next sibling under a DBOP_table_name node. A DBOP_project node is also required to form a complete command tree.

STDAPI CITextToSelectTree(
  WCHAR const * pwszRestriction,
  DBCOMMANDTREE * * ppTree,
  ULONG cProperties,
  CIPROPERTYDEF * pProperties,
  LCID LocaleID
);
 

Parameters

pwszRestriction

[in] Points to a null-terminated string specifying an Index Server query. The syntax for queries is described in the Index Server documentation.

ppTree

[out] Address of output variable that receives the command tree built by the function.

cProperties

[in] Count of properties in the pProperties array, or 0 if pProperties is 0.

pProperties

[in] Address of an array of properties that can be referred to by friendly name in pwszRestriction. Column names in the wcsFriendlyName field of each CIPROPERTYDEF must be specified in uppercase. Index Server's built-in properties do not need to be defined to be used. It is an error to define a property with the same friendly name as a built-in property.

LocaleID

[in] The locale ID used for nodes in the tree returned in ppTree that contain an LCID field, including content restrictions and sort order.

Return Values

An HRESULT, S_OK if successful.

Remarks

Command trees created by CITextToSelectTree contain the select portion of a DBCOMMANDTREE. A tree returned by CITextToSelectTree can be combined with project and sort nodes to form a complete command tree. Use CITextToSelectTree instead of CITextToFullTree if the sort order and project columns tree nodes are already available.

The query tree allocated by CITextToSelectTree must be freed either with ICommandTree::FreeCommandTree or passed to ICommandTree::SetCommandTree with the fCopy parameter set to FALSE.

Example

This example creates a DBCOMMANDTREE. A custom property from a Microsoft® Word document named "IssueNumber" of type "Number" is defined and used in the query.

DBCOMMANDTREE * pCompleteTree; 
DBCOMMANDTREE * pTableNode;
 
// ...
// Insert code here to make pCompleteTree a complete tree using pTableNode
// as the DBOP_table_name node that has no query restriction (yet).
// User CoTaskMemAlloc to allocate memory for the nodes.
// ...
//
 
CIPROPERTYDEF aProperties[1];
const GUID guidOffice = { 0xd5cdd505, 0x2e9c, 0x101b,
                          0x93, 0x97, 0x08, 0x00, 0x2b, 0x2c, 0xf9, 0xae }
                            };
aProperties[0].wcsFriendlyName = L"ISSUENUMBER";
aProperties[0].dbType = DBTYPE_R8;
aProperties[0].dbCol.uGuid.guid = guidOffice;
aProperties[0].dbCol.eKind = DBKIND_GUID_NAME;
aProperties[0].dbCol.pwszName.ulPropid = L"ISSUENUMBER";
DBCOMMANDTREE * pSelectTree;
HRESULT hr = CiTextToSelectTree( L"microsoft and @issuenumber=2",
                                 &pSelectTree,
                                 1,
                                 aProperties,
                                 GetSystemDefaultLCID() );
if ( SUCCEEDED( hr ) )
{
    pTableNode->pctNextSibling = pSelectTree;
    hr = pICommand->SetCommandTree( pCompleteTree,
                                    DBCOMMANDREUSE_NONE,
                                    FALSE );
    if ( SUCCEEDED( hr ) )
    {
        // ...
        // execute a query
        // ...
    }
}
 

This is the DBCOMMANDTREE pSelectTree created by the example code:

DBCOMMANDTREE pSelectTree Created by Example Code