/**
 * @file
 * @author VoXel Interaction Design <office@voxel.at>
 * @version     1.0.0
 *
 *
 * @section DESCRIPTION
 *
 * Sentis-ToF-m100 camera API
 *
 */

#ifndef _M100API_H
#define _M100API_H

#include <apitypes.h>

#if defined(MSVC)
 #define DLLExport __declspec( dllexport )
#else
 #define DLLExport /**/
#endif

#ifdef __cplusplus
extern "C" {
#endif

/**
 *  
 * @brief Open the UDP and TCP sockets for data and control interfaces.
 * 	Instance a thread which receives the UDP data and writes them to a queue.
 *
 * This function starts the communication with the camera, checks the data connection and
 * keeps it opened if the HOLD_CONTROL_ALIVE flag is set. It creates the udp data connection
 * and initializes a queue where the image frames are saved.
 *
 * To configure these connections and theirs behavior, the function receives the T_SENTIS_CONFIG
 * struct where the user should define the connection values.
 *
 * The user receives an handle T_SENTIS_HANDLE which allows to interact with the camera.
 *
 * The user should check if the connection is established by
 * checking the T_ERROR_CODE.
 * Also it is the responsability of the user to correctly close and delete the connection and the
 * data structures related by using the function STSclose.
 *
 *
 * @param [in] pa_tConf Configuration structure.
 * @param [out] pa_tErr 0 on success, a negative one byte error code otherwise
 *
 * @return Device handle
 *
 */
DLLExport T_SENTIS_HANDLE STSopen(T_SENTIS_CONFIG *pa_tConf, T_ERROR_CODE *pa_tErr);

/**
 * @brief Deletes the device handle and frees all allocated memory and close any TCP and UDP connections. 
 *
 * @param [in] pa_tHndl: Device handle.
 *
 * @return 0 if ok, negative error code otherwise.
 *
 */
DLLExport T_ERROR_CODE STSclose(T_SENTIS_HANDLE pa_tHndl);

/**
 *
 * @brief The function is used to read the image data of one frame. 
 *	
 *
 * The meta-information of the image is contained in pa_tHeader. On each call one frame should be provided.
 * The buffer contains the image data only depending on the selected image format. The buffer length must be 
 * indicated in the pa_nLength parameter and it should be big enough for the set image format in the camera 
 * register. If the length of the buffer is too small, the function will return an error and pa_nLength will 
 * contain the size needed for the image format set in the camera register.
 *
 * @note T_SENTIS_DATA_HEADER: The structure should contain all members of the 
 * 	frame header as described in the Sentis-ToF-M100 manual.
 *
 * @param [in] pa_tHndl Device handle.
 * @param [out] pa_pcBuffer Buffer to the image data.
 * @param [in,out] pa_nLength It should provide the size of pa_pcBuffer. 
 *	On return “pa_nLength” should contain the real size of the image data. 
 *	If not enough buffer space has been provided an error code should be reported.
 * @param [out] pa_tHeader Pointer to a image header structure.
 * @param [in] pa_nFlags Flags to control the behavior of the function. 
 * @param [in] pa_nTimeout No frame timeout [us] in case of blocking behavior.
 *	0 means default timeout (1000ms).
 * 
 * @return 0 if ok, negative error code otherwise.
 *
 */
DLLExport T_ERROR_CODE STSgetData(T_SENTIS_HANDLE pa_tHndl, T_SENTIS_DATA_HEADER *pa_tHeader, 
	char *pa_pcBuffer, int*pa_nLength, double pa_nFlags, int pa_nTimeout);
	
/**
 *
 * @brief Read the content of one register from the camera.
 *
 * @param [in] pa_tHndl Device handle.
 * @param [in] pa_usAddress 16 bits register address.
 * @param [out] pa_usData 16 bits register content buffer.
 * @param [in] pa_nFlags Read behavior. Blocking.
 * @param [in] pa_nTimeout Read timeout [us]. 0 means default timeout (1000ms).
 *
 * @result 0 if ok, negative error code otherwise.
 *
 */
DLLExport T_ERROR_CODE STSreadRegister(T_SENTIS_HANDLE pa_tHndl, unsigned short pa_usAddress, 
	unsigned short *pa_usData, int pa_nFlags, int pa_nTimeout);

/**
 *
 * @brief Write a value to one register of the camera.
 *
 * @note Any value could be written to the register. Please be sure you are
 * giving the right values to avoid unexpected behaviors
 *
 * @param [in] pa_tHndl Device handle.
 * @param [in] pa_usAddress 16 bits register address.
 * @param [out] pa_usData 16 bits register value to be written.
 *
 * @result 0 if ok, negative error code otherwise.
 *
 */
DLLExport T_ERROR_CODE STSwriteRegister(T_SENTIS_HANDLE pa_tHndl, unsigned short pa_usAddress, 
	unsigned short pa_usData);

#ifdef __cplusplus
}
#endif 


#endif 



