/*
 * This is an encapsulation of a National Instruments counter.
 *
 * It presents a simple 64-bit counter abstraction. When the counter is
 * created, it commences counting at zero until it is destroyed.
 *
 * The counter can be read and returns a 64-bit unsigned value.
 */
#ifndef _HCTR_H_
#define _HCTR_H_

#include <stdbool.h>

struct counter_private_t;
typedef struct counter_private_t* pHCTR;

/**
 * Create a 64-bit counter and start it counting
 *
 * \param device_name the name of the device (e.g. "dev1/ctr0")
 * \param ptr address of pointer to opaque private data structure
 *
 * \return
 *   0 OK
 *  !0 Error
 */
int hctr_ctor(const char* device_name, pHCTR* ptr);

/**
 * Read the value of the 64-bit counter
 *
 * \param hctr pointer to opaque private data structure
 * \param value address of unsigned 64-bit value to receive the output
 *
 * \return
 *   0 OK
 *  !0 Error
 */
int hctr_read(pHCTR hctr, unsigned long long* value);

/**
 * Destroy the 64-bit counter
 *
 * \param ptr address of pointer to opaque private data structure
 *
 * \return
 *   0 OK
 *  !0 Error
 */
int hctr_dtor(pHCTR* hctr);

/**
 * Tests returned error value to see if it represents failure
 *
 * \param error a value returned from another hctr function
 *
 * \return
 *   true the error was a failure
 *   false the error was not a failure (warning)
 */
bool hctr_failed(int error);

/**
 * Retrieves a textual representation of the most recent error
 *
 * \param buff a pointer to the buffer to receive the text
 * \param len the length of the provided buffer
 */
void hctr_errmsg(char* buff, int len);

#endif