## CamelFolderSearch

CamelFolderSearch

## Synopsis

    struct              CamelFolderSearch;
    CamelFolderSearch * camel_folder_search_new             (void);
    void                camel_folder_search_construct       (CamelFolderSearch *search);
    void                camel_folder_search_set_folder      (CamelFolderSearch *search,
                                                             CamelFolder *folder);
    void                camel_folder_search_set_summary     (CamelFolderSearch *search,
                                                             GPtrArray *summary);
    void                camel_folder_search_set_body_index  (CamelFolderSearch *search,
                                                             CamelIndex *index);
    GPtrArray *         camel_folder_search_execute_expression
                                                            (CamelFolderSearch *search,
                                                             const char *expr,
                                                             CamelException *ex);
    GPtrArray *         camel_folder_search_search          (CamelFolderSearch *search,
                                                             const char *expr,
                                                             GPtrArray *uids,
                                                             CamelException *ex);
    guint32             camel_folder_search_count           (CamelFolderSearch *search,
                                                             const char *expr,
                                                             CamelException *ex);
    void                camel_folder_search_free_result     (CamelFolderSearch *search,
                                                             GPtrArray *);

## Description

## Details

### struct CamelFolderSearch

    struct CamelFolderSearch {
    	CamelObject parent;

    	struct _CamelFolderSearchPrivate *priv;

    	ESExp *sexp;		/* s-exp evaluator */
    	char *last_search; /* last searched expression */

    	/* these are only valid during the search, and are reset afterwards */
    	CamelFolder *folder; /* folder for current search */
    	GPtrArray *summary; /* summary array for current search */
    	GPtrArray *summary_set; /* subset of summary to actually include in search */
    	CamelMessageInfo *current; /* current message info, when searching one by one */
    	CamelMimeMessage *current_message; /* cache of current message, if required */
    	CamelIndex *body_index;
    };

### camel_folder_search_new ()

    CamelFolderSearch * camel_folder_search_new             (void);

Create a new CamelFolderSearch object.

A CamelFolderSearch is a subclassable, extensible s-exp evaluator which enforces a particular set of s-expressions. Particular methods may be overriden by an implementation to implement a search for any sort of backend.

Returns : | A new CamelFolderSearch widget.

### camel_folder_search_construct ()

    void                camel_folder_search_construct       (CamelFolderSearch *search);

`search` : |

### camel_folder_search_set_folder ()

    void                camel_folder_search_set_folder      (CamelFolderSearch *search,
                                                             CamelFolder *folder);

Set the folder attribute of the search. This is currently unused, but could be used to perform a slow-search when indexes and so forth are not available. Or for use by subclasses.

`search` : |
`folder` : | A folder.

### camel_folder_search_set_summary ()

    void                camel_folder_search_set_summary     (CamelFolderSearch *search,
                                                             GPtrArray *summary);

Set the array of summary objects representing the span of the search.

If this is not set, then a subclass must provide the functions for searching headers and for the match-all operator.

`search` : |
`summary` : | An array of CamelMessageInfo pointers.

### camel_folder_search_set_body_index ()

    void                camel_folder_search_set_body_index  (CamelFolderSearch *search,
                                                             CamelIndex *index);

Set the index representing the contents of all messages in this folder. If this is not set, then the folder implementation should sub-class the CamelFolderSearch and provide its own body-contains function.

`search` : |
`index` : |

### camel_folder_search_execute_expression ()

    GPtrArray *         camel_folder_search_execute_expression
                                                            (CamelFolderSearch *search,
                                                             const char *expr,
                                                             CamelException *ex);

Execute the search expression `expr`, returning an array of all matches as a GPtrArray of uid's of matching messages.

Note that any settings such as `set_body_index()`, `set_folder()`, and so on are reset to NULL once the search has completed.

TODO: The interface should probably return summary items instead (since they are much more useful to any client).

`search` : |
`expr` : |
`ex` : |
Returns : | A GPtrArray of strings of all matching messages. This must only be freed by camel_folder_search_free_result.

### camel_folder_search_search ()

    GPtrArray *         camel_folder_search_search          (CamelFolderSearch *search,
                                                             const char *expr,
                                                             GPtrArray *uids,
                                                             CamelException *ex);

Run a search. Search must have had Folder already set on it, and it must implement summaries.

`search` : |
`expr` : |
`uids` : | to search against, NULL for all uid's.
`ex` : |
Returns : |

### camel_folder_search_count ()

    guint32             camel_folder_search_count           (CamelFolderSearch *search,
                                                             const char *expr,
                                                             CamelException *ex);

Run a search. Search must have had Folder already set on it, and it must implement summaries.

`search` : |
`expr` : |
`ex` : |
Returns : | Number of messages that match the query.

### camel_folder_search_free_result ()

    void                camel_folder_search_free_result     (CamelFolderSearch *search,
                                                             GPtrArray *);

`search` : |
`Param2` : |