#if !defined(__HR_LIB_H__)
#define __HR_LIB_H__
///////////////////////////////////////////////////////////////////////////////////////////////////
//
//  File:           HR_Lib.h
//
//                  Copyright 2005 Imaginant, Inc.
//
//  Source:         Original.
//
//  Description:    Function definitions for the HR_Lib
//
//  Change History:
//          2004.10.01   Started source
//          2005.02.08   Updated
//
///////////////////////////////////////////////////////////////////////////////////////////////////



// HR_LIB_EXPORTS is only defined in the project that builds the DLL, it MUST NOT be defined
// by application that include HR_Lib files.
#ifdef HR_LIB_EXPORTS
#define HR_LIB_API __declspec(dllexport)
#else
#define HR_LIB_API __declspec(dllimport)
#endif

// The interface to the Library is exported as a C interface
#ifdef __cplusplus
extern "C" {
#endif

 // this file will only be used once in any compile that includes it
#if PRAGMA_ONCE
#pragma once
#endif

// If we are using windows, our interface will pack data structures to 8 byte boundaries
#ifdef WIN32
#pragma pack (push, 8)
#endif

// Other interface headers ONLY 
#include "HR_Types.h"
#include "HR_Errors.h"


///////////////////////////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////// Library Functions ////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_OpenLibrary
//
//    Description:
//      Initialize the SDK and return a handle to the manager for this library. This function
//      must be called once per process and balanced with a call to HR_CloseLibrary.
//
//    Returns:    Error codes as defined in HR_Errors.h
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_OpenLibrary
(
    HR_Int32Type   inOptionBits, // Each bit specifies an option, unused bits must be 0
    HR_LibHandle*  outLibHandle  // will be needed for later calls
);


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_CloseLibrary
//
//    Description:
//      Closes the library, releasing all resources.
//
//    Returns:    Error codes as defined in HR_Errors.h
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_CloseLibrary
(
    HR_LibHandle inLibHandle // the library handle created by HR_OpenLibrary
);


///////////////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////// Camera Functions ////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_GetCameraList
//
//    Description:
//      Gives the calling application a list of available cameras
//
//    Returns:    Error codes as defined in HR_Errors.h
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_GetCameraList
(
    HR_LibHandle     inLibHandle,   // must be a valid library handle
    HR_Int32Type     inBufferCount, // element count the app. allocated for outCameraList
    HR_Int32Type*    outAvailCount, // Library reports how many cameras found
    HR_CamHandle*    outCameraList  // allocation must match inBufferCount
);


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_OpenCamera
//
//    Description:
//      Opens a camera object.
//
//    Returns:    Error codes as defined in HR_Errors.h
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_OpenCamera
(
    HR_CamHandle    inCameraHandle     // must be a valid handle
);


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_CloseCamera
//
//    Description:
//      Closes the camera, releasing all resources.
//
//    Returns:    Error codes as defined in HR_Errors.h
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_CloseCamera
(
    HR_CamHandle    inCameraHandle     // must be an open camera handle
);


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_TriggerCamera
//
//    Description:
//      Sends a trigger to the camera, which is exactly the same as an external trigger. Depending
//      on other setup information, this can  trigger one or several image captures.
//
//    Returns:    Error codes as defined in HR_Errors.h
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_TriggerCamera
(
    HR_CamHandle    inCameraHandle     // must be an open camera handle
);



///////////////////////////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////// Image  Functions /////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_GetImageList
//
//    Description:
//      Gives the calling application a list of available images. The inHandle argument can be for
//      either the library or one camera.
//
//      If inHandle is the Library handle, all available images will be listed. If InHandle is a 
//      camera handle, the list will be just those image handles that were made by the 
//      specified camera.
//
//    Returns:    Error codes as defined in HR_Errors.h
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_GetImageList
(
    HR_BaseHandle   inHandle,      // can be the Library or one specific camera
    HR_Int32Type    inBufferCount, // element count the app. allocated for outImageList
    HR_Int32Type*   outAvailCount, // Lib reports how many images found
    HR_ImgHandle*   outImageList   // allocation must match inBufferCount
);


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_OpenImage
//
//    Description:
//      Opens an image object. 
//
//    Returns:    Error codes as defined in HR_Errors.h
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_OpenImage
(
    HR_ImgHandle   inImageHandle   // must be a valid handle
);


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_CloseImage
//
//    Description:
//      Closes the image, and releses some (but not all) resources allocated for to access the
//      image. In order to access an image handle after it has been  closed, it must be opened 
//      again via HR_OpenImage
//
//    Returns:    Error codes as defined in HR_Errors.h
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_CloseImage
(
    HR_ImgHandle   inImageHandle     // must be a valid open handlew
);


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_DeleteImage
//
//    Description:
//      Deletes the image, releases ALL resources.  Once an image has been deleted, it can no 
//      longer be accessed.  The handle that identified the image is no longer valid.
//
//      If the image is "open", this function will close it before deleting it.
//
//    Returns:    Error codes as defined in HR_Errors.h
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_DeleteImage
(
    HR_ImgHandle   inImageHandle     // must be a valid image handle
);



///////////////////////////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////// General Functions ////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_GetParamInfo
//
//    Description:
//       Get the size, type, and access mode for the specified Parameter ID.  This function works 
//       for Library, Camera, and Image Handles.
//
//    Returns:    Any of the tool kit errors
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_GetParamInfo
(
    HR_BaseHandle      inHandle,   // handle to an open lib, cam, or img object
    HR_ParamIdEnumType inID,       // the enumerated ID of a parameter
    HR_InfoType*       outInfo     // all the info in this struct
);


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_GetParam
//
//    Description:
//      Get the value of the specified Parameter ID
//      This function works for Library, Camera, and Image Handles.
//
//    Returns:    Any of the tool kit errors
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_GetParam
(
    HR_BaseHandle      inHandle,     // a handle to a lib, cam, or img object
    HR_ParamIdEnumType inID,         // the enum, enumerated ID of an parameter
    HR_Int32Type       inCount,      // count of elelments outpValue can hold
    HR_Int32Type*      outAvailCount,// count of elements ( not bytes ) available.
    void*              outpValue     // The HR Library will copy data TO app memory
);


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_SetParam
//
//    Description:
//     Set the value of the specified parameter ID. 
//     "value" can be a single value, an array, or a struct.
//
//     This function works for Library, Camera, and Image Handles.
//
//    Returns:    Any of the tool kit errors
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_SetParam
(
    HR_BaseHandle      inHandle,  // a handle to a lib, cam, or img object
    HR_ParamIdEnumType inID,      // the enum, enumerated ID of an parameter
    HR_DataTypeEnumType    inType,    // the data type of the param, for error checking
    HR_Int32Type       inCount,   // count of elements (not bytes) Library should copy
    void*              inpValue   // The HR Library will copy data FROM app memory
);



///////////////////////////////////////////////////////////////////////////////////////////////////
/////////////////////////////////////// Event Notification Functions //////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////////////////



///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_Poll
//
//    Description:
//
//    Returns:    Any of the tool kit errors
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API HR_StatusType HR_Poll
(
    HR_BaseHandle   inHandle,      // handle to the relevent Lib, Cam, or Image
    HR_Int32Type    inEventGroup,  // Event group we are interested in for
    HR_Int32Type*   outEventFlags  // Events flags for events we have recieved
);

///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_GetErrorString
//
//    Description:
//    HR_GetErrorString decodes a number into a zero-terminated string 
//    representation of number and the enum as defined in HR_Errors.h
//
//    For example, if the value 100 is the input argument, the string
//    created will be " 100 HR_ERR_PID_NOT_VALID"
//
//    HR_GetErrorString always returns a pointer to a string, even if the
//    inErrorNumber argument is "HR_OK". In that case, the string will be
//       "   0 HR_OK"
//
//    If the inErrorNumber is not valid, e.g. 4321, the string will display 
//       "4321 IS NOT A VALID HR_Lib ERROR NUMBER" 
//
//    To allow the application more flexibility, the string does not have "\n"
//
//    The returned char* always points to the same buffer internal to the
//    HR Library, which will be overwritten the next time HR_GetErrorString
//    is called. Therefore, the application should either display the
//    string immediately or make a copy of the string for later display.
//
//    Example:
//      status = HR_SomeFunction(...)
//      if ( status != HR_OK )
//           printf("HR_Lib ERROR %s\n", HR_GetErrorString(status));
//
//
//    Returns:    pointer to a char string
///////////////////////////////////////////////////////////////////////////////////////////////////

HR_LIB_API char* HR_GetErrorString
(
    HR_Int32Type inErrorNumber
);

///////////////////////////////////////////////////////////////////////////////////////////////////
//
// Use of callbacks with the HR Library is optional.
//
// HR_CallbackType defines the signature of callback functions that must exist 
// within the application in order to use the HR Library callback mechanism.
//
// The application's callback function will be called by the HR Library after
// it is set up within the HR Library using HR_RegisterCallback and the specified
// event(s) occur within the HR Library.
//
///////////////////////////////////////////////////////////////////////////////////////////////////

typedef void (CALLBACK *HR_CallbackType)
(
    HR_Int32Type   inEvent,     // The type of event we are sending notice of
    HR_BaseHandle  inHandle,    // handle to the relevent Lib, Cam, or Image
    HR_InfoType    inInfo,      // The HR_Info structure for the info
    HR_Int32Type*  iopInfo,     // the pointer to the Info we are returning
    HR_Int32Type   inParam1,    // Other parameters (not always used)
    void*          inpUserData  // application's void pointer for application's use
);


///////////////////////////////////////////////////////////////////////////////////////////////////
//
//    Function:    HR_RegisterCallback
//
//    Description: Registers an application callback with the library
//
//    Returns:    Any of the tool kit errors, HR__InvalidAttrIDErr
///////////////////////////////////////////////////////////////////////////////////////////////////
HR_LIB_API HR_StatusType HR_RegisterCallback
(
    HR_BaseHandle*   inHandle,   // handle to the relevent Lib, Cam, or Image
    HR_CallbackType* inCallbackFunctionPointer, // see HR_CallbackType
    void*            inpUserData // value will be passed to callback's inpUserData
);



///////////////////////////////////////////////////////////////////////////////////////////////////
// END OF FUNCTION DECL
///////////////////////////////////////////////////////////////////////////////////////////////////

// remove the pragma for packing data structures to 8 byte boundries
#ifdef WIN32
#pragma pack (pop)
#endif

#ifdef __cplusplus
}
#endif

#endif    //__HR_LIB_H__