//+----------------------------------------------------------------------------
//
//    Copyright (c) 2005 Microsoft Corporation.
//
//    File:     SearchQuery.idl
//
//    Purpose:  Search Query Helper Description
//
//    History:  08/13/2005     louisg      Modified
//
//-----------------------------------------------------------------------------

//
// Anyone can query catalogs using OLE-DB/ADO and this will remain
// true even with this API.
//
// Using ADO we do this:
//   con = CLSID_CADOConnection
//   con->Open(Connection string)
//   cmd = CLSID_CADOCommand
//   cmd->put_ActiveConnection(con);
//   cmd->put_Timeout(5)
//   cmd->put_CommandText
//   rows = CLSID_CADORowset / IID_IADORecordset
//   rows->put_CursorType(adOpenStatic)
//   rows->put_LockType(adLockReadOnly)
//   rows->put_CacheSize(250)
//   rows->Open(cmd) *** This is what executes the query and takes time ***
//   props = rows->get_Properties
//   props->get_Value("RowCount")
//   props->get_Value("Maximum Rank")
//   rows->GetRows
//
// The interfaces here are designed to do two things.
// 1) Make it simpler to query.
// 2) Expose AQS/NQS.
//

//**********************************************************************
// Query Helper
//**********************************************************************
[
    object,
    uuid(ISearchQueryHelper_GUID),
    pointer_default(unique)
]
interface ISearchQueryHelper: IUnknown
{
    //
    // Return the OLE-DB connection string
    //
    [propget]
    HRESULT ConnectionString([out, retval, string] LPWSTR *pszConnectionString);

    typedef enum _SEARCH_TERM_EXPANSION {
        // No Expansion
        SEARCH_TERM_NO_EXPANSION,

        // All search terms become <term>*
        SEARCH_TERM_PREFIX_ALL,

        // Stem expansion is applied to all terms
        SEARCH_TERM_STEM_ALL,
    } SEARCH_TERM_EXPANSION;

    typedef enum _SEARCH_QUERY_SYNTAX {
        // No query syntax in user input
        SEARCH_NO_QUERY_SYNTAX,

        // Understand AQS (from:chris)
        SEARCH_ADVANCED_QUERY_SYNTAX,

        // Understand NQS (mail from chris) in addition to AQS.
        // NOTE: This is not enough to allow a semantic canvas.  For
        // that I think people either have to host our query control
        // or go to SemThing directly.
        SEARCH_NATURAL_QUERY_SYNTAX,
    } SEARCH_QUERY_SYNTAX;


    //
    // Language of query for user words
    //
    [propput]
    HRESULT QueryContentLocale([in] LCID lcid);

    [propget]
    HRESULT QueryContentLocale([out, retval] LCID *plcid);

    //
    // Language of sem thing for AQS
    //
    [propput]
    HRESULT QueryKeywordLocale([in] LCID lcid);

    [propget]
    HRESULT QueryKeywordLocale([out, retval] LCID *plcid);

    //
    // How to expand search terms
    //
    [propput]
    HRESULT QueryTermExpansion([in] SEARCH_TERM_EXPANSION expandTerms);

    [propget]
    HRESULT QueryTermExpansion([out, retval] SEARCH_TERM_EXPANSION *pExpandTerms);

    //
    // Query syntax to allow
    //
    [propput]
    HRESULT QuerySyntax([in] SEARCH_QUERY_SYNTAX querySyntax);

    [propget]
    HRESULT QuerySyntax([out, retval] SEARCH_QUERY_SYNTAX *pQuerySyntax);

    //
    // NULL for using all properties
    // Otherwise comma delimited list of properties to search
    // when looking for content that is not explicit.
    // So if this was "Content, DocAuthor", then
    // "foo" --> Look for "foo" in Content, DocAuthor
    // "from:foo" --> Look for "foo" in From field.
    //
    [propput]
    HRESULT QueryContentProperties([in, string, unique] LPCWSTR pszContentProperties);

    [propget]
    HRESULT QueryContentProperties([out, string, retval] LPWSTR *ppszContentProperties);

    //
    // Comma delimted column names
    // Example: "System.ItemAuthors, System.Document.Title"
    //
    [propput]
    HRESULT QuerySelectColumns([in, string, unique] LPCWSTR pszSelectColumns);

    [propget]
    HRESULT QuerySelectColumns([out, string, retval] LPWSTR *ppszSelectColumns);

    //
    // Additional where clauses added to the
    // end, must start with and/or
    // Example: "and contains(*, 'foo')"
    //
    //
    [propput]
    HRESULT QueryWhereRestrictions([in, string, unique] LPCWSTR pszRestrictions);

    [propget]
    HRESULT QueryWhereRestrictions([out, string, retval] LPWSTR *ppszRestrictions);

    //
    // Sorting clause
    // Example: "System.ItemAuthors asc, System.ItemDate desc"
    //
    [propput]
    HRESULT QuerySorting([in, string, unique] LPCWSTR pszSorting);

    [propget]
    HRESULT QuerySorting([out, string, retval] LPWSTR *ppszSorting);

    //
    // Start a user query and immediately return the result
    //
    HRESULT GenerateSQLFromUserQuery([in, string] LPCWSTR pszQuery,
                                     [out, retval, string] LPWSTR *ppszSQL);

    typedef struct _SEARCH_COLUMN_PROPERTIES {
        PROPVARIANT     Value;
        LCID            lcid;
    } SEARCH_COLUMN_PROPERTIES;

    //
    // Write properites for a specific itemID
    //

    HRESULT WriteProperties([in] ITEMID itemID,
                            [in] DWORD dwNumberOfColumns,
                            [in, size_is(dwNumberOfColumns)] PROPERTYKEY *pColumns,
                            [in, size_is(dwNumberOfColumns)] SEARCH_COLUMN_PROPERTIES *pValues,
                            [in, unique] FILETIME *pftGatherModifiedTime);

    //
    // Any negative number for returning all results, otherwise the maximum number of results to return.
    //

    [propput]
    HRESULT QueryMaxResults([in] LONG cMaxResults);
    
    [propget]
    HRESULT QueryMaxResults([out, retval] LONG* pcMaxResults);
};