/****************************************************************************************
 *
 *	Name:		BioAPI_iPAQ3.h
 *	version:	version 1.0
 *	language:	ANSI C
 *	compiler:	Microsoft Visual C++ 6.0
 *  Date:		4-26-2002
 *
 *
 *	This header file describes functions exported by BioAPI_iPAQ3 library.
 *	BioAPI_Init --- initializes the BioAPI
 *	BioAPI_Terminate --- terminates the use of BioAPI
 *	BioAPI_Capture --- captures samples
 *	BioAPI_VerifyMatch --- performs a verification (1-to-1)
 *	BioAPI_IdentifyMatch --- performs an identification (1-to-many)
 *	BioAPI_Enroll --- captures sample and enroll it
 *	BioAPI_Verify --- captures a sample and compares it against the stored template
 *	BioAPI_Identify --- captures a sample and compares it against the population
 *	BioAPI_GetBIRFromHandle --- retrieves the BIR associated with a BIR handle
 *
 *
 *	Copyright 2002 Cogent Systems, Inc.
 ****************************************************************************************/


#ifdef WIN32
#define BioAPI	__stdcall
#else
#define BioAPI
#endif

//#define UINT8 unsigned char

typedef struct bioapi_version {
	UINT32	Major;
	UINT32	Minor;
} BioAPI_VERSION, *BioAPI_VERSION_PTR;

typedef UINT8 BioAPI_BIR_VERSION, *BioAPI_BIR_VERSION_PTR;

typedef UINT8 BioAPI_BIR_DATA_TYPE;
#define BioAPI_BIR_DATA_TYPE_RAW			(0x01)
#define BioAPI_BIR_DATA_TYPE_INTERMEDIATE	(0x02)
#define BioAPI_BIR_DATA_TYPE_PROCESSED		(0x04)
#define BioAPI_BIR_DATA_TYPE_ENCRYPTED		(0x10)
#define BioAPI_BIR_DATA_TYPE_SIGNED			(0x20)

typedef struct bioapi_bir_biometric_data_format {
	UINT16	FormatOwner;
	UINT16	FormatID;
} BioAPI_BIR_BIOMETRIC_DATA_FORMAT, *BioAPI_BIR_BIOMETRIC_DATA_FORMAT_PTR;

typedef INT8 BioAPI_QUALITY;

typedef UINT8 BioAPI_BIR_PURPOSE;
#define BioAPI_PURPOSE_VERIFY							(1)
#define BioAPI_PURPOSE_IDENTIFY							(2)
#define BioAPI_PURPOSE_ENROLL							(3)
#define BioAPI_PURPOSE_ENROLL_FOR_VERIFICATION_ONLY		(4)
#define BioAPI_PURPOSE_ENROLL_FOR_IDENTIFICATIOIN_ONLY	(5)
#define BioAPI_PURPOSE_AUDIT							(6)

typedef UINT32 BioAPI_BIR_AUTH_FACTORS;
#define BioAPI_FACTOR_MULTIPLE			(0x00000001)
#define BioAPI_FACTOR_FACIAL_FEATURES	(0x00000002)
#define BioAPI_FACTOR_VOICE				(0x00000004)
#define BioAPI_FACTOR_FINGERPRINT		(0x00000008)
#define BioAPI_FACTOR_IRIS				(0x00000010)
#define BioAPI_FACTOR_RETINA			(0x00000020)
#define BioAPI_FACTOR_HAND_GEOMETRY		(0x00000040)
#define BioAPI_FACTOR_SIGNATURE_DYNAMICS (0x00000080)
#define BioAPI_FACTOR_KEYSTOKE_DYNAMICS	(0x00000100)
#define BioAPI_FACTOR_LIP_MOVEMENT		(0x00000200)
#define BioAPI_FACTOR_THERMAL_FACE_IMAGE (0x00000400)
#define BioAPI_FACTOR_THERMAL_HAND_IMAGE (0x00000800)
#define BioAPI_FACTOR_GAIT				(0x00001000)
#define BioAPI_FACTOR_PASSWORD			(0x80000000)


