/**@@!ignore
|******************************************************************************|
|*                                                                            *|
|*                        Neurotechnology Template 1.4                        *|
|*                                                                            *|
|* NERecord.h                                                                 *|
|* Header file for NERecord module                                            *|
|*                                                                            *|
|* Copyright (C) 2005-2008 Neurotechnology                                    *|
|*                                                                            *|
\******************************************************************************/

#ifndef NE_RECORD_H_INCLUDED
#define NE_RECORD_H_INCLUDED

#include <NCore.h>

#ifdef N_CPP
extern "C"
{
#endif

/**@@!ignore
 * \brief Specifies the eye position
 */
typedef enum NEPosition_
{
	nepUnknown = 0,  /**@@!ignore< Unknown eye */
	nepRight = 1,    /**@@!ignore< Right eye */
	nepLeft = 2,     /**@@!ignore< Left eye */
} NEPosition;

/**@@!ignore Handle to iris record object. */
N_DECLARE_HANDLE(HNERecord)

/**@@!ignore
 * \brief  Gets maximum possible iris record size in bytes.
 * \param[in]  featuresSize  Size of features data in bytes.
 * \param[out] pSize         Returns number of bytes in largest possible
 *                           template of iris features (including header).
 * \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 pSize is #NULL.</td></tr>
 *          </table>
 * \remarks  For internal use only.
 *
 * Gets maximum possible iris record size in bytes.
 */
NResult N_API NERecordGetMaxSize(NSizeType featuresSize, NSizeType *pSize);

/**@@!ignore
 * \brief  Checks whether serialized iris record is valid.
 * \param[in]  buffer      Pointer to a buffer with serialized iris record.
 * \param[in]  bufferSize  Size of buffer in bytes.
 * \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 buffer is #NULL.</td></tr>
 *            <tr><td>#N_E_OUT_OF_MEMORY</td>
 *                <td>Not enough memory to create iris record.</td></tr>
 *            <tr><td>#N_E_END_OF_STREAM</td>
 *                <td>Iris record is truncated.</td></tr>
 *            <tr><td>#N_E_FORMAT</td>
 *                <td>Iris record is not valid.</td></tr>
 *          </table>
 *
 * Checks whether serialized iris record is valid.
 */
NResult N_API NERecordCheck(const void *buffer, NSizeType bufferSize);

/**@@!ignore
 * \brief  Iris record info.
 * \remarks  For internal use only.
 */
typedef struct NERecordInfo_
{
	NByte MajorVersion; /**@@!ignore< Major version */
	NByte MinorVersion; /**@@!ignore< Minor version */
	NUInt Size;         /**@@!ignore Size */
	NByte HeaderSize;   /**@@!ignore< Header size */
} NERecordInfo;

/**@@!ignore
 * \brief  Disposes iris record info.
 * \param[in]  pInfo  Pointer to a iris record info structure.
 * \remarks  For internal use only.
 *
 * Disposes memory internally taken by iris record info structure.
 */
void N_API NERecordInfoDispose(NERecordInfo *pInfo);

/**@@!ignore
 * \brief  Creates empty iris record object.
 * \param[in]  width     Specifies width of iris image.
 * \param[in]  height    Specifies height of iris image.
 * \param[in]  flags     Flags that control iris record object type and
 *                       purpose.
 * \param[out] pHRecord  Pointer to #HNERecord that receives handle to the
 *                       created iris record 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 pHRecord is #NULL.</td></tr>
 *            <tr><td>#N_E_OUT_OF_MEMORY</td>
 *                <td>Not enough memory to create iris record.</td></tr>
 *          </table>
 * \remarks  For internal use only.
 * \sa HNERecord | NERecordCreateFromMemory | NERecordLoadFromMemory
 *
 * Creates iris record object and sets all parameters to default values.
 */
NResult N_API NERecordCreate(NUShort width, NUShort height,
	NUInt flags, HNERecord *pHRecord);

/**@@!ignore
 * \brief  Creates iris record object from the memory buffer.
 * \param[in]  buffer      Pointer to the memory buffer containing serialized
 *                         iris record.
 * \param[in]  bufferSize  Size of the memory buffer.
 * \param[in]  flags       Flags that control iris record object type and
 *                         purpose.
 * \param[in]  pInfo       Pointer to #NERecordInfo structer that is filled
 *                         from created iris record object.
 * \param[out] pHRecord    Pointer to #HNERecord that receives handle to the
 *                         created iris record 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 buffer or \p pHRecord is #NULL.</td></tr>
 *            <tr><td>#N_E_OUT_OF_MEMORY</td>
 *                <td>Not enough memory to create iris record.</td></tr>
 *            <tr><td>#N_E_END_OF_STREAM</td>
 *                <td>Iris record is truncated.</td></tr>
 *            <tr><td>#N_E_FORMAT</td>
 *                <td>Iris record is not valid.</td></tr>
 *          </table>
 * \sa HNERecord | NERecordCreate | NERecordLoadFromMemory
 *
 * Creates iris record object from memory buffer.
 */
NResult N_API NERecordCreateFromMemory(const void *buffer, NSizeType bufferSize,
	NUInt flags, NERecordInfo *pInfo, HNERecord *pHRecord);

/**@@!ignore
 * \brief  Deletes iris record object.
 * \param[in]  hRecord  Handle to the iris record.
 * \sa HNERecord
 *
 * Deletes iris record object. After the object is deleted the specified handle
 * is no longer valid.
 */
void N_API NERecordFree(HNERecord hRecord);

/**@@!ignore
 * \brief  Clones iris record object.
 * \param[in]  hRecord         Handle to the iris record.
 * \param[out] pHClonedRecord  Pointer to #HNERecord that receives handle to
 *                             the cloned iris record 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 hRecord or \p pHClonedRecord is #NULL.</td></tr>
 *            <tr><td>#N_E_OUT_OF_MEMORY</td>
 *                <td>Not enough memory to create iris record.</td></tr>
 *          </table>
 * \sa HNERecord | NERecordCreate
 *
 * Clones the created iris record object to a new instance.
 */
NResult N_API NERecordClone(HNERecord hRecord, HNERecord *pHClonedRecord);
/**@@!ignore
 * \brief  Gets size of serialized iris record in bytes.
 * \param[in]  hRecord  Handle to the iris record.
 * \param[in]  flags    Flags that control iris record object type and purpose.
 * \param[out] pSize    Pointer to #NSizeType that receives value of serialized
 *                      iris record size in bytes.
 * \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 pSize is #NULL.</td></tr>
 *          </table>
 * \sa HNERecord | NERecordSaveToMemory
 *
 * Gets size of serialized iris record in bytes.
 */
NResult N_API NERecordGetSize(HNERecord hRecord, NUInt flags, NSizeType *pSize);
/**@@!ignore
 * \brief  Serializes NERecord into the specified memory buffer.
 * \param[in]  hRecord     Handle to the iris record.
 * \param[in]  buffer      Pointer to the memory buffer.
 * \param[in]  bufferSize  Size of memory buffer in bytes.
 * \param[in]  flags       Flags that control iris record saving.
 * \param[out] pSize       Pointer to #NSizeType that receives value of
 *                         serialized iris record size in bytes.
 * \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 hRecord, \p buffer or \p pSize is #NULL.</td></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td>Buffer is too small for the serialized iris record.</td>
 *                </tr>
 *            <tr><td>#N_E_FAILED</td>
 *                <td>The memory cannot be written correctly.</td></tr>
 *          </table>
 * \sa HNERecord
 *
 * Serializes iris record to the memory buffer.
 */
NResult N_API NERecordSaveToMemory(HNERecord hRecord,
	void *buffer, NSizeType bufferSize, NUInt flags, NSizeType *pSize);

/**@@!ignore
 * \brief  Retrieves the image width of the packed #NERecord.
 * \param[in]  buffer      Pointer to memory buffer that contains packed
 *                         #NERecord.
 * \param[in]  bufferSize  Size of memory buffer that contains packed
 *                         #NERecord.
 * \param[out] pValue      Pointer to #NUShort that receives width of iris
 *                         image.
 * \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 buffer or \p pValue is #NULL.</td></tr>
 *            <tr><td>#N_E_END_OF_STREAM</td>
 *                <td>\p bufferSize is less than expected.</td></tr>
 *            <tr><td>#N_E_FORMAT</td>
 *                <td>Data in memory buffer \p buffer points to is
 *                    inconsistent with #NERecord format.</td></tr>
 *          </table>
 * \sa HNERecord
 */
NResult N_API NERecordGetWidthMem(const void *buffer, NSizeType bufferSize, NUShort *pValue);

/**@@!ignore
 * \brief  Retrieves the image height of the packed #NERecord.
 * \param[in]  buffer      Pointer to memory buffer that contains packed
 *                         #NERecord.
 * \param[in]  bufferSize  Size of memory buffer that contains packed
 *                         #NERecord.
 * \param[out] pValue      Pointer to #NUShort that receives height of iris
 *                         image.
 * \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 buffer or \p pValue is #NULL.</td></tr>
 *            <tr><td>#N_E_END_OF_STREAM</td>
 *                <td>\p bufferSize is less than expected.</td></tr>
 *            <tr><td>#N_E_FORMAT</td>
 *                <td>Data in memory buffer \p buffer points to is
 *                    inconsistent with #NERecord format.</td></tr>
 *          </table>
 * \sa HNERecord
 */
NResult N_API NERecordGetHeightMem(const void *buffer, NSizeType bufferSize, NUShort *pValue);

/**@@!ignore
 * \brief  Retrieves the eye position of the packed #NERecord.
 * \param[in]  buffer      Pointer to memory buffer that contains packed
 *                         #NERecord.
 * \param[in]  bufferSize  Size of memory buffer that contains packed
 *                         #NERecord.
 * \param[out] pValue      Pointer to #NEPosition that receives position of
 *                         eye.
 * \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 buffer or \p pValue is #NULL.</td></tr>
 *            <tr><td>#N_E_END_OF_STREAM</td>
 *                <td>\p bufferSize is less than expected.</td></tr>
 *            <tr><td>#N_E_FORMAT</td>
 *                <td>Data in memory buffer \p buffer points to is
 *                    inconsistent with #NERecord format.</td></tr>
 *          </table>
 * \sa HNERecord
 */
NResult N_API NERecordGetPositionMem(const void *buffer, NSizeType bufferSize, NEPosition *pValue);

/**@@!ignore
 * \brief  Retrieves the quality of the packed #NERecord.
 * \param[in]  buffer      Pointer to memory buffer that contains packed
 *                         #NERecord.
 * \param[in]  bufferSize  Size of memory buffer that contains packed
 *                         #NERecord.
 * \param[out] pValue      Pointer to #NByte that receives iris quality.
 * \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 buffer or \p pValue is #NULL.</td></tr>
 *            <tr><td>#N_E_END_OF_STREAM</td>
 *                <td>\p bufferSize is less than expected.</td></tr>
 *            <tr><td>#N_E_FORMAT</td>
 *                <td>Data in memory buffer \p buffer points to is
 *                    inconsistent with #NERecord format.</td></tr>
 *          </table>
 * \sa HNERecord
 */
NResult N_API NERecordGetQualityMem(const void *buffer, NSizeType bufferSize, NByte *pValue);

/**@@!ignore
 * \brief  Retrieves the image width of the #NERecord.
 * 
 * \param[in]  hRecord  Handle to the #NERecord object.
 * \param[out] pValue   Pointer to #NUShort that receives image width.
 * \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 buffer or \p pValue is #NULL.</td></tr>
 *          </table>
 * \sa HNERecord
 */
NResult N_API NERecordGetWidth(HNERecord hRecord, NUShort *pValue);

/**@@!ignore
 * \brief  Retrieves the image height of the #NERecord.
 * 
 * \param[in]  hRecord  Handle to the #NERecord object.
 * \param[out] pValue   Pointer to #NUShort that receives image height.
 * \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 buffer or \p pValue is #NULL.</td></tr>
 *          </table>
 * \sa HNERecord
 */
NResult N_API NERecordGetHeight(HNERecord hRecord, NUShort *pValue);

/**@@!ignore
 * \brief  Retrieves the eye position of the #NERecord.
 * 
 * \param[in]  hRecord  Handle to the #NERecord object.
 * \param[out] pValue   Pointer to #NEPosition that receives eye position.
 * \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 buffer or \p pValue is #NULL.</td></tr>
 *          </table>
 * \sa HNERecord | NERecordSetPositions
 */
NResult N_API NERecordGetPosition(HNERecord hRecord, NEPosition *pValue);

/**@@!ignore
 * \brief  Sets the eye position of the #NERecord.
 * 
 * \param[in]  hRecord  Handle to the #NERecord object.
 * \param[in]  value    New eye position value.
 * 
 * \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 value is invalid.</td></tr>
 *            <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hRecord is #NULL.</td></tr>
 *          </table>
 * 
 * \sa HNERecord | NERecordGetPositions
 */
NResult N_API NERecordSetPosition(HNERecord hRecord, NEPosition value);

/**@@!ignore
 * \brief  Retrieves the quality of the #NERecord.
 * 
 * \param[in]  hRecord  Handle to the #NERecord object.
 * \param[out] pValue   Pointer to #NByte that receives iris quality.
 * \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 buffer or \p pValue is #NULL.</td></tr>
 *          </table>
 * \sa HNERecord | NERecordSetQuality
 */
NResult N_API NERecordGetQuality(HNERecord hRecord, NByte *pValue);

/**@@!ignore
 * \brief  Sets the quality of the #NERecord.
 * 
 * \param[in]  hRecord  Handle to the #NERecord object.
 * \param[in]  value    New iris quality value.
 * 
 * \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 value is invalid.</td></tr>
 *            <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p hRecord is #NULL.</td></tr>
 *          </table>
 * 
 * \sa HNERecord | NERecordGetQuality
 */
NResult N_API NERecordSetQuality(HNERecord hRecord, NByte value);

#ifdef N_CPP
}
#endif

#endif /**@@!ignore !NE_RECORD_H_INCLUDED */
