CITextToFullTree function

[Indexing Service is no longer supported as of Windows XP and is unavailable for use as of Windows 8. Instead, use Windows Search for client side search and Microsoft Search Server Express for server side search.]

Creates a full command tree using Query Language 1.

Syntax


HRESULT __stdcall CITextToFullTree(
  const WCHAR *pwszRestriction,
  const WCHAR *pwszColumns,
  const WCHAR *pwszSortColumns,
  const WCHAR *pwszGroupings,
  DBCOMMANDTREE **ppTree,
  ULONG cProperties,
  CIPROPERTYDEF *pProperties,
  LCID LocaleID
);

Parameters

pwszRestriction

A pointer to a null-terminated string that specifies an Indexing Service query language, Dialect 1 query.

pwszColumns

A pointer to a null-terminated string that specifies a comma-separated list of column names returned in the query results. These columns can be bound by OLE DB accessors.

pwszSortColumns

A pointer to a null-terminated string that contains a comma separated list of column names that specify the sort order for the query results. A sort direction can be appended to each column name. Use [d] for descending, and [a] for ascending. If no sort order is specified, ascending is the default. This parameter can be NULL for no sort order.

pwszGroupings

A pointer to a null-terminated string that contains a grouping specification made up of a type (currently only [unique] is supported), a property name, and a sort order ([a] for ascending or [d] for descending). In a unique grouping, unique values of the column set form the individual categories. This parameter is optional.

The syntax for the unique grouping term is:

unique fname [ {[a]|[d]} ] [ , fname2 {[a]|[d]} ... ]

where fname and fname2 are the assigned friendly names.

Column names separated by a plus sign (+) are grouped in individual categories, and column names following a comma (,) are grouped together into subgroups of the preceding grouping.

ppTree

A pointer to an output variable that receives a pointer to the DBCOMMANDTREE structure for the command tree built by the function.

cProperties

The number of properties in the pProperties array, or NULL if pProperties is zero.

pProperties

A pointer to an array of properties that can be referred to by friendly names in the pwszColumns, pwszSortColumns, pwszGroupings, and pwszRestriction parameters. Column names in the wcsFriendlyName member of each CIPROPERTYDEF structure must be specified in uppercase. This parameter can be NULL if no properties are being defined and cProperties is zero. Indexing Service'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 that of a built-in property.

LocaleID

The locale identifier (LCID) used for nodes in ppTree that contain an LCID member, including such nodes as content restrictions, sort order, and so on.

Return value

This function can return one of these values.

Return codeDescription
S_OK

The operation was completed successfully.

E_HANDLE

The function encountered an invalid handle, probably due to a low-memory situation.

E_INVALIDARG

The function received an invalid parameter.

E_OUTOFMEMORY

The function did not have sufficient memory or other resources to complete the operation.

E_FAIL

An unknown error has occurred.

 

Remarks

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

Be sure to include the following #define directive before your #include <oledberr.h> to access the command tree definitions.

#define DBINITCONSTANTS
#include <oledberr.h> 
#include <oledb.h> 
#include <cmdtree.h>

Examples

This sample code creates a command tree. A custom property from a Microsoft Word document named "IssueNumber" of type "Number" is defined and used in the query. The list of properties returned by the query includes path and size. The sort order is first by rank descending, then by path ascending. The default system locale is used to create the command tree.


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 * pTree;
HRESULT hr = CiTextToFullTree( L"microsoft and @issuenumber=2",
                               L"size,path,issuenumber",
                               L"rank[d],path[a]",
                               ,
                               &pTree,
                               1,
                               aProperties,
                               GetSystemDefaultLCID() );
if ( SUCCEEDED( hr ) )
{
    hr = pICommandTree->SetCommandTree( pTree,
                                    DBCOMMANDREUSE_NONE,
                                    FALSE );
    if ( SUCCEEDED( hr ) )
    {
        // ...
        // execute a query
        // ...
    }
}


The following diagram shows the pTree parameter, created by the example code, of the DBCOMMANDTREE structure.

ms690933.dbcmdtr2(en-us,VS.85).png

Requirements

Minimum supported client

Windows 2000 Professional (desktop apps only)

Minimum supported server

Windows 2000 Server (desktop apps only)

End of client support

Windows 7

End of server support

Windows Server 2008 R2

Header

Ntquery.h

Library

Ntquery.lib

DLL

Ntquery.dll

See also

CIPROPERTYDEF
DBCOMMANDTREE
ICommandTree

 

 

Build date: 9/10/2012

Community Additions

ADD
Show: