/*------------------------------------------------------------------------ 
 dbAx class library - version 1.0.0
 Copyright (c) 2007-2008 Data Management Systems. 

 Description
 -----------
 The dxAx library consists of a set of C++ classes that wrap the
 Microsoft ActiveX Data Objects (ADO) interface allowing C++ 
 application developers to access databases in a native C++ environment.
 The objective of this library is to relieve the developer from the
 details of COM interfaces and having to translate VARIANT data types
 into common C++ data types.

 The dbAx library does not rely on MFC with the exception of the 
 CString and COleDateTime classes. Since the majority Windows
 applications are expected to utilize MFC, this is not seen as a
 real drawback. It is possibile, though, to develop non-MFC
 applications using this library since CString and COleDateTime are
 stand-alone and do not rely on any base class from the MFC library.

 Disclaimer
 ----------
 This software is provided 'AS IS', WITHOUT ANY WARRANTY, express
 or implied, as to MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 In no event shall the author be held liable for any damages arising
 from the use of this software.

 Any conflict with outside or third party entities regarding the naming
 convention used in this software, specifically 'dbAx', 'AxLib' or the
 prefix 'CAx' is unintended and purly coincidental.

 Data Management System reserves the right to modify and update this
 code without notice.

 License
 -------
 Permission is granted to anyone to use this software for any purpose,
 including commercial applications. You may alter this software to
 suite a particular purpose and redistribute it subject to the following
 conditions:

  1. You must not misrepresent the origin of this work claiming that
     you wrote the original software. Using this software in a project
     or product does not require that you acknowledge its use, but
     reference to it is certainly appreciated.

  2. If you alter this version of the software, it must be plainly marked
     as such and not misrepresented as being the original work.

  3. This notice and disclaimer may not be removed or altered from any
     source distribution of the product.

  Revision History
  ----------------
  v1.0.0  - 12/21/07
    Initial release.

  v1.0.1  - 2/10/2008
    Corrected fuction calls mixing 'BOOL' and 'bool' data types. VS2005
    produces errors since 'bool' is now an intrinsic data type. Also
    corrected errors in AxGen producing erroneous code.

  v1.1.0  - 2/25/08
    Numerious updates...
    
    .Rewrote a lot of code to avoid potentially calling invalid or
     NULL pointers.

    .Moved the 'Release' of underlying COM objects into the Destructor of
     class objects.

    .No longer necessary to call Create() prior to opening a CAxRecordset
     object provided no calls are made to methods affecting object settings
     or parameters prior to calling Open(). This is especially useful where
     temporary or ad-hoc recordsets are opened, closed and reopened using a
     new SQL query statement generated on the fly.

    .Revisited the FX_xxx functions to take into account the ADO flags
     adFldUpdatable and adFldUnknownUpdatable (see comment on 
     _isUpdatable()). Replaced the FX_Provider and SetVariant functions 
     with:
      
      HRESULT ::_setGetFieldValue(bool bSave, LPCTSTR lpszColumn,
                                  unsigned short varType, void* pvValue);

     This uses the helper function _getFldValue() or _setFldValue depending
     on the bSave flag. More testing done on all SQL data types to ensure
     correct translation. Client code, however, can still use the FX_xxx
     functions as always with the exception of FX_Money (see following
     comment).
    
    .Changed the data types for FX_Money and FX_SmallMoney to COleCurrency. 
     This MFC class encapsulates the CURRENCY struct and is better suited
     to handling monetary values as opposed to a double. Previous client
     code will need to be updated to handle the new data type.

    .Corrected the situation where an error was thrown if a match was not
     found for an ADOField specified in the DoFieldExchange method of a
     CAxRecordset object. This can occur if the derived class tags most or
     all of the fields in a table, however, a CAxCommand object
     (i.e. stored procedure) is used to return only a subset of the fields.
     The library generates the error code ERROR_INVALID_ACCESS, but does
     not consider it fatal.

    .Updated the AxGen utility to support the changes made in this version.
     When creating a user specified class for a CAxCommand object, AxGen
     matches the variant types in the derived class' _CreateParameters()
     method. AxGen substitutes '\' with '\\' when building a connection
     string so the C++ compiler recognizes the single delimiter.

    .Updated documentation as needed.

  v1.2.0  - 12/25/08
    .Added call to CursorLocation in the Open methods of CAxRecordset. This
     performs bounds checking and sets the CursorLocation for the Recordset
     based on the eCursorLocation parameter (per Dan via CodeProject).

    .Removed assumed values in the CAxRecordset::_getFldValue method. If the
     method failed, an assumed valued was used (i.e. 0). No assumption should
     be made, therefore the client application should initialize a recordset
     field variable before making a call to _getFldValue, directly or through
     one of the CAxRecordset::FX_{xxx} methods.

    .Moved call to CAxCommand::_CreateParameters to CAxCommand::Create(). 
     Deleted call to _CreateParameters in the CAxRecordset::Open method.
     This was necessary in the event that a CAxCommand object is used in a
     manner other than opening a recordset. For example, using a CAxCommand
     object to simply execute a stored procedure that does not involve
     returning table records (i.e. INSERT)

    .Added code to the CAxCommand::Execute method. A CAxCommand object can
     now be used to execute a stored procedure that may not involve a recordset.
     A typical case is accessing a stored procedure that does not involve a 
     SQL SELECT (i.e. INSERT)

    .Changed CAxRecordset::FX_TinyInt to use VT_UI1 (BYTE) rather than VT_I2
     (short). 

  How to use this library
  -----------------------
  1. Add the AxLib source files to your project. This includes:
      AxLib.h
      AxConnection.cpp
      AxCommand.cpp
      AxRecordset.cpp
      AxException.cpp

	2. Add "#include <AxLib.h> in the project's stdafx.h file.

  3. AxLib provides the GenGUIDStr function to support the generation
     of a unique GUID character string. A GUID string can be used with
     SQL Server's UniqueIdentifier field. If you need this functionality,
     un-remark the "#define GEN_GUID_STR" statement below. You will also 
     need to add a reference to Rpcrt4.lib in the project settings. This
     is found under:

         Project Settings/Linker Options/Input/Additional Dependencies

  4. Create an instance of the CAxConnection object.

  5. Create instance(s) of custom derived version of CAxCommand and CAxRecordset.

  6. Initialize the library at program startup using dbAx::Init()

  7. Open connection, command, and recordset objects as needed.

  8. At program terminstion, call the dbAx::Term() function to properly
     shut down the library.

  For a complete discussion on using the AxLib library, see the 
  accompanying documentation in the compiled help file - dbAx.chm
------------------------------------------------------------------------*/

#ifndef _AXLIB_H_
#define _AXLIB_H_

#include <icrsint.h>	  // ADO class extensions
#include <comdef.h>		  // COM support
#include <crtdbg.h>     // Debug _ASSERT support

//Redefine GUID macro to eliminate EXTERN_C
//ADO GUID interface delcaration (contained in adoid.h) are defined here, otherwise
//#else directive defines them as "extern "C" declarations
//NOTE: DEFINE_GUID macro in objbase.h includes the EXTERN_C statement which 
//      causes the compiler to choke on macro expansion during Link 
//      operations. Why??
#ifdef DEFINE_GUID
	#undef DEFINE_GUID
#endif

#define DEFINE_GUID(name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8) \
        const GUID name = { l, w1, w2, { b1, b2,  b3,  b4,  b5,  b6,  b7,  b8 } }

// ******************************************************************************
//Un-Remark this define if you intended to use the
//global GenGUIDStr function. If so, you will need to
//add a reference to Rpcrt4.lib to the project settings.
//See note 3 in the "How to use this Library" section
//above.
//#define GEN_GUID_STR
// ******************************************************************************

#if _MSC_VER == 1200
  #include <afx.h>        // Support for CString VC6
  #include <afxdisp.h>    // Support for COleDateTime VC6
#else
  #include <atlstr.h>     // Support for CString
  #include <ATLComTime.h> // Support for COleDateTime