typedef struct bioapi_bir_header {
	UINT32					Length;	/*length of Header+Opaque data */
	BioAPI_BIR_VERSION		HeaderVersion;
	BioAPI_BIR_DATA_TYPE	Type;
	BioAPI_BIR_BIOMETRIC_DATA_FORMAT	Format;
	BioAPI_QUALITY						Quality;
	BioAPI_BIR_PURPOSE					Purpose;
	BioAPI_BIR_AUTH_FACTORS				FactorsMask;
} BioAPI_BIR_HEADER, *BioAPI_BIR_HEADER_PTR;


typedef UINT8 BioAPI_BIR_BIOMETRIC_DATA, *BioAPI_BIR_BIOMETRIC_DATA_PTR;


typedef struct bioapi_data {
	UINT32	Lenght;	/*lenght of the data buffer in bytes */
	UINT8	*Data;	/*points to the start of an arbitrary length data buffer */
} BioAPI_DATA, *BioAPI_DATA_PTR;


typedef struct bioapi_bir {
	BioAPI_BIR_HEADER				Header;
	BioAPI_BIR_BIOMETRIC_DATA_PTR	BiometricData;	/*length indicated in header */
	BioAPI_DATA_PTR					Signature;		/*NULL if no signature */
} BioAPI_BIR, *BioAPI_BIR_PTR;


//typedef sint32 BioAPI_BIR_HANDLE, *BioAPI_BIR_HANDLE_PTR;
typedef INT32 BioAPI_BIR_HANDLE, *BioAPI_BIR_HANDLE_PTR;
#define BioAPI_INVALID_BIR_HANDLE		(-1)
#define BioAPI_UNSUPPORTED_BIR_HANDLE	(-2)

typedef UINT32 BioAPI_HANDLE, *BioAPI_HANDLE_PTR;

typedef UINT32 BioAPI_BOOL;
#define BioAPI_FALSE	(0)
#define BioAPI_TRUE		(!BioAPI_FALSE)

//typedef sint32 BioAPI_FAR, *BioAPI_FAR_PTR;
typedef INT32 BioAPI_FAR, *BioAPI_FAR_PTR;
#define BioAPI_NOT_SET	(-1)

//typedef sint32 BioAPI_FRR, *BioAPI_FRR_PTR;
typedef INT32 BioAPI_FRR, *BioAPI_FRR_PTR;
#define BioAPI_NOT_SET			(-1)
#define BioAPI_NOT_SUPPORTED	(-2)

typedef UINT8 BioAPI_INPUT_BIR_FORM;
#define BioAPI_DATABASE_ID_INPUT	(1)
#define BioAPI_BIR_HANDLE_INPUT		(2)
#define BioAPI_FULLBIR_INPUT		(3)

//typedef sint32 BioAPI_BIR_HANDLE, *BioAPI_BIR_HANDLE_PTR;
typedef INT32 BioAPI_BIR_HANDLE, *BioAPI_BIR_HANDLE_PTR;
#define BioAPI_INVALID_BIR_HANDLE		(-1)
#define BioAPI_UNSUPPORTED_BIR_HANDLE	(-2)

//typedef sint32 BioAPI_DB_HANDLE, *BioAPI_DB_HANDLE_PTR;
typedef INT32 BioAPI_DB_HANDLE, *BioAPI_DB_HANDLE_PTR;
#define BioAPI_DB_INVALID_HANDLE	(-1)

typedef UINT8 BioAPI_UUID[16], *BioAPI_UUID_PTR;
//typedef BioAPI_UUID, *BioAPI_UUID_PTR;

typedef struct bioapi_dbbir_id {
	BioAPI_DB_HANDLE	DbHandle;
	BioAPI_UUID			KeyValue;
} BioAPI_DBBIR_ID, *BioAPI_DBBIR_ID_PTR;


typedef struct bioapi_input_bir {
	BioAPI_INPUT_BIR_FORM		Form;
	union {
		BioAPI_DBBIR_ID_PTR		BIRinDb;
		BioAPI_BIR_HANDLE_PTR	BIRinBSP;
		BioAPI_BIR_PTR			BIR;
	} inputBIR;
} BioAPI_INPUT_BIR, *BioAPI_INPUT_BIR_PTR;


