gears/base/ie/activex_utils.h

   1 // Copyright 2006, Google Inc.
   2 //
   3 // Redistribution and use in source and binary forms, with or without
   4 // modification, are permitted provided that the following conditions are met:
   5 //
   6 //  1. Redistributions of source code must retain the above copyright notice,
   7 //     this list of conditions and the following disclaimer.
   8 //  2. Redistributions in binary form must reproduce the above copyright notice,
   9 //     this list of conditions and the following disclaimer in the documentation
  10 //     and/or other materials provided with the distribution.
  11 //  3. Neither the name of Google Inc. nor the names of its contributors may be
  12 //     used to endorse or promote products derived from this software without
  13 //     specific prior written permission.
  14 //
  15 // THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
  16 // WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  17 // MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
  18 // EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  19 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  20 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  21 // OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  22 // WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  23 // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  24 // ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 //
  26 // A collection of static utility methods.
  27
  28 #ifndef GEARS_BASE_IE_ACTIVEX_UTILS_H__
  29 #define GEARS_BASE_IE_ACTIVEX_UTILS_H__
  30
  31 #include "gears/base/common/string16.h"
  32 #include "gears/base/ie/atl_headers.h"
  33
  34 struct IHTMLElement;
  35 class SecurityOrigin;
  36
  37 #ifdef WINCE
  38 struct IWebBrowser2;
  39 struct IPIEHTMLDocument;
  40 struct IPIEHTMLDocument2;
  41 struct IPIEHTMLWindow2;
  42 typedef IPIEHTMLDocument IHTMLDocument;
  43 typedef IPIEHTMLDocument2 IHTMLDocument2;
  44 // WinMo 5 SDK defines IHTMLWindow2, so we can't typedef IPIEHTMLWindow2.
  45 #endif
  46
  47 class ActiveXUtils {
  48  public:
  49   // Returns the location url of the containing webBrowser as determined by
  50   // IWebBrowser2.LocationURL.
  51   // TODO(cprince): across the codebase, change PageOrigin to PageSecurityOrigin
  52   // and PageLocation to PageLocationUrl, for consistency.
  53   static bool GetPageLocation(IUnknown *site, std::string16 *page_location_url);
  54   static bool GetPageOrigin(IUnknown *site, SecurityOrigin *security_origin);
  55
  56 #ifdef WINCE
  57   // We're not able to get IWebBrowser2 on WinCE. Instead we obtain the window
  58   // and document objects from the script engine's IDispatch pointer.
  59 #else
  60   // Returns the IWebBrowser2 interface corresponding to the given site.
  61   static HRESULT GetWebBrowser2(IUnknown *site,
  62                                 IWebBrowser2 **browser2);
  63 #endif
  64
  65   // Returns the IHTMLDocument2 interface corresponding to the given site.
  66   static HRESULT GetHtmlDocument2(IUnknown *site,
  67                                   IHTMLDocument2 **document2);
  68
  69   // Returns the IHTMLWindow2 interface corresponding to the given site.
  70   static HRESULT GetHtmlWindow2(IUnknown *site,
  71 #ifdef WINCE
  72                                 IPIEHTMLWindow2 **window2);
  73 #else
  74                                 IHTMLWindow2 **window2);
  75 #endif
  76
  77 #ifdef WINCE
  78   // WinCE does not provide I(PIE)HTMLWindow3, but we do not need it.
  79 #else
  80   // Returns the IHTMLWindow3 interface corresponding to the given site.
  81   // Can be used with our HtmlEventMonitor.
  82   static HRESULT GetHtmlWindow3(IUnknown *site,
  83                                 IHTMLWindow3 **window3);
  84 #endif
  85
  86   // Returns the IDispatch interface for the script engine at the given site.
  87   // TODO(zork): Remove dump_on_error.
  88   static HRESULT GetScriptDispatch(IUnknown *site,
  89                                    IDispatch **script_dispatch,
  90                                    bool dump_on_error = false);
  91
  92   // Returns the dispatch id of the named member.
  93   static HRESULT GetDispatchMemberId(IDispatch *dispatch, const WCHAR *name,
  94                                      DISPID *dispid) {
  95     *dispid = DISPID_UNKNOWN;
  96     return dispatch->GetIDsOfNames(IID_NULL, const_cast<WCHAR**>(&name), 1, 0,
  97                                    dispid);
  98   }
  99
 100   // Determine whether a variant is, ahem, null or undefined.
 101   static bool VariantIsNullOrUndefined(const VARIANT *var) {
 102     return var->vt == VT_NULL || var->vt == VT_EMPTY;
 103   }
 104
 105   // Determine whether an optional variant parameter was specified. Handles
 106   // unpassed params, as well as <undefined> and <null> valued params.
 107   // TODO(cprince): When JsParamFetcher is implemented for IE, move this
 108   // function there.
 109   static bool OptionalVariantIsPresent(const VARIANT *arg) {
 110     // If an optional variant was not passed, we get this
 111     // See: http://msdn2.microsoft.com/en-us/library/ms931135.aspx
 112     if (arg->vt == VT_ERROR && arg->scode == DISP_E_PARAMNOTFOUND) {
 113       return false;
 114     }
 115
 116     if (VariantIsNullOrUndefined(arg)) {
 117       return false;
 118     }
 119
 120     return true;
 121   }
 122
 123   // Returns the property value by name.
 124   // The caller is responsible for freeing the returned VARIANT.
 125   static HRESULT GetDispatchProperty(IDispatch *dispatch, const WCHAR *name,
 126                                      VARIANT *value) {
 127     DISPID dispid;
 128     HRESULT hr = GetDispatchMemberId(dispatch, name, &dispid);
 129     if (FAILED(hr)) return hr;
 130     return GetDispatchProperty(dispatch, dispid, value);
 131   }
 132
 133   // Returns the property value by dispid.
 134   // The caller is responsible for freeing the returned VARIANT.
 135   static HRESULT GetDispatchProperty(IDispatch *dispatch, DISPID dispid,
 136                                      VARIANT *value);
 137
 138   // Sets the property value by name.
 139   static HRESULT SetDispatchProperty(IDispatch *dispatch, const WCHAR *name,
 140                                      const VARIANT *value) {
 141     DISPID dispid;
 142     HRESULT hr = GetDispatchMemberId(dispatch, name, &dispid);
 143     if (FAILED(hr)) return hr;
 144     return SetDispatchProperty(dispatch, dispid, value);
 145   }
 146
 147   // Sets the property value by dispid.
 148   static HRESULT SetDispatchProperty(IDispatch *dispatch, DISPID dispid,
 149                                      const VARIANT *value);
 150
 151   // Adds a new property to object.
 152   // If the property already exists then it is returned.
 153   // Parameters:
 154   //  dispatch - in - the properties are added to this object
 155   //  name - in - the case sensitive name of the property
 156   //  dispid - out - the identifier for the property
 157   static HRESULT AddDispatchProperty(IDispatch* dispatch, const char16* name,
 158                                      DISPID* dispid);
 159
 160   // Convenience function for calling AddDispatchProperty
 161   // and then SetDispathProperty.
 162   static HRESULT AddAndSetDispatchProperty(IDispatch* dispatch,
 163                                            const char16* name,
 164                                            const VARIANT* value);
 165
 166 #ifdef WINCE
 167   // TODO(andreip): implement on Windows Mobile.
 168 #else
 169   // Returns the html attribute value of the given HTMLElement.
 170   // The caller is responsible for freeing the returned VARIANT.
 171   static HRESULT GetHTMLElementAttributeValue(IHTMLElement *element,
 172                                               const WCHAR *name,
 173                                               VARIANT *value);
 174 #endif
 175
 176   // Convert NULL BSTR to the empty string.
 177   static const CComBSTR kEmptyBSTR;
 178   static const BSTR SafeBSTR(const BSTR value) {
 179     return value ? value : kEmptyBSTR.m_str;
 180   }
 181   // Returns true if there the browser is in 'online' mode and the local
 182   // system is connected to a network.
 183   static bool IsOnline();
 184 };
 185
 186
 187 #endif  // GEARS_BASE_IE_ACTIVEX_UTILS_H__