#endif

#include <adoid.h>      // ADO GUID's
#include <adoint.h>		  // ADO C++ header

#include <math.h>
#include <stdio.h>
#include <io.h>
#include <fcntl.h>
#include <tchar.h>			// Unicode
#include <vector>       // STL vector

using namespace std;

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
namespace dbAx {
  //AxLib errors.
  //Note: most error conditions use the AXLIB_ERROR_NONE enum and pull
  //      error information from the ADO COM interface.
  enum AxLibErrorEnums
  {
    AXLIB_ERROR_NONE = 0,
    AXLIB_ERROR_INIT = 5001,
    AXLIB_ERROR_DXBIND = 5002,
    AXLIB_ERROR_OBJECT_NOTOPEN = 5003,
    AXLIB_ERROR_BUF_SIZE = 5004,
    AXLIB_ERROR_NULL_PTR = 5005,
    AXLIB_ERROR_ENUM = 5006,
    AXLIB_ERROR_INVALID_POS = 5007,
  };

   //Header information prepended to binay data
   //field (i.e. image)
   typedef struct tagBINDATAINFOHEADER
    {
	    long		imgSize;	//uncompressed size
	    long		cmpSize;	//compressed size
	    long		lReserved1;	//Future
	    long		lReserved2; //Future
    } BINDATAINFOHEADER;


  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // Classes defined in this header file

    class CAxConnection;
    class CAxCommand;
    class CAxRecordset;
    class CAxException;
    class CAxConnectionEvents;
    class CAxRecordsetEvents;
 
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // Global namespace definitions and functions
  // AxLib Exception handling
  void ThrowAxException(int nAxError = AXLIB_ERROR_NONE, 
                         LPCTSTR lpszMsg = NULL,
                         HRESULT hr = S_OK);

  //Connection objects collection
  typedef std::vector<CAxConnection*> _AxConnectionsT;
  extern _AxConnectionsT m_AxConnections;

  //Initialization and Termination
  void Init();                                    //Initialize the library
  void Term();                                    //Terminate and cleanup
  void DropConnection(CAxConnection *pCn);

  //Utility functions
  const wchar_t*   M2W(LPCSTR lpszCharStr);       //char -> wchar
  const char*      W2M(LPCWSTR lpszWideCharStr);  //wchar -> char

#ifdef GEN_GUID_STR
  //The GenGUIDStr function will generate a string
  //version of a GUID that can be used with the SQL
  //Server UniqueIdentifier field.
  HRESULT          GenGUIDStr(CString& szGUID);
#endif


//Debug assert on ADO objects pointers
#ifdef _DEBUG
#define VALID_ADO_OBJECT(a) if(a == NULL) ThrowAxException(AXLIB_ERROR_NULL_PTR)
#else
#define VALID_ADO_OBJECT(a) 
#endif

  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // CAxConnection class
  // Desc: Open and maintain a connection to an OLEDB
  //       Data Provider. AxCommand and AxRecordset
  //       objects use an existing AxConnection object.
  class CAxConnection
  {
    friend class CAxException;
    friend class CAxRecordset;

    //Construction
    public:
    CAxConnection();
    CAxConnection(LPCTSTR lpszConnectStr);
    virtual ~CAxConnection();

    //Attributes
    public:

    protected:
    //CAxRecordset objects collection associated with
    //this connection object
    ADOConnection* m_piConnection;

    DWORD          m_dwEvents;               //Connection events cookie
    CString 			 m_strConnect;             //OLEDB Provider connection string

    //Implementation
    public:
    void           Create();