typedef UINT8 BioAPI_IDENTIFY_POPULATION_TYPE;
#define BioAPI_DB_TYPE		(1)
#define BioAPI_ARRAY_TYPE	(2)

typedef struct bioapi_bir_array_population {
	UINT32			NumberOfMembers;
	BioAPI_BIR_PTR	*Members;	/* a pointer to an array of BIR pointers */
} BioAPI_BIR_ARRAY_POPULATION, *BioAPI_BIR_ARRAY_POPULATION_PTR;

typedef struct bioapi_identify_population {
	BioAPI_IDENTIFY_POPULATION_TYPE		Type;
	union {
		BioAPI_DB_HANDLE_PTR				BIRDataBase;
		BioAPI_BIR_ARRAY_POPULATION_PTR		BIRArray;
	} BIRs;
} BioAPI_IDENTIFY_POPULATION, *BioAPI_IDENTIFY_POPULATION_PTR;


typedef struct bioapi_candidate {
	BioAPI_IDENTIFY_POPULATION_TYPE		Type;
	union {
		BioAPI_UUID_PTR		BIRInDataBase;
		UINT32				*BIRInArray;
	} BIR;
	BioAPI_FAR	FARAchieved;
	BioAPI_FRR	FRRAchieved;
} BioAPI_CANDIDATE, *BioAPI_CANDIDATE_PTR;


typedef BioAPI_CANDIDATE_PTR BioAPI_CANDIDATE_ARRAY, *BioAPI_CANDIDATE_ARRAY_PTR;





/********************** export functions ***************************/
#define BioAPI_RETURN	int

/* return code */
#define BioAPI_OK		0x0000000

#define BioAPI_ERRCODE_INTERNAL_ERROR		0x00000001

#define CogentSensorLibraryLoadError		0x00000800
#define CogentGeneralFailure				0x00000801
#define CogentVerificationFailure			0x00002800
#define CogentIdentificationFailure			0x00002801

#define	BioAPI_BSP_FUNCTION_NOT_SUPPORTED	0x0000200C
#define	BioAPIERR_BSP_INCONSISTENT_PURPOSE	0x0000200D
#define	BioAPIERR_BSP_PURPOSE_NOT_SUPPORTED	0x0000200F

#define BioAPIERR_BSP_UNABLE_TO_CAPTURE		0x00002001
#define	BioAPIERR_BSP_TOO_MANY_HANDLES		0x00002002
#define	BioAPIERR_BSP_TIMEOUT_EXPIRED		0x00002003

#define	BioAPIERR_BSP_BIR_SIGNATURE_FAILURE	0x00002005
#define	BioAPIERR_BSP_RECORD_NOT_FOUND		0x00002105

#define	BioAPI_BSP_NO_INPUT_BIRS			0x00002008

/*
 * This function initializes the BioAPI and can be used for reference counting. Application
 * should call this function to initialize the system. Proper application will initialize and
 * terminate the connection to BioAPI API layer to allow for correct reclamation of system
 * resources.
 * 
 * Parameters:
 *	Version --- [in] the major and minor version number of the BioAPI release the application
 *					is compatible with. The current BioAPI release version 1.1.
 *	Reserved1 --- [in] set to 0
 *	Reserved2 --- [in] set to NULL
 *	Reserved3 --- [in] set to 0
 *	Reserved4 --- [in] set to NULL
 *
 * Return:
 *	BioAPI_OK --- success
 */
BioAPI_RETURN BioAPI BioAPI_Init (
	const BioAPI_VERSION	*Version,
	UINT32					Reserved1,
	const void				*Reserved2,
	UINT32					Reserved3,
	const void				*Reserved4);



/*
 * This function terminates the caller's use of BioAPI and is used for reference counting. 
 * Proper applications will call this function for each call made to BioAPI_Init(). This will
 * allow for the proper cleanup of internal structures and free any held system resources.
 *
 * Parameters: None
 * Return:
 *	BioAPI_OK --- success
 */
