home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1999 January / pcwk_01_1999.iso / Wtestowe / Vistdstd / Install / Data.Z / Helpers.H < prev    next >
Encoding:
C/C++ Source or Header  |  1997-11-11  |  10.1 KB  |  335 lines
  1. /*    HELPERS.H - Helper classes for easing BSTR and VARIANT and SAFEARRAY use.
  2.  *  Copyright (C) 1996-1997 Visio Corporation. All rights reserved.
  3.  */
  4.  
  5. #ifndef HELPERS_____
  6. #define HELPERS_____
  7.  
  8. /******************************************************************************/
  9. //
  10. //    YOU can define your own "helper classes" for string and variant
  11. //    args to OLE automation methods. The required elements are listed
  12. //    below in our example helper classes. These classes are what make it
  13. //    easy to create clean C++ code to drive OLE Automation objects.
  14. //
  15. //    You may use the example helper classes as is or you may derive your own
  16. //    to use.
  17.  
  18.  
  19. /******************************************************************************/
  20. //
  21. //    *** Scenarios ***    (scenarii?)
  22. //
  23. //    (do ONE of the following)
  24. //
  25. //
  26. //    <1>    #define NO_HELPERS
  27. //            BSTR_HELPER_CLASS    == BSTR
  28. //            VARIANT_HELPER_CLASS == VARIANT
  29. //
  30. //    <2>    #define BSTR_HELPER_CLASS or VARIANT_HELPER_CLASS independently.
  31. //
  32. //    <3>    #define MFC_HELPERS
  33. //            BSTR_HELPER_CLASS    == VString     (...if you didn't define your own.)
  34. //            VARIANT_HELPER_CLASS == COleVariant (...if you didn't define your own.)
  35. //
  36. //    <4>    Don't #define anything and take the defaults:
  37. //            BSTR_HELPER_CLASS    == VBstr    (...if you didn't define your own.)
  38. //            VARIANT_HELPER_CLASS == VVariant (...if you didn't define your own.)
  39. //
  40. //
  41. //    *** IMPORTANT ***
  42. //
  43. //    If you want a VARIANT helper class, but NO BSTR helper class:
  44. //        #define BSTR_HELPER_CLASS        BSTR
  45. //        #define NO_BSTR_HELPER            //    <--- *** Important ***
  46. //        #define VARIANT_HELPER_CLASS    MyVariantHelper
  47. //
  48. //    The NO_BSTR_HELPER definition is how we know whether to do a SysFreeString
  49. //    internal to the wrapper class methods. If it's NOT defined, we do a
  50. //    SysFreeString after getting a BSTR from an OLE method and passing a copy
  51. //    of it to the BSTR_HELPER_CLASS through its assignment operator.
  52. //    If there is no BSTR_HELPER_CLASS, then we just do a straight BSTR assignment
  53. //    and if we did a SysFreeString "for you," you'd probably get a little
  54. //    perturbed about it!
  55.  
  56.  
  57. /******************************************************************************/
  58. //    For those who require no!! help:
  59.  
  60. #ifdef NO_HELPERS
  61.  
  62. #undef BSTR_HELPER_CLASS
  63. #undef VARIANT_HELPER_CLASS
  64.  
  65. #define BSTR_HELPER_CLASS        BSTR
  66. #define NO_BSTR_HELPER
  67.  
  68. #define VARIANT_HELPER_CLASS    VARIANT
  69. #define NO_VARIANT_HELPER
  70.  
  71. #endif    //    NO_HELPERS
  72.  
  73.  
  74. #ifdef MFC_HELPERS
  75. #include <afx.h>    //    MFC file where CString is defined
  76. #endif
  77.  
  78. /******************************************************************************/
  79. //    The default BSTR helper class interface:
  80.  
  81. #define VBSTR_CASE_INSENSITIVE 0
  82.  
  83. class VBstr
  84. {
  85. // Constructors
  86. public:
  87.     VBstr();
  88.     VBstr(const VBstr FAR &other);                            //    a good idea since our constructors allocate memory...
  89.     VBstr(LPCTSTR lpStr);                                    //    construct from LPCTSTR / const char * / CString
  90.     VBstr(BSTR bstr, BOOL bAssumeResponsibility= FALSE);    //    *REQUIRED* for compiling with wrapper classes
  91.  
  92.     virtual ~VBstr();
  93.  
  94.  
  95. // Operations
  96. public:
  97.     operator const BSTR() const;                            //    *REQUIRED* for compiling with wrapper classes
  98.     const VBstr FAR &operator=(const BSTR bstr);            //    *REQUIRED* for compiling with wrapper classes
  99.     const VBstr FAR &operator=(const VBstr FAR &other);        //    a good idea since we have a copy constructor...
  100.     const VBstr FAR &operator=(LPCTSTR lpStr);                //    useful -- requested!
  101.     const VBstr FAR &operator=(LPCOLESTR lpOlestr);            //    useful -- requested!
  102.  
  103.     BOOL operator==(const VBstr FAR &other) const;            //    comparison operator -- case sensitive
  104.     BOOL Compare(const VBstr FAR &other, BOOL bCaseSensitive= TRUE) const;
  105.  
  106. #ifdef MFC_HELPERS
  107.     void ConvertToCString(CString FAR& cstr);
  108. #endif
  109.  
  110.     HRESULT ConvertToLPTSTR(LPTSTR pStr, ULONG *pnBytes);
  111.  
  112. private:
  113.     HRESULT AllocFromLPCTSTR(LPCTSTR lpStr);                //    called ONLY from constructor/operator=
  114.     BSTR m_bstr;
  115. };
  116.  
  117.  
  118.  
  119. /******************************************************************************/
  120. //    The default VARIANT helper class interface:
  121.  
  122. class VVariant
  123. {
  124. public:
  125.     VVariant();
  126.     VVariant(const VVariant& other);
  127.     VVariant(const VARIANT& v);                //    *REQUIRED* for compiling with wrapper classes
  128.     VVariant(LPCTSTR p);
  129.     VVariant(const BSTR bstr, BOOL bAssumeResponsibility= FALSE);
  130.     VVariant(const long n);
  131.     VVariant(const double d);
  132.     VVariant(const LPUNKNOWN pUnk);
  133.     VVariant(const LPDISPATCH pDisp);
  134.  
  135.     virtual ~VVariant();
  136.  
  137.  
  138.     operator VARIANT *();                        //    *REQUIRED* for compiling with wrapper classes
  139.     operator VARIANT();                            //    *REQUIRED* for compiling with wrapper classes
  140.     operator const VARIANT() const;                //    *REQUIRED* for compiling with wrapper classes
  141.  
  142.     const VVariant& operator=(const VVariant& other);
  143.     const VVariant& operator=(const VARIANT& v);
  144.     const VVariant& operator=(LPCTSTR p);
  145.     const VVariant& operator=(const BSTR bstr);
  146.     const VVariant& operator=(const long n);
  147.     const VVariant& operator=(const double d);
  148.     const VVariant& operator=(const LPUNKNOWN pUnk);
  149.     const VVariant& operator=(const LPDISPATCH pDisp);
  150.  
  151. private:
  152.     VARIANT m_v;
  153.  
  154.     void Init(void);
  155.     void Clear(void);
  156.  
  157. public:
  158.     void Copy(const VARIANT &v);
  159. };
  160.  
  161.  
  162.  
  163. /******************************************************************************/
  164. //    The default SAFEARRAY helper class interface:
  165.  
  166.  
  167. #define DIM_UNINITIALIZED    (unsigned int)(-1)
  168.  
  169.  
  170. class VSafeArray {
  171.  
  172. public:
  173.     //    Empty (good for passing as output arg to, for example, "Collection.GetNames"):
  174.     VSafeArray();
  175.  
  176.     //    Generic:
  177.     VSafeArray(VARTYPE vt, unsigned int nDims, SAFEARRAYBOUND FAR* pBounds);
  178.  
  179.     //    Simple 1D:
  180.     VSafeArray(VARTYPE vt, ULONG cElements, LONG lLbound);
  181.  
  182.     //    2D:
  183.     VSafeArray(VARTYPE vt, ULONG cElements1, LONG lLbound1, ULONG cElements2, LONG lLbound2);
  184.  
  185.     //    3D:
  186.     VSafeArray(VARTYPE vt, ULONG cElements1, LONG lLbound1, ULONG cElements2, LONG lLbound2, ULONG cElements3, LONG lLbound3);
  187.  
  188.     virtual ~VSafeArray();
  189.  
  190.     virtual BOOL IsSet(void) { return (NULL!=m_pSA); };
  191.  
  192.     virtual unsigned int GetDimensions(void);
  193.     virtual long GetNumberElements(unsigned int nDim= 1);
  194.     virtual long GetLower(unsigned int nDim= 1);
  195.     virtual long GetUpper(unsigned int nDim= 1);
  196.  
  197.     virtual HRESULT PutElement(long *pnIndices, void const *pData);
  198.     virtual HRESULT GetElement(long *pnIndices, void *pData);
  199.  
  200.     //    These two merely grant access to data member or its address:
  201.     operator SAFEARRAY FAR* const (void) const;
  202.     operator SAFEARRAY FAR* FAR* (void) const;
  203.  
  204.     //    This one cleans out the data member before giving back its address:
  205.     virtual SAFEARRAY FAR* FAR* LPLPSAFEARRAY(void);    //    pass as an 'out' arg; i.e. filled in by called function...
  206.  
  207. protected:
  208.     virtual HRESULT Init(void);
  209.     virtual HRESULT Create(VARTYPE vt, unsigned int nDims, SAFEARRAYBOUND FAR* pBounds);
  210.     virtual HRESULT Destroy(void);
  211.  
  212. private:
  213.     unsigned int m_nDims;
  214.     VARTYPE m_vt;
  215.     SAFEARRAY FAR* m_pSA;
  216. };
  217.  
  218.  
  219. //    1D case - putters and getters for basic element types:
  220.  
  221. class VSafeArray1D : public VSafeArray {
  222.  
  223. public:
  224.     //    Empty (good for passing as input arg):
  225.     VSafeArray1D() { };                                                //    parent class does it all...
  226.  
  227.     //    Simple 1D:
  228.     VSafeArray1D(VARTYPE vt, ULONG cElements, LONG lLbound) :
  229.             VSafeArray(vt, cElements, lLbound) { };                    //    parent class does it all...
  230.  
  231.     virtual ~VSafeArray1D() { };                                    //    parent class does it all...
  232.  
  233.     virtual HRESULT PutShort(long nIndex, short n);
  234.     virtual HRESULT PutLong(long nIndex, long n);
  235.     virtual HRESULT PutDouble(long nIndex, double d);
  236.     virtual HRESULT PutBstr(long nIndex, BSTR bstr);
  237.     virtual HRESULT PutVariant(long nIndex, const VARIANT &v);
  238.     virtual HRESULT PutObject(long nIndex, LPUNKNOWN pUnk);
  239.  
  240.     virtual short GetShort(long nIndex);
  241.     virtual long GetLong(long nIndex);
  242.     virtual double GetDouble(long nIndex);
  243.     virtual BSTR GetBstr(long nIndex);
  244.     virtual VARIANT GetVariant(long nIndex);
  245.     virtual LPUNKNOWN GetObject(long nIndex);
  246. };
  247.  
  248.  
  249.  
  250. /******************************************************************************/
  251. //    For those using MFC requiring help:
  252.  
  253. #ifdef MFC_HELPERS
  254.  
  255. //    Get rid of const-ness default for wrapper class input arguments:
  256. //        (allows operator const BSTR to be a non-const method;
  257. //         that is, we can do a data member assignment inside of it...)
  258. #define VW_CONST
  259.  
  260. class VString : public CString
  261. {
  262. public:
  263. //    Inherited from CString, straight pass-throughs:
  264.     VString() { }
  265.     VString(const VString& stringSrc) : CString(stringSrc) { }
  266.     VString(TCHAR ch, int nRepeat = 1) : CString(ch, nRepeat) { }
  267.     VString(LPCSTR lpsz) : CString(lpsz) { }
  268.     VString(LPCWSTR lpsz) : CString(lpsz) { }
  269.     VString(LPCTSTR lpch, int nLength) : CString(lpch, nLength) { }
  270.     VString(const unsigned char* psz) : CString(psz) { }
  271.  
  272.  
  273. //    The class "VString" requires the class VBstr...
  274. //    It uses VBstr to accomplish assignments and conversions:
  275.  
  276. private:
  277.     VBstr m_vbstr;    //    Destroyed when VString is destroyed...
  278.  
  279. //    Add these three *REQUIRED* ops:
  280. public:
  281.     VString(const BSTR bstr, BOOL bAssumeResponsibility= FALSE)
  282.     {
  283.         VBstr vb(bstr);
  284.         vb.ConvertToCString(*this);
  285.         if (bAssumeResponsibility && bstr)
  286.             SysFreeString(bstr);
  287.     }
  288.  
  289.     operator const BSTR()
  290.     {
  291.         m_vbstr= (LPCTSTR) this;
  292.         return m_vbstr;
  293.     }
  294.  
  295.     const VString &operator=(const BSTR bstr)
  296.     {
  297.         VBstr vb(bstr);
  298.         vb.ConvertToCString(*this);
  299.         return (*this);
  300.     }
  301. };
  302.  
  303. #ifndef BSTR_HELPER_CLASS
  304. #define BSTR_HELPER_CLASS        VString
  305. #endif
  306.  
  307. #ifndef VARIANT_HELPER_CLASS
  308. #define VARIANT_HELPER_CLASS    COleVariant
  309. #endif
  310.  
  311. #endif    //    MFC_HELPERS
  312.  
  313.  
  314. /******************************************************************************/
  315. //    For those requiring the simplest level of help:
  316.  
  317. #ifndef BSTR_HELPER_CLASS
  318. #define BSTR_HELPER_CLASS        VBstr
  319. #endif
  320.  
  321. #ifndef VARIANT_HELPER_CLASS
  322. #define VARIANT_HELPER_CLASS    VVariant
  323. #endif
  324.  
  325.  
  326. /******************************************************************************/
  327. //    Abstract use of helpers regardless of which set you're actually using:
  328.  
  329. #define H_Str(s)            (   BSTR_HELPER_CLASS( (LPCTSTR) (s) )             )
  330. #define H_Long(v)            (   VARIANT_HELPER_CLASS( (const long) (v) )     )
  331. #define H_StrVar(v)            (   VARIANT_HELPER_CLASS( (const char *) (v) )   )
  332.  
  333.  
  334. #endif    //    HELPERS_____
  335.