/*
* 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
            cpix_FREE_TEXT = 128
        };

    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 */
