copernicdesktopsearch(varargin)

function [Results,ResultsFields,similarWords] = copernicdesktopsearch(varargin)

% Function for submitting search queries to Copernic Desktop Search and
% retriving results, using COM interface.
% 
% author: Gianluca Dorini
% email:  [e-mail]
% 
%
% syntax: [Results,ResultsFields,similarWords] = copernicdesktopsearch(QueryText)
%
% The function copernicdesktopsearch submits the string QueryText containing the text of a query
% and returns N results that are objects (files, url, Outlook things,...) described by means of
% several parameters. The results are stored within two M-by-N cell matrices: Results,ResultsFields.
% Results{j,i} contains the j-th parameter value of the i-th search result; the name of the parameter
% is a string contained in ResultsFields{j,i}. Note that the number of parameters varys according to
% the specific search result, hence the number M of rows of Results,ResultsFields is the maximum number
% of parameters for a single search result obtained for a specific query. Search results with less than
% M parameters will obviously have some empty cell.
%
% similarWords is string with alternative query keys suggested by Copernic Desktop Search
%
% example: this commands returns all indexed items referring to 'iron maiden'.
% [Results,ResultsFields,similarWords] = copernicdesktopsearch('iron maiden');
%
% syntax: [Results,ResultsFields,similarWords] = copernicdesktopsearch(QueryText,Fields)
%
% The rearch result can be restricted to the list of M comma-separated fields specified
% within variable Fields. In this case the number of rows of Results is fixed, and of
% course ResultsFields is this case is a M-by-1 matrix, as there is no need to specify
% the name and the sequence of parameters is the same for search result.
%
% example: this commands returns all files referring to 'iron maiden' by means of filename,displaylocation,extension
% [Results,ResultsFields,similarWords] = copernicdesktopsearch('iron maiden' , 'filename,displaylocation,extension');
%
% There are quite a few types of field names, and some of the is listed below. Although there must be some method
% of Copernic Desktop Search COM interface that lists all possible field names, I sill haven't found it.
%
%
% Examples of field names:
% 'author'    'company'    'date'    'datereceived'    'datesent'   'displaylocation'
% 'displayname'   'extension'    'filename'    'flag'    'from'    'importance'
% 'isattachment'    'location'    'offline'    'receivedmail'    'size'    'subject'
% 'subsourceid'    'sys_contenttype'    'sys_indexedascontenttype'    'sys_indexeddata'
% 'sys_issubdocument'    'sys_sourceid'    'sys_subdocumentcontentformat'    'sys_topic'
% 'sys_uri'    'title'    'to'    'uid'

query_Result_buffer = 100;

if nargin == 1
    QueryText = varargin{1};
    Fields = '';
end
if nargin == 2
    QueryText = varargin{1};
    Fields = varargin{2};
end

Results = {};
ResultsFields = {};

%connect to copernic desktop search
cds = actxserver('CopernicDesktopSearch.DesktopSearch');

% execute a query
query = ExecuteQuery(cds,QueryText);

% check whether the quesry has been successfull
if get(query,'Valid') == 0
    Results = [];
    ResultsFields = [];
    similarWords = [];
    return
end

% GetSimilarWords
similarWords = GetSimilarWords(cds,QueryText);

% obtain the number of results
query_ResultCount = get(query,'ResultCount');

if isempty(query_ResultCount)
    Results = [];
    ResultsFields = [];
    return
end

Results = {};
ResultsFields = {};

if isempty(Fields)
    nofields = 1;
else
    nofields = 0;
end

first_index = 0;
k = 1;

while first_index < query_ResultCount


    if (first_index + query_Result_buffer) > query_ResultCount;
        query_Result_buffer = query_ResultCount - first_index;
    end
    % access results
    query_results = GetResults(query,int32(first_index),query_Result_buffer,Fields);

    % count selected results
    query_results_count = get(query_results,'Count');


    for i = 1:query_results_count
        % extract i-th result
        query_results_item = Item(query_results,i-1);

        % read the number of fields for the i-th result
        Item_CustomFieldCount = get(query_results_item,'CustomFieldCount');

        if Item_CustomFieldCount > 0
            for j = 1:Item_CustomFieldCount

                Results{j,k} = CustomFieldByIndex(query_results_item, j-1);

                if nofields
                    ResultsFields{j,k} = CustomFieldNameByIndex(query_results_item,j-1);
                else
                    if k==1
                        ResultsFields{j,1} = CustomFieldNameByIndex(query_results_item,j-1);
                    end
                end
            end
            k = k + 1;
        end
    end


    first_index = first_index + query_Result_buffer;


end