/*

* Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

#ifndef CPIX_CPIXDOC_H

#define CPIX_CPIXDOC_H

#include "cpixinit.h"

#include "cpixerror.h"

#include <math.h> // float_t

//#include "indevicecfg.h"

/**

 * Document related CPix API.

 *

 * See cpixsearch.h for further info and notes on CPix API.

 */

#ifdef __cplusplus

extern "C" {

#endif

    /************************************************************************

     * Class cpix_Field

     */

    /**

     * Storage related flags

     */

    enum cpix_Store_

        {

            // stores the field in the index

            cpix_STORE_YES = 1,

            // does not stores the field in the index

            cpix_STORE_NO  = 2

            // Not supported as yet

            // STORE_COMPRESS = 4

        };

    typedef enum cpix_Store_ cpix_Store;

    /**

     * Indexing action related flags

     */

    enum cpix_Index_

        {

            // do not index the field value - but it can still be

            // retrieved

            cpix_INDEX_NO = 16,

            // index the value of the field after an analyzer has

            // tokenized it

            cpix_INDEX_TOKENIZED = 32,

            // index the value of the field without an analyzer and

            // disable storing of norms

            cpix_INDEX_UNTOKENIZED = 64,

            // index the value of the field without the stop word analyzer and

            // store it in _aggregate

        };

    typedef enum cpix_Index_ cpix_Index;

    enum cpix_Aggregate_ 

    	{

            // NOTE: Aggregate flags are picked intentionally so that

            // 	     they won't conflict with CLucene.

            // Do not expose the value to be searchable through the

            // aggregate field

            cpix_AGGREGATE_NO = 1<<30,

            // Expose the value to be searchable throught the

            // aggregate field

            cpix_AGGREGATE_YES = 1<<31

    	};

    typedef enum cpix_Aggregate_ cpix_Aggregate;   

    struct cpix_Field_

    {

        // pointer to native (CLucene) impl

        void       * ptr_;

     //   bool		aggregate_;

        // Last error, if any, that resulted from executing the

        // last operation on this cpix_XXX object

        // Use macros cpix_Failed, cpix_Succeeded and cpix_ClearError.

        // Do not attempt releasing it.

        cpix_Error * err_;

    };

    typedef cpix_Field_ cpix_Field;

    /** 

     * Creates (initializes) a field - creates the native instance and

     * puts it into the wrapper provided. May fail - in which case

     * error is signalled on the field wrapper (use

     * cpix_Succeeded(..)).

     *

     * @param name the name of the field to create. Must not be NULL,

     * ownership not transferred.

     *

     * @param value the value of the field to create. Must not be NULL,

     * ownership not transferred.

     *

     * @param configs flags from cpix_Store, cpix_Index values.

     *

     * NOTE: An actual wrapper instance is not created by this

     * function, only the native instance it will wrap. This is

     * because the usecase of creating fields is that to add them to

     * Document, which transfers the ownership of the native instance

     * while not transferring the owernship of the wrapper. So, to

     * manage that situation comfortably, we do not force the creation

     * of the wrapper on the heap, only initialize it on the stack.

     */

    void cpix_Field_initialize(cpix_Field    * field,

                               const wchar_t * name,

                               const wchar_t * value,

                               int             configs);

    /**

     * Gets the name of this field. Never fails.

     *

     * @param thisField this field instance

     * @return the name of this field - ownership not transferred

     */

    const wchar_t * cpix_Field_name(cpix_Field * thisField);

    /**

     * Tells if this field has binary value. Never fails.

     *

     * @param thisFiels this field instance.

     * @return true if this field has binary value.

     */

    int cpix_Field_isBinary(cpix_Field * thisField);

    /**

     * Returns boost value for thisField

     * 

     * @param thisField this field instance.

     * @return boost value as a float_t.

     */

    float_t cpix_Field_boost(cpix_Field * thisField);

    /**

     * Set boost value for thisField

     * 

     * @param thisField this field instance to set boost for.

     * @param boost boost value as a float_t.

     */

    void cpix_Field_setBoost(cpix_Field * thisField,

                             float_t      boost);

    // TODO implement store, index, termvector related property

    // getters

    /**

     * Gets the string value of this field. Never fails.

     *

     * @param thisField this field instance

     * @return the string value of this field, if this field is not

     * binary, otherwise NULL. Ownership not transferred.

     */

    const wchar_t * cpix_Field_stringValue(cpix_Field * thisField);

    // TODO cpix_Field_streamValue() for getting content with a streamer

    /**

     * Releases the native instance wrapped by this wrapper but does

     * not free the wrapper.

     *

     * @param thisField this field (wrapper) to release

     */

    void cpix_Field_release(cpix_Field * thisField);

    /************************************************************************

     * Class cpix_DocFieldEnum to enumerate fields of a cpix_Document

     */

    struct cpix_DocFieldEnum_

    {

        // pointer to native (CLucene) impl

        void       * ptr_;

        // Last error, if any, that resulted from executing the

        // last operation on this cpix_XXX object

        // Use macros cpix_Failed, cpix_Succeeded and cpix_ClearError.

        // Do not attempt releasing it.

        cpix_Error * err_;

    };

    typedef cpix_DocFieldEnum_ cpix_DocFieldEnum;

    /**

     * Tells if there are more fields in this enumeration that were not

     * yet enumerated. Never fails.

     * @param thisDocFieldEnum this document-field enumeration instance

     *

     * @return true if there are yet un-enumerated fields, false (0)

     * otherwise

     */

    int cpix_DocFieldEnum_hasMore(cpix_DocFieldEnum * thisDocFieldEnum);

    /**

     * Gets the next field if this doc-field enum has more. Never fails.

     *

     * @param thisDocFieldEnum this doc-field enumeration

     *

     * @param target to put the field to. NOTE no new native instance

     * is created for the target, and therefore cpix_Field_destroy

     * must NOT be called on it. The instance 'target' is best to

     * have as a local variable (on the stack). See description of

     * lifetime management in the beginning of this header.

     */

    void cpix_DocFieldEnum_next(cpix_DocFieldEnum * thisDocFieldEnum,

                                cpix_Field        * target);

    /**

     * Destroys this document field enum instance. Never fails.

     *

     * @param thisDocFieldEnum this instance to destroy

     */

    void cpix_DocFieldEnum_destroy(cpix_DocFieldEnum * thisDocFieldEnum);

    struct cpix_Document_

    {

        // pointer to native (CPix) impl

        void       * ptr_;

        // Last error, if any, that resulted from executing the

        // last operation on this cpix_XXX object

        // Use macros cpix_Failed, cpix_Succeeded and cpix_ClearError.

        // Do not attempt releasing it.

        cpix_Error * err_;

    };

    typedef struct cpix_Document_ cpix_Document;

    /**

     * @param result any details on failure are communicated via this

     * struct - must not be NULL

     *

     * @param docUid document unique id - whatever string the document

     * can be identified with. Needed for deletion. It needs to be

     * unique only in the context of this index database. Mandatory

     * field. See enum LCPIX_DOCUID_FIELD. Stored and indexed

     * untokenized. If NULL is passed, exception is thrown.

     *

     * @param appClass the application class of the document. See

     * appclass-hierarchy.txt for more details. Optional field, can be

     * NULL, but recommended to define it. See enum

     * LCPIX_APPCLASS_FIELD. Stored and indexed tokenized. NOTE: this

     * value is supposed to be ASCII, so it is accepted as char*, but

     * the actual field is stored as wchar_t*, and that is how it is

     * returned on documents. If you want to be able to search

     * specific types in an index (like "root file media jpg" type

     * docs in the index "root file"), then you have to define this

     * field.

     *

     * @param excerpt a short textual extract of the document. It's up

     * to the client to figure out what short text can represent the

     * documents best when shown in search results. Optional

     * field. See enum LCPIX_EXCERPT_FIELD, as well as file parser

     * filter (LCPIX_FILEPARSER_FID). If defined: stored, not indexed.

     *

     * @param mimeType the mime type. Search clients can use it for

     * better displaying (like fetching corresponding icons, starting

     * viewing applications / components, etc...). Optional field, can

     * be NULL. See global variable LCPIX_MIMETYPE_FIELD. Stored if

     * specified, indexed untokenized.

     *

     * @return a newly created document instance. May fail, in which

     * case NULL is returned. Ownership transferred to caller.

     */

    cpix_Document * cpix_Document_create(cpix_Result   * result,

                                         const wchar_t * docUid,

                                         const char    * appClass,

                                         const wchar_t * excerpt,

                                         const wchar_t * mimeType);

    /**

     * Adds a field to this document.

     *

     * @param thisDocument this document to add a field to.

     *

     * @param field the field to add.

     *

     * NOTE!!! The ownership of the native field instance IS

     * transferred to this document. However, the ownership of the

     * wrapper (cpix_Field) is still at the caller. To work

     * comfortably with this situation, it has a cpix_Field_initialize()

     * function that initializes a wrapper instead of creating it - cf

     * above.

     */

    void cpix_Document_add(cpix_Document * thisDocument,

                           cpix_Field    * field);

    /**

     * Gets the value of a field in as a newly created string,

     * if the field exists in the document.

     *

     * @param thisDocument the document from which to get

     *        a field

     *

     * @param fieldName the name of the field, must not be NULL.

     *

     * @return the newly created string with the value of the

     *         field. If multiple fields exists with this name on the

     *         document, the first value is returned.  If only binary

     *         values exist or no value at all, NULL is returned. May

     *         fail. The value returned is owned by thisDocument,

     *         ownership is not transferred (do not delete it).

     */

    const wchar_t * 

    cpix_Document_getFieldValue(cpix_Document * thisDocument,

                                const wchar_t * fieldName);

    /**

     * Creates and returns with an enumeration of the fields.

     *

     * @param thisDocument this document of which the fields or are being

     * queried

     *

     * @return the newly created field enumeration. Ownership transferred

     * to the caller.

     */

    cpix_DocFieldEnum * cpix_Document_fields(cpix_Document * thisDocument);

    /**

     * Returns boost value for this Document

     * 

     * @param thisDocument this document instance.

     * @return boost value as a float_t.

     */

    float_t cpix_Document_boost(cpix_Document * thisDocument);

    /**

     * Set boost value for this Document.

     * 

     * @param thisDocument this document instance.

     * @param boost Boost value as a float_t.

     */

    void cpix_Document_setBoost(cpix_Document * thisDocument,

                                float_t         boost);

    /**

     * Empties out the document so that it can be reused. Always

     * succeeds. I.e. the document instance is not destroyed, only its

     * contents are emptied.

     *

     * @param thisDocument the document instance to clear

     */

    void cpix_Document_clear(cpix_Document * thisDocument);

    /**

     * Destroys this document instance. Never fails.

     *

     * @param thisDocument the document instance to destroy.

     */

    void cpix_Document_destroy(cpix_Document * thisDocument);

#ifdef __cplusplus

} /* extern "C" */

#endif /* __cplusplus */

#endif /* CPIX_CPIXDOC_H */