/*
* 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_CPIXERROR_H
#define CPIX_CPIXERROR_H

#include <wchar.h>

#ifdef __cplusplus
extern "C" {
#endif



    /************************************************************************
     * Class cpix_Error and related types
     */
    enum cpix_ErrorType_
        {
            // Unknown exception
            ET_UNKNOWN_EXC         = 0x0000,

            // Standard C++ exceptions
            ET_STD_CPP_EXC         = 0x0100,
            ET_STD_BAD_ALLOC_EXC   = 0x0101,
            // TODO perhaps more std C++ exceptions are of interest?

            // 'Exceptions' that are generated by CPix API impl (CpixExc)
            ET_CPIX_EXC            = 0x0200,

            // LuceneError exception
            ET_CLUCENE_EXC         = 0x0400,

            // Exception(s) from Cpt (cpixtools) component
            ET_CPT_EXC             = 0x0800,
            ET_CPTSYNTAX_EXC       = 0x0801,

            // OS exceptions, if any
            ET_OS_EXC              = 0x1000
        };
    typedef enum cpix_ErrorType_ cpix_ErrorType;

    struct cpix_Error_
    {
        // the type of the error
        cpix_ErrorType   type_;

        // Detailed error message, may be NULL.
        const wchar_t *  msg_;

        // Implementation detail (pointer to derived C++ class instance)
        void          *  impl_;
    };
    typedef cpix_Error_ cpix_Error;

    /**
     * Generates a human readable error report based on the
     * error. Never fails (the report message may be truncated).
     *
     * @param thisError the error object for which to generate error.
     *        Unorthodoxly, it may be NULL, in which case empty string
     *        is generated.
     *
     * @param target the target buffer to render the report to. Must
     *        not be NULL.
     * 
     * @param targetLength the max amount of character to put in
     *        buffer, including the terminating zero. It must be
     *        greater than or equal to 1, obviously.
     */
    void cpix_Error_report(cpix_Error    * thisError,
                           wchar_t       * target,
                           size_t          targetLength);
    
    /**
     * Destroys this error instance.
     * @return always returns NULL
     */
    cpix_Error * cpix_Error_destroy(cpix_Error * thisError);

    /**
     * Tests if the last operation on cpixObj has failed.
     */
#define cpix_Failed(cpixObj)    ((cpixObj)->err_ != NULL)

    /**
     * Tests if the last operation on cpixObj has succeeded.
     */
#define cpix_Succeeded(cpixObj) ((cpixObj)->err_ == NULL)

    /**
     * Clears the error state of cpixObj.
     */
#define cpix_ClearError(cpixObj)  ((cpixObj)->err_ = cpix_Error_destroy((cpixObj)->err_))
    /*
     * Determines to what extent the cpix_hits_docs() is able to fetch available hits
     * Previously a check on cpix_Failed/Suceeded(hits) suffices, but with the batch_get_doc
     * implementation a request for N results may results in X fetches where (X <= N) To
     * correctly determine how many actual results are fetched a check on _err is not enough
     * and _ptr too have to cheked for NULL
     */
#define doc_Fetch_Succeeded(docObj) ((docObj)->ptr_ != NULL)
#define doc_Fetch_Failed(docObj)    ((docObj)->ptr_ == NULL)
    
    /**
     * Any "static" calls will give the result back via this
     * structure.
     */
    struct cpix_Result_
    {
        // Last error, if any, that resulted from executing a "static"
        // operation.
        // Use macros cpix_Failed, cpix_Succeeded and cpix_ClearError.
        // Do not attempt releasing it.
        cpix_Error * err_;
    };
    typedef cpix_Result_ cpix_Result;



#ifdef __cplusplus
} /* extern "C" */
#endif /* __cplusplus */



#endif /* CPIX_CPIXERROR_H */