/******************************************************************************\
|*                                                                            *|
|*                          FingerCell Extractor 2.1                          *|
|*                                                                            *|
|* FncExtractor.h                                                             *|
|* Header file for FncExtractor module                                        *|
|*                                                                            *|
|* Copyright (C) 2006-2008 Neurotechnology                                    *|
|*                                                                            *|
\******************************************************************************/

#ifndef FNC_EXTRACTOR_H_INCLUDED
#define FNC_EXTRACTOR_H_INCLUDED

#include "NFRecord.h"
#include "NImages.h"
#include "FncExtractorParams.h"

#ifdef N_CPP
extern "C"
{
#endif

/**
 * \brief Handle to FncExtractor object. 
 */
N_DECLARE_HANDLE(HFncExtractor);

#ifndef N_NO_ANSI_FUNC
NResult N_API FnceGetInfoA(NLibraryInfoA * pValue);
#endif
#ifndef N_NO_UNICODE
NResult N_API FnceGetInfoW(NLibraryInfoW * pValue);
#endif
#define FnceGetInfo N_FUNC_AW(FnceGetInfo)

/**
 *\brief Checks if FncExtractor library is registered.
 * 
 * \return #NTrue if library is registered, #NFalse otherwise.
 * 
 * \sa FncExtractor Module 
 */
NBool N_API FnceIsRegistered(void);

/**
 * \brief Copies parameter values from one FncExtractor to another.
 * 
 * \param[in] hDstExtractor Handle to the destination FncExtractor object. 
 * \param[in] hSrcExtractor Handle to the source FncExtractor object. 
 * 
 * \return  If the function fails, the return value is one of the following
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hDstExtractor or hSrcExtractor is NULL. </td></tr>
 *          </table>
 * 
 * \sa FncExtractor Module | HFncExtractor 
 */
NResult N_API FnceCopyParameters(HFncExtractor hDstExtractor, HFncExtractor hSrcExtractor);

/**
 * \brief Creates a FncExtractor.
 * 
 * \param[out] pHExtractor Pointer to HFncExtractor that receives handle to created FncExtractor object. 
 * 
 * \return  If the function succeeds the return value is #N_OK. 
 * \return  If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p pHExtractor is #NULL. </td></tr>
 *            <tr><td>#N_E_OUT_OF_MEMORY</td>
 *                <td>There was not enough memory. </td></tr>
 *          </table>
 * 
 * \remark Created object must be deleted using #FnceFree function. 
 * 
 * \sa FncExtractor Module | HFncExtractor | FnceFree 
 */
NResult N_API FnceCreate(HFncExtractor * pHExtractor);

/**
 * \brief Deletes the FncExtractor. After the object is deleted the specified handle is no longer valid.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * 
 * \remark If hExtractor is #NULL, does nothing.
 * 
 * \sa FncExtractor Module | HFncExtractor 
 */
void N_API FnceFree(HFncExtractor hExtractor);

/**
 * \brief Sets default values for all parameters of the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * 
 * \return  If the function succeeds the return value is #N_OK. 
 * \return  If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor is #NULL. </td></tr>
 *          </table>
 * 
 * \sa FncExtractor Module | HFncExtractor 
 */
NResult N_API FnceReset(HFncExtractor hExtractor);

/**
 * \brief Retrieves maximal size of packed #NFRecord the specified FncExtractor can extract.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[out] pSize Pointer to #NSizeType that receives maximal template size.  
 * 
 * \return  If the function succeeds the return value is #N_OK. 
 * \return  If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor or pSize is #NULL. </td></tr>
 *          </table>
 * \sa FncExtractor Module | HFncExtractor 
 */
NResult N_API FnceGetMaxTemplateSize(HFncExtractor hExtractor, NSizeType * pSize);

/**
 * \brief Extracts a packed #NFRecord from the image using the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] width Specifies image width. 
 * \param[in] width Specifies image width. 
 * \param[in] width Specifies image width. 
 * \param[in] height Specifies image height. 
 * \param[in] stride Specifies length of the image row in bytes. 
 * \param[in] horzResolution Specifies horizontal resolution in pixels per inch of the image. 
 * \param[in] vertResolution Specifies vertical resolution in pixels per inch of the image. 
 * \param[in, out] pixels Pointer to memory block containing image pixels. 
 * \param[in] position Specifies finger position. 
 * \param[in] impressionType Specifies impression type. 
 * \param[out] buffer Pointer to memory buffer to store extracted packed #NFRecord. 
 * \param[in] bufferSize Size of memory buffer to store extracted packed #NFRecord. 
 * \param[out] pSize Pointer to #NSizeType that receives size of extracted packed #NFRecord.  
 * 
 * \return  If the function succeeds the return value is #N_OK. 
 * \return  If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> \p stride is less than \p width. or <br>
 *                      \p position is invalid or <br>
 *                      \p impressionType is invalid. or  <br>
 *                      \p bufferSize is less than needed to store extracted packed #NFRecord. </td></tr>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor, \p pixels, \p buffer or \p pSize is NULL. </td></tr>
 *             <tr><td>#N_E_ARGUMENT_OUT_OF_RANGE</td>
 *                <td>\p width or \p height is zero. or 
 *                    \p horzResolution or \p vertResolution is out of supported range </td></tr>
 *           </table>
 * 
 * \remark \p position and \p impressionType are written to extracted #NFRecord.
 * \remark Memory for  \p buffer must be allocated before calling the function. #FnceGetMaxTemplateSize function should be used to get the size needed for allocation. 
 * \remark If image is of low quality then \p buffer is not used and value received through \p pSize is zero.
 * 
\sa FncExtractor Module | HFncExtractor | FnceGetMaxTemplateSize | FnceExtractUnpacked | FnceExtractFromImage 
 */
NResult N_API FnceExtract(HFncExtractor hExtractor,
	NUShort width, NUShort height, NSizeType stride, NUShort horzResolution, NUShort vertResolution, NByte * pixels,
	NFPosition position, NFImpressionType impressionType,
	void * buffer, NSizeType bufferSize, NSizeType * pSize);

/**
 * \brief Extracts a packed #NFRecord from the #NImage using the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] hImage Handle to the image. 
 * \param[in] position Specifies finger position. 
 * \param[in] impressionType Specifies impression type. 
 * \param[out] buffer Pointer to memory buffer to store extracted packed NFRecord. 
 * \param[in] bufferSize Size of memory buffer to store extracted packed NFRecord. 
 * \param[out] pSize Pointer to NSizeType that receives size of extracted packed NFRecord. 
 * 
 * \return  If the function succeeds the return value is #N_OK. 
 * \return  If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> \p hImage is invalid. or <br>
 *                      \p position is invalid. or <br>
 *                      \p impressionType is invalid. or <br>
 *                      \p bufferSize is less than needed to store extracted packed #NFRecord.  </td></tr>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor, \p hImage, \p buffer or \p pSize is NULL. </td></tr>
 *             <tr><td>#N_E_INVALID_OPERATION</td>
 *                <td>Fast extraction is started </td></tr>
 *           </table>
 * 
 * \remark \p position and \p impressionType are written to extracted #NFRecord.
 * \remark Memory for \p buffer must be allocated before calling the function. #FnceGetMaxTemplateSize function should be used to get the size needed for allocation. 
 * \remark If image is of low quality then \p buffer is not used and value received through \p pSize is zero.
 * 
 * \sa FncExtractor Module | HFncExtractor | HNImage | FnceGetMaxTemplateSize | FnceExtract | FnceExtractUnpackedFromImage 
 */
NResult N_API FnceExtractFromImage(HFncExtractor hExtractor,
	HNImage hImage,
	NFPosition position, NFImpressionType impressionType,
	void * buffer, NSizeType bufferSize, NSizeType * pSize);

/**
 * \brief Extracts a #NFRecord from the image using the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] width Specifies image width. 
 * \param[in] height Specifies image height. 
 * \param[in] stride Specifies length of the image row in bytes. 
 * \param[in] horzResolution Specifies horizontal resolution in pixels per inch of the image. 
 * \param[in] vertResolution Specifies vertical resolution in pixels per inch of the image. 
 * \param[in, out] pixels Pointer to memory block containing image pixels. 
 * \param[in] position Specifies finger position. 
 * \param[in] impressionType Specifies impression type. 
 * \param[out] pHRecord Pointer to #HNFRecord that receives handle to created #NFRecord object containing extracted template.  
 * 
 * \return  If the function succeeds the return value is #N_OK. 
 * \return  If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> \p stride is less than width. or <br>
 *                      \p position is invalid. or <br>
 *                      \p impressionType is invalid.  </td></tr>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor, \p pixels or \p pHRecord is #NULL. </td></tr>
 *             <tr><td>#N_E_ARGUMENT_OUT_OF_RANGE</td>
 *                <td>\p width or \p height is zero. or 
 *                    \p horzResolution or \p vertResolution is out of supported range </td></tr>
  *             <tr><td>#N_E_INVALID_OPERATION</td>
 *                <td>Fast extraction is started </td></tr>
 *           </table>
 * 
 * \remark \p position and \p impressionType are written to extracted #NFRecord.
 * \remark If image is of low quality then handle received through pHRecord is NULL.
 * \sa FncExtractor Module | HFncExtractor | HNFRecord | FnceExtract | FnceExtractUnpackedFromImage 
 */
NResult N_API FnceExtractUnpacked(HFncExtractor hExtractor,
	NUShort width, NUShort height, NSizeType stride, NUShort horzResolution, NUShort vertResolution, NByte * pixels,
	NFPosition position, NFImpressionType impressionType, HNFRecord * pHRecord);

/**
 * \brief Extracts a #NFRecord from the #NImage using the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] hImage Handle to the image. 
 * \param[in] position Specifies finger position. 
 * \param[in] impressionType Specifies impression type. 
 * \param[out] pHRecord Pointer to #HNFRecord that receives handle to created #NFRecord object containing extracted template. 
 * 
 * \return If the function succeeds the return value is #N_OK. 
 * \return If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> \p hImage is invalid. or <br>
 *                      \p position is invalid. or <br>
 *                      \p impressionType is invalid </td></tr>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor, \p hImage or \p pHRecord is #NULL </td></tr>
  *             <tr><td>#N_E_INVALID_OPERATION</td>
 *                <td>Fast extraction is started </td></tr>
 *           </table>
 * 
 * \remark \p position and \p impressionType are written to extracted #NFRecord.
 * \remark If image is of low quality then handle received through \p pHRecord is #NULL.
 * 
 * \sa FncExtractor Module | HFncExtractor | HNImage | HNFRecord | FnceExtractFromImage | FnceExtractUnpacked 
 */
NResult N_API FnceExtractUnpackedFromImage(HFncExtractor hExtractor, HNImage hImage,
	NFPosition position, NFImpressionType impressionType, HNFRecord * pHRecord);

/**
 * \brief Starts fast extraction by extracting a packed #NFRecord from a part of the image using the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] width Specifies image width. 
 * \param[in] height Specifies image height. 
 * \param[in] stride Specifies length of the image row in bytes. 
 * \param[in] horzResolution Specifies horizontal resolution in pixels per inch of the image. 
 * \param[in] vertResolution Specifies vertical resolution in pixels per inch of the image. 
 * \param[in, out] pixels Pointer to memory block containing image pixels. 
 * \param[in] position Specifies finger position. 
 * \param[in] impressionType Specifies impression type. 
 * \param[out] buffer Pointer to memory buffer to store extracted packed #NFRecord. 
 * \param[in] bufferSize Size of memory buffer to store extracted packed #NFRecord. 
 * \param[out] pSize Pointer to #NSizeType that receives size of extracted packed #NFRecord. 
 * 
 * \return If the function succeeds the return value is #N_OK. 
 * \return If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> \p stride is less than width. or <br>
 *                     \p position is invalid. or <br>
 *                     \p impressionType is invalid or <br>
 *                     \p bufferSize is less than needed to store extracted packed #NFRecord
 *                </td>
 *            </tr>
 *            <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor, \p pixels, \p buffer or \p pSize is NULL.
 *                </td>
 *            </tr>
 *            <tr><td>#N_E_ARGUMENT_OUT_OF_RANGE</td>
 *                <td>\p width or \p height is zero or \p horzResolution or \p vertResolution is out of supported range. 
 *                </td>
 *            </tr>
 *            <tr><td>#N_E_INVALID_OPERATION</td>
 *                <td>Fast extraction is started.
 *                </td>
 *            </tr>
 *           </table>
 * 
 * \remark \p position and \p impressionType are written to extracted #NFRecord.
 * \remark Memory for \p buffer must be allocated before calling the function. #FnceGetMaxTemplateSize function should be used to learn the size needed for allocation. 
 * \remark If image is of low quality then buffer is not used and value received through \p pSize is zero.
 * \remark Fast extraction must be either end with #FnceFastExtractEnd function or finished with for example #FnceFastExtractFinish function. 
 * 
 * \sa FncExtractor Module | HFncExtractor | FnceGetMaxTemplateSize | FnceFastExtractStartUnpacked | FnceFastExtractStartFromImage | FnceFastExtractFinish | FnceFastExtractEnd 
*/
NResult N_API FnceFastExtractStart(HFncExtractor hExtractor,
	NUShort width, NUShort height, NSizeType stride, NUShort horzResolution, NUShort vertResolution, NByte * pixels,
	NFPosition position, NFImpressionType impressionType,
	void * buffer, NSizeType bufferSize, NSizeType * pSize);

/**
 * \brief Starts fast extraction by extracting a #NFRecord from a part of the image using the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] width Specifies image width. 
 * \param[in] height Specifies image height. 
 * \param[in] stride Specifies length of the image row in bytes. 
 * \param[in] horzResolution Specifies horizontal resolution in pixels per inch of the image. 
 * \param[in] vertResolution Specifies vertical resolution in pixels per inch of the image. 
 * \param[in, out] pixels Pointer to memory block containing image pixels. 
 * \param[in] position Specifies finger position. 
 * \param[in] impressionType Specifies impression type. 
 * \param[out] pHRecord Pointer to #HNFRecord that receives handle to created #NFRecord object containing extracted template. 
 * 
 * \return If the function succeeds the return value is #N_OK. 
 * \return If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> \p stride is less than width. or <br>
 *                     \p position is invalid. or <br>
 *                     \p impressionType is invalid or <br>
 *                </td>
 *            </tr>
 *            <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor, \p pixels or \p pHRecord is #NULL.
 *                </td>
 *            </tr>
 *            <tr><td>#N_E_ARGUMENT_OUT_OF_RANGE</td>
 *                <td>\p width or \p height is zero or \p horzResolution or \p vertResolution is out of supported range. 
 *                </td>
 *            </tr>
 *            <tr><td>#N_E_INVALID_OPERATION</td>
 *                <td>Fast extraction is started.
 *                </td>
 *            </tr>
 *           </table>
 * 
 * \remark \p position and \p impressionType are written to extracted #NFRecord.
 * \remark If image is of low quality then handle received through pHRecord is #NULL.
 * \remark Fast extraction must be either end with #FnceFastExtractEnd function or finished with for example #FnceFastExtractFinishUnpacked function. 
 * 
 * \sa FncExtractor Module | HFncExtractor | FnceGetMaxTemplateSize | FnceFastExtractStartUnpacked | FnceFastExtractStartFromImage | FnceFastExtractFinish | FnceFastExtractEnd 
 * 
*/
NResult N_API FnceFastExtractStartUnpacked(HFncExtractor hExtractor,
	NUShort width, NUShort height, NSizeType stride, NUShort horzResolution, NUShort vertResolution, NByte * pixels,
	NFPosition position, NFImpressionType impressionType, HNFRecord * pHRecord);

/**
 * \brief Starts fast extraction by extracting a packed #NFRecord from a part of the #NImage using the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] hImage Handle to the image. 
 * \param[in] position Specifies finger position. 
 * \param[in] impressionType Specifies impression type. 
 * \param[out] buffer Pointer to memory buffer to store extracted packed #NFRecord.
 * \param[in] bufferSize Size of memory buffer to store extracted packed #NFRecord.
 * \param[out] pSize Pointer to #NSizeType that receives size of extracted packed #NFRecord.  
 * 
 * \return If the function succeeds the return value is #N_OK. 
 * \return If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> \p hImage is invalid. or <br>
 *                     \p position is invalid. or <br>
 *                     \p bufferSize is less than needed to store extracted packed #NFRecord. or <br>
 *                     \p impressionType is invalid </td></tr>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor, \p hImage, \p buffer or \p pSize is  #NULL </td></tr>
 *              <tr><td>#N_E_INVALID_OPERATION</td>
 *                  <td>Fast extraction is started.</td></tr>
 *           </table>
 * 
 * \remark \p position and \p impressionType are written to extracted #NFRecord.
 * \remark Memory for \p buffer must be allocated before calling the function. #FnceGetMaxTemplateSize function should be used to learn the size needed for allocation. 
 * \remark If image is of low quality then handle received through pHRecord is #NULL.
 * \remark Fast extraction must be either end with #FnceFastExtractEnd function or finished with for example #FnceFastExtractFinishWithImage function. 
 * 
 * \sa FncExtractor Module | HFncExtractor | HNImage | FnceGetMaxTemplateSize | FnceFastExtractStartUnpackedFromImage | FnceFastExtractStart | FnceFastExtractFinishWithImage | FnceFastExtractEnd 
 */
NResult N_API FnceFastExtractStartFromImage(HFncExtractor hExtractor, HNImage hImage,
	NFPosition position, NFImpressionType impressionType, void * buffer, NSizeType bufferSize, NSizeType * pSize);

/**
 * \brief Starts fast extraction by extracting a #NFRecord from a part of the #NImage using the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object.
 * \param[in] hImage Handle to the image. 
 * \param[in] position Specifies finger position. 
 * \param[in] impressionType Specifies impression type. 
 * \param[out] pHRecord Pointer to #HNFRecord that receives handle to created #NFRecord object containing extracted template. 
 * 
 * \return If the function succeeds the return value is #N_OK. 
 * \return If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> \p hImage is invalid. or <br>
 *                      \p position is invalid. or <br>
 *                      \p impressionType is invalid </td></tr>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor, \p hImage, or \p pHRecord is  #NULL </td></tr>
 *              <tr><td>#N_E_INVALID_OPERATION</td>
 *                  <td>Fast extraction is started.</td></tr>
 *           </table>
 * 
 * \remark \p position and \p impressionType are written to extracted #NFRecord.
 * \remark If image is of low quality then handle received through pHRecord is #NULL.
 * \remark Fast extraction must be either end with #FnceFastExtractEnd function or finished with for example #FnceFastExtractFinishWithImage function. 
 * 
 * \sa FncExtractor Module | HFncExtractor | HNImage | HNFRecord | FnceFastExtractStartFromImage | FnceFastExtractStartUnpacked | FnceFastExtractFinishUnpackedWithImage | FnceFastExtractEnd 
 */
NResult N_API FnceFastExtractStartUnpackedFromImage(HFncExtractor hExtractor, HNImage hImage,
	NFPosition position, NFImpressionType impressionType, HNFRecord * pHRecord);

/**
 * \brief Finishes fast extraction by extracting a packed #NFRecord from the whole image used during start of fast extraction using the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] width Specifies image width. 
 * \param[in] height Specifies image height. 
 * \param[in] stride Specifies length of the image row in bytes. 
 * \param[in] horzResolution Specifies horizontal resolution in pixels per inch of the image. 
 * \param[in] vertResolution Specifies vertical resolution in pixels per inch of the image. 
 * \param[in, out] pixels Pointer to memory block containing image pixels. 
 * \param[out] buffer Pointer to memory buffer to store extracted packed #NFRecord. 
 * \param[in] bufferSize Size of memory buffer to store extracted packed #NFRecord. 
 * \param[out] pSize Pointer to #NSizeType that receives size of extracted packed #NFRecord. 
 * 
 * \return If the function succeeds the return value is #N_OK. 
 * \return If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> \p stride is less than width. or <br>
 *                      \p bufferSize is less than needed to store extracted packed #NFRecord. or <br>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor, pixels, buffer or pSize is #NULL </td></tr>
 *             <tr><td>#N_E_ARGUMENT_OUT_OF_RANGE</td>
 *                <td>\p width or height is zero, -or- horzResolution or vertResolution is out of range </td></tr>
 *              <tr><td>#N_E_INVALID_OPERATION</td>
 *                  <td>Fast extraction is started.</td></tr>
 *           </table>
 * 
 * \remark Memory for \p buffer must be allocated before calling the function. #FnceGetMaxTemplateSize function should be used to learn the size needed for allocation. 
 * \remark If image is of low quality then \p buffer is not used and value received through \p pSize is zero.
 * 
 * \sa FncExtractor Module | HFncExtractor | FnceGetMaxTemplateSize | FnceFastExtractFinishUnpacked | FnceFastExtractFinishWithImage | FnceFastExtractStart | FnceFastExtractEnd 
 */
NResult N_API FnceFastExtractFinish(HFncExtractor hExtractor,
	NUShort width, NUShort height, NSizeType stride, NUShort horzResolution, NUShort vertResolution, NByte * pixels,
	void * buffer, NSizeType bufferSize, NSizeType * pSize);

/**
 * \brief Finishes fast extraction by extracting a #NFRecord from the whole image used during start of fast extraction using the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] width Specifies image width. 
 * \param[in] height Specifies image height. 
 * \param[in] stride Specifies length of the image row in bytes. 
 * \param[in] horzResolution Specifies horizontal resolution in pixels per inch of the image. 
 * \param[in] vertResolution Specifies vertical resolution in pixels per inch of the image. 
 * \param[in, out] pixels Pointer to memory block containing image pixels. 
 * \param[out] pHRecord Pointer to #HNFRecord that receives handle to created #NFRecord object  
 * 
 * \return If the function succeeds the return value is #N_OK. 
 * \return If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> \p stride is less than width.
                  </td>
 *             </tr>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor, pixels, or pHRecord is  #NULL </td></tr>
 *             <tr><td>#N_E_ARGUMENT_OUT_OF_RANGE</td>
 *                <td>\p width or height is zero, -or- horzResolution or vertResolution is out of range </td></tr>
 *              <tr><td>#N_E_INVALID_OPERATION</td>
 *                  <td>Fast extraction is started.</td></tr>
 *           </table>
 * 
 * \remark If image is of low quality then handle received through pHRecord is #NULL.
 * 
 * \sa FncExtractor Module | HFncExtractor | HNFRecord | FnceFastExtractFinish | FnceFastExtractFinishUnpackedWithImage | FnceFastExtractStartUnpacked | FnceFastExtractEnd 
 */
NResult N_API FnceFastExtractFinishUnpacked(HFncExtractor hExtractor,
	NUShort width, NUShort height, NSizeType stride, NUShort horzResolution, NUShort vertResolution, NByte * pixels,
	HNFRecord * pHRecord);

/**
 * \brief Finishes fast extraction by extracting a packed #NFRecord from the whole #NImage used during start of fast extraction using the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] hImage Handle to the image. 
 * \param[out] buffer Pointer to memory buffer to store extracted packed #NFRecord.
 * \param[in] bufferSize Size of memory buffer to store extracted packed #NFRecord.
 * \param[out] pSize Pointer to #NSizeType that receives size of extracted packed #NFRecord.  
 * 
 * \return If the function succeeds the return value is #N_OK. 
 * \return If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> \p hImage is invalid </td></tr>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor, \p hImage, \p buffer or \p pSize is  #NULL </td></tr>
 *              <tr><td>#N_E_INVALID_OPERATION</td>
 *                  <td>Fast extraction is not started.</td></tr>
 *           </table>
 * 
 * \remark Memory for \p buffer must be allocated before calling the function. #FnceGetMaxTemplateSize function should be used to learn the size needed for allocation. 
 * \remark If image is of low quality then handle received through \p pHRecord is #NULL.
 * 
 * \sa FncExtractor Module | HFncExtractor | HNImage | FnceGetMaxTemplateSize | FnceFastExtractFinishUnpackedWithImage | FnceFastExtractFinish | FnceFastExtractStartFromImage | FnceFastExtractEnd 
 */
NResult N_API FnceFastExtractFinishWithImage(HFncExtractor hExtractor, HNImage hImage, void * buffer, NSizeType bufferSize, NSizeType * pSize);

/**
 * \brief Finishes fast extraction by extracting a #NFRecord from the whole #NImage used during start of fast extraction using the specified FncExtractor.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] hImage Handle to the image. 
 * \param[out] pHRecord Pointer to #HNFRecord that receives handle to created #NFRecord object containing extracted template.  
 * 
 * \return If the function succeeds the return value is #N_OK. 
 * \return If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> \p hImage is invalid.
 *                      </td></tr>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor or \p pHRecord is  #NULL </td></tr>
 *              <tr><td>#N_E_INVALID_OPERATION</td>
 *                  <td>Fast extraction is not started.</td></tr>
 *           </table>
 * 
 * \remark If image is of low quality then handle received through \p pHRecord is #NULL.
 * 
 * 
 * \sa FncExtractor Module | HFncExtractor | HNImage | HNFRecord | FnceFastExtractFinishWithImage | FnceFastExtractFinishUnpacked | FnceFastExtractStartUnpackedFromImage | FnceFastExtractEnd 
 */
NResult N_API FnceFastExtractFinishUnpackedWithImage(HFncExtractor hExtractor, HNImage hImage, HNFRecord * pHRecord);

/**
 * \brief Ends fast extraction.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * 
 * \return If the function succeeds the return value is #N_OK. 
 * \return If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hExtractor, hImage, or pHRecord is #NULL </td></tr>
 *              <tr><td>#N_E_INVALID_OPERATION</td>
 *                  <td>Fast extraction is not started.</td></tr>
 *           </table>
 * 
 * \sa FncExtractor Module | HFncExtractor | FnceFastExtractStartFromImage | FnceFastExtractStartUnpackedFromImage | FnceFastExtractFinishWithImage | FnceFastExtractFinishUnpackedWithImage 
 */
NResult N_API FnceFastExtractEnd(HFncExtractor hExtractor);

/**
 * \brief Generalizes \p count features collections to single features collection.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] templateCount The templates count. 
 * \param[in] arTemplates Pointer to void * that receives pointer to memory block containing templates array. 
 * \param[in] arTemplateSizes Pointer to array of #NSizeType that contains sizes of each template. 
 * \param[out] pHRecord Pointer to #HNFRecord that receives handle to created #NFRecord object containing generalized template.  
 * \param[out] pBaseTemplateIndex Index of main generalization template. 
 * 
 * \return If failed to generalize templates, function returns #NULL through pHRecord .
 * \return If the function succeeds the return value is #N_OK. 
 * \return If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> One of arTemplates templated is #NULL. </td></tr>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td> \p hExtractor, \p arTemplates, \p arTemplateSizes, \p pHRecord, or \p pBaseTemplateIndex is #NULL.</td></tr>
  *             <tr><td>#N_E_ARGUMENT_OUT_OF_RANGE</td>
 *                <td>\p templateCount is less or greater than NFG_MIN_TEMPLATES. </td></tr>
  *            <tr><td>#N_E_OUT_OF_MEMORY</td>
 *                <td>There was not enough memory. </td></tr>
 *           </table>
 * 
 * \remark If templates can not be generalized then value received through \p pHRecord is #NULL and value received through \p pBaseTemplateIndex is -1. 
 * 
 * \sa FncExtractor Module | HFncExtractor | HNFRecord | FnceExtract | FnceGeneralize 
 */
NResult N_API FnceGeneralizeUnpacked(HFncExtractor hExtractor, NInt templateCount, const void * * arTemplates, const NSizeType * arTemplateSizes,
	HNFRecord * pHRecord, NInt * pBaseTemplateIndex);

/**
 * \brief Generalizes \p count features collections to single features collection.
 * 
 * \param[in] hExtractor Handle to the FncExtractor object. 
 * \param[in] templateCount The templates count. 
 * \param[in] arTemplates Pointer to void * that receives pointer to memory block containing templates array. 
 * \param[in] arTemplateSizes Pointer to array of #NSizeType that contains sizes of each template. 
 * \param[out] buffer Pointer to memory buffer to store generalized template. 
 * \param[in] bufferSize Size of memory buffer to store generalized template. 
 * \param[out] pSize Pointer to #NSizeType that receives size of template. 
 * \param[out] pBaseTemplateIndex Index of main generalization template. 
 * 
 * \return If failed to generalize templates, function returns #NULL through pHRecord .
 * \return If the function succeeds the return value is #N_OK. 
 * \return If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td> One of arTemplates templated is #NULL. </td></tr>
 *             <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td> \p hExtractor, \p arTemplates, \p arTemplateSizes, \p buffer, \p pSize, or \p pBaseTemplateIndex is #NULL.</td></tr>
 *             <tr><td>#N_E_ARGUMENT_OUT_OF_RANGE</td>
 *                <td>\p templateCount is less or greater than NFG_MIN_TEMPLATES. </td></tr>
  *            <tr><td>#N_E_OUT_OF_MEMORY</td>
 *                <td>There was not enough memory. </td></tr>
 *           </table>
 * 
 * \remark If templates can not be generalized then \p buffer is not used, value received through \p pSize is zero and value received through \p pBaseTemplateIndex is -1. 
 * 
 * \sa FncExtractor Module | HFncExtractor | HNFRecord | FnceExtract | FnceGeneralizeUnpacked 
 */
NResult N_API FnceGeneralize(HFncExtractor hExtractor, NInt templateCount, const void * * arTemplates, const NSizeType * arTemplateSizes,
	void * buffer, NSizeType bufferSize, NSizeType * pSize, NInt * pBaseTemplateIndex);

#ifdef N_DOCUMENTATION
/**
 * \brief  Retrieves value of the parameter.
 * \param[in]  hExtractor   Handle to the extractor object.
 * \param[in]  parameterId  Identifier of the parameter to retrieve.
 * \param[out] pValue       Pointer to a variable that receives parameter
 *                          value.
 * \return  If the function succeeds and \p parameterId specifies
 *          #N_TYPE_STRING type parameter and \p pValue is #NULL, the return
 *          value is length of the string (not including NULL-terminator)
 *          \p pValue should point to.
 * \return  If the function succeeds and \p pValue is not #NULL, the return
 *          value is #N_OK.
 * \return  If the function fails, the return value is one of the following
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td rowspan="2">#N_E_ARGUMENT_NULL</td>
 *                <td>\p parameterId specifies a non-static parameter and
 *                \p hExtractor is #NULL</td></tr>
 *            <tr><td>\p parameterId specifies a non-#N_TYPE_STRING type
 *                parameter and \p pValue is #NULL.</td></tr>
 *            <tr><td>#N_E_PARAMETER</td>
 *                <td>\p parameterId is invalid.</td></tr>
 *          </table>
 * \remark  The following values can be used for \p parameterId:
 *          - #FNCEP_COPYRIGHT
 *          - #FNCEP_GENERALIZATION_THRESHOLD
 *          - #FNCEP_GENERALIZATION_MAXIMAL_ROTATION
 *          - #FNCEP_MODE
 *          - #FNCEP_NAME
 *          - #FNCEP_TEMPLATE_SIZE
 *          - #FNCEP_RETURNED_IMAGE
 *          - #FNCEP_VERSION_HIGH
 *          - #FNCEP_VERSION_LOW
 *          To learn the type of parameter pass a value obtained with
 *          #NParameterMakeId macro using #N_PC_TYPE_ID code, the parameter
 *          identifier via \p parameterId and pointer to #NInt that will
 *          receive one of the N_TYPE_XXX via \p pValue parameter.
 *          \p hExtractor can be #NULL in this case.
 * \sa  HFncExtractor | FnceSetParameter
 *
 * Retrieves value of the specified parameter of the specified extractor
 * object.
 */
NResult N_API FnceGetParameter(HFncExtractor hExtractor, NUInt parameterId, void * pValue);

#else

#ifndef N_NO_ANSI_FUNC
NResult N_API FnceGetParameterA(HFncExtractor hExtractor, NUInt parameterId, void * pValue);
#endif
#ifndef N_NO_UNICODE
NResult N_API FnceGetParameterW(HFncExtractor hExtractor, NUInt parameterId, void * pValue);
#endif
#define FnceGetParameter N_FUNC_AW(FnceGetParameter)

#endif

#ifdef N_DOCUMENTATION
/**
 * \brief  Sets value of the parameter.
 * \param[in]  hExtractor   Handle to the extractor object. Can be #NULL if
 *                          setting static parameter value.
 * \param[in]  parameterId  Identifier of the parameter to set.
 * \param[in]  pValue       Pointer to the parameter value to set.
 * \return  If the function succeeds the return value is #N_OK.
 * \return  If the function fails, the return value is one of the following
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT_NULL</td><td>\p pValue is #NULL.</td></tr>
 *            <tr><td>#N_E_ARGUMENT_OUT_OF_RANGE</td>
 *                <td>\p pValue points to a value that is out of range.</td>
 *                </tr>
 *            <tr><td>#N_E_PARAMETER</td>
 *                <td>\p parameterId is invalid.</td></tr>
 *            <tr><td>#N_E_PARAMETER_READ_ONLY</td>
 *                <td>\p parameterId specifies a read-only parameter.</td></tr>
 *          </table>
 * \remark  The following values can be used for \p parameterId:
 *          - #FNCEP_COPYRIGHT
 *          - #FNCEP_GENERALIZATION_THRESHOLD
 *          - #FNCEP_GENERALIZATION_MAXIMAL_ROTATION
 *          - #FNCEP_MODE
 *          - #FNCEP_NAME
 *          - #FNCEP_TEMPLATE_SIZE
 *          - #FNCEP_RETURNED_IMAGE
 *          - #FNCEP_VERSION_HIGH
 *          - #FNCEP_VERSION_LOW
 * \sa  HFncExtractor | FnceGetParameter
 *
 * Sets value of the specified parameter of the specified extractor object.
 */
NResult N_API FnceSetParameter(HFncExtractor hExtractor, NUInt parameterId, const void * pValue);

#else

#ifndef N_NO_ANSI_FUNC
NResult N_API FnceSetParameterA(HFncExtractor hExtractor, NUInt parameterId, const void * pValue);
#endif
#ifndef N_NO_UNICODE
NResult N_API FnceSetParameterW(HFncExtractor hExtractor, NUInt parameterId, const void * pValue);
#endif
#define FnceSetParameter N_FUNC_AW(FnceSetParameter)

#endif

#ifdef N_CPP
}
#endif

#endif // !FNC_EXTRACTOR_H_INCLUDED