BioAPI_RETURN BioAPI BioAPI_Terminate();


/*
 * This function captures samples for the purpose specified, and returns a BIR. The purpose
 * is recorded in the header of the CapturedBIR. The function returns handles to whatever data
 * is collected, and all local operation can be completed through use of the handles. If the
 * application needs to acquire the data either to store it in a database or to send it to a 
 * server, the application can retrieve the data with the BioAPI_GetBIRFromHandle function.
 * 
 * Parameters:
 *	Reserved --- [in] set to NULL
 *	Purpose --- [in] a value indicating the purpose of the biometric data capture.
 *	CapturedBIR --- [out] a handle to a BIR containing captured data. This data can be used
 *					directly by VerifyMatch or IdentifyMatch, depending on the purpose.
 *	OriginalBIR --- [out] original image data. This data can be used display purpose.
 *	Timeout --- [in] an integer specifying the timeout value (in milliseconds) for the operation.
 *					If this timeout is reached, the function returns an error, and no results. This
 *					value can be any positive number. A -1 value means the default timeout value
 *					will be used.
 *
 * Return:
 *	BioAPI_OK --- success
 *	BioAPIERR_BSP_UNABLE_TO_CAPTURE
 *	BioAPIERR_BSP_TOO_MANY_HANDLES
 *	BioAPIERR_BSP_TIMEOUT_EXPIRED
 *	BioAPIERR_BSP_PURPOSE_NOT_SUPPORTED
 *	BioAPI_ERRCODE_INTERNAL_ERROR --- internal memory allocate error
 *	CogentGeneralFailure --- process failed
 *
 * Note: Image quality saved in header structure is defined as:
 *	IMAGE_QUALITY_POOR = 0,
 *	IMAGE_QUALITY_ACCEPT = 1,
 *	IMAGE_QUALITY_GOOD = 2
 */
BioAPI_RETURN BioAPI BioAPI_Capture (
	UINT32					Reserved,
	BioAPI_BIR_PURPOSE		Purpose,
	BioAPI_BIR_PTR			CapturedBIR,
	BioAPI_BIR_PTR			OriginalBIR,
	INT32					Timeout);


/*
 * This function performs verification (1-to-1) match between two BIRs; the ProcessedBIR and the
 * StoredTemplate. The ProcessedBIR is the processed BIR constructed specifically for this 
 * verification. The StoredTemplate was created at enrollment. The application must request a 
 * maximum FAR value for a successful match, and may also request a maximum FRR for a successful
 * match. If a maximum FRR value is provided, the application must also indicate via the 
 * FARPrecedence parameter, which one takes precedence. The Boolean result indicates whether 
 * verification was successful or not, and the FARAchieved is a FAR value indicating how closely
 * the BIRs actually matched. The implementation may optionally return the corresponding FRR that
 * was achieved through the FRRAchieved return parameter. If the StoredTemplate contains a Payload,
 * the Payload will be returned upon successful verification.
 *
 * Parameters:
 *	Reserved1 --- [in] set to 0
 *	MaxFARRequested --- [in] the requested FAR criterion for successful verification
 *	MaxFRRRequested --- [in](optioinal) the requested FRR criterion for successful verification. 
 *							A NULL pointer indicates that this criterion is not provided.
 *	FARPrecedence --- [in] if both criteria are provided, this parameter indicates which takes
 *						precedence. BioAPI_TRUE for FAR, BioAPI_FALSE for FRR.
 *	ProcessedBIR --- [in] the BIR to be verified, or its handle
 *	StoredTemplate --- [in] the BIR to be verified against, or its key in a database, or its handle
 *	Reserved2 --- [in] set to NULL
 *	Result --- [out] a pointer to a Boolean value indicating (BioAPI_TRUE/BioAPI_FALSE) whether
 *				the BIRs matched or not according to the specified criteria.
 *
 * Return:
 *	BioAPI_OK --- success
 *	BioAPIERR_BSP_BIR_SIGNATURE_FAILURE
 *	BioAPIERR_BSP_INCONSISTENT_PURPOSE
 *	BioAPIERR_BSP_RECORD_NOT_FOUND
 */
BioAPI_RETURN BioAPI BioAPI_VerifyMatch (
	UINT32					Reserved1,
	const BioAPI_FAR		*MaxFARRequested,
	const BioAPI_FRR		*MaxFRRRequested,
	const BioAPI_BOOL		*FARPrecedence,
	const BioAPI_BIR_PTR	ProcessedBIR,
	const BioAPI_BIR_PTR	StoredTemplate,
	INT32					*Reserved2,
	BioAPI_BOOL				*Result);
 

/*
 * This function perform an identification (1-to-many) match between a ProcessedBIR and a set of stored
 * BIRs. The ProcessedBIR is the captured specifically for this identification. The population that
 * the match takes place against can be presented in one of three ways:
 *	1. in a database identified by an open database handle
 *	2. input in an array of BIRs
 *	3. in the "default" database of the BSP (possiblly stored in the biometric device)
 * The application must request a maximum FAR value criterion for a successful match, and may also(optional)
 * request a maximum FRR criterion for a successful match. If a maximum FRR value is provided, the application
 * must also indicate via the FARPrecedence parameter, which criterion takes prcedence. The FARAchieved
 * and, optionally, the FRRAchieved are returned for each result in the Candidate array.
 *
 * Parameters:
 *	Reserved1 --- [in] set to NULL
 *	MaxFARRequested --- [in] the requested FAR criterion for successful verification
 *	MaxFRRRequested --- [in](optioinal) the requested FRR criterion for successful verification. 
 *							A NULL pointer indicates that this criterion is not provided.
 *	FARPrecedence --- [in] if both criteria are provided, this parameter indicates which takes
 *						precedence. BioAPI_TRUE for FAR, BioAPI_FALSE for FRR.
 *	ProcessedBIR --- [in] the BIR to be verified, or its handle
 *	Population --- [in] The population of templates against which the identify match is performed.
 *	MaxNumberOfResults --- [in] specifies tha maximum number of match candidates to be returned as a
 *							result of the 1:N match. A value of zero is a request for all candidates.
 *	NumberOfResults --- [out] specifies the number of candidates returned in the Candidates array as
 *						a result of the 1:N match.
 *	Candidates --- [out] a pointer to an array of BioAPI_CANDIDATE_PTRs corresponding to the BIRs
 *					identified as a result of the match process (i.e., indicess associated with BIRs
 *					found to exceed the match threshold).This list is in rank order, with the highest
 *					scoring record being first. If no matches are found, this pointer will be set to
 *					NULL. If the Population was presented in a database, the IDs are database IDs; if
 *					the set was presented in an in-memory array, the IDs are indexes into the array.
 *	Timeout --- [in] an integer specifying the timeout value (in milliseconds) for the operation.
 *					If this timeout is reached, the function returns an error, and no results. This
 *					value can be any positive number. A -1 value means the default timeout value
 *					will be used.
 *
 * Return:
 *	BioAPI_OK --- success
 *	BioAPI_BSP_BIR_SIGNATURE_FAILURE
 *	BioAPI_BSP_TIMEOUT_EXPIRED
 *	BioAPI_BSP_NO_INPUT_BIRS
 *	BioAPI_BSP_FUNCTIOIN_NOT_SUPPORTED
 *	BioAPI_BSP_INCONSISTENT_PURPOSE
 *	BioAPI_BSP_RECORD_NOT_FOUND
 */	
BioAPI_RETURN BioAPI BioAPI_IdentifyMatch (
	UINT32								Reserved1,
	const BioAPI_FAR					*MaxFARRequested,
	const BioAPI_FRR					*MaxFRRRequested,
	const BioAPI_BOOL					*FARPrecedence,
	const BioAPI_BIR_PTR				ProcessedBIR,
	const BioAPI_BIR_ARRAY_POPULATION	*Population,
	UINT32								MaxNumberOfResults,
	UINT32								*NumberOfResults,
	BioAPI_CANDIDATE_ARRAY_PTR			Candidates,
	INT32								Timeout);




