Issues #1163, #1173 - refactor CPluginUserSettings

src/plugin/PluginUserSettings.cpp

+/*
+ * This file is part of Adblock Plus <https://adblockplus.org/>,
+ * Copyright (C) 2006-2015 Eyeo GmbH
+ *
+ * Adblock Plus is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 3 as
+ * published by the Free Software Foundation.
+ *
+ * Adblock Plus is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Adblock Plus.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 #include "PluginStdAfx.h"
 #include "PluginUserSettings.h"
 #include <algorithm>
 #include "PluginSettings.h"
 #include "PluginClient.h"
 #include "../shared/Dictionary.h"
 #include <unordered_map>
 
 namespace
 {
   enum UserSettingsMethods
   {
     dispatchID_GetMessage = 0,
     dispatchID_GetLanguageCount,
     dispatchID_GetLanguageByIndex,
     dispatchID_GetLanguageTitleByIndex,
     dispatchID_SetLanguage,
     dispatchID_GetLanguage,
     dispatchID_GetWhitelistDomains,
     dispatchID_AddWhitelistDomain,
     dispatchID_RemoveWhitelistDomain,
     dispatchID_GetAppLocale,
     dispatchID_GetDocumentationLink,
     dispatchID_IsAcceptableAdsEnabled,
-    dispatchID_SetAcceptableAdsEnabled
+    dispatchID_SetAcceptableAdsEnabled,
+    dispatchID_IsUpdate,
   };
 
+  /**
+   * Auxiliary for static initialization
+   */
   std::unordered_map<std::wstring, DISPID> InitMethodIndex()
   {
     std::unordered_map<std::wstring, DISPID> m;
     // try-block for safety during static initialization
     try
     {
       m.emplace(L"GetMessage", dispatchID_GetMessage);

[Oleksandr, 2014/08/17 22:52:01]

It's outside the scope of this review, but since we are already re-factoring
this, I wouldn't mind to get rid of that really long Invoke method below. I am
thinking of something like this

typedef (HRESULT JavaScriptMethodInvoke)(DISPPARAMS* pDispparams, VARIANT*
pVarResult, EXCEPINFO* pExcepinfo, UINT* pArgErr)

std::unordered_map<DISPID, JavaScriptMethodInvoke> m_methods;

Then for each DISPID we could have a separate method, and all Invoke would do
would just call something like:
return m_methods[dispidMember]->second(pDispparams, pVarResult, pExcepinfo,
pArgErr)

Shall we put this into our issues list?

[Eric, 2014/09/29 18:45:41]

Discussion points.
1. I wouldn't mind breaking up the Invoke code so that the central functionality
of each method is implemented in its own function.
2. I would prefer to centralize all the type conversion and validation functions
here so that the individual functions have interfaces with natural C++ types and
not the Microsoft API conventions.
2a. For example, only some of the functions need to return a result. Defining
'pVarResult' as an argument for such functions loses the opportunity for the
function signature to signify what it does.
It would be a low priority issue in every case I can think of. I don't see a
need to plan to rewrite it yet.

[Oleksandr, 2014/10/02 20:36:53]

Creating a low priority issue in our issue tracker would enable developers from
outside the team to just go and do it, if the feel like it. 

On 2014/09/29 18:45:41, Eric wrote:

[Eric, 2014/10/14 22:23:50]

I wrote an issue for the slightly larger task of cleaning up the Invoke
implementations generally. See https://issues.adblockplus.org/ticket/1163 The
subtask of breaking out each dispatch ID to its own function is in there. Let me
know if this is sufficient.

       m.emplace(L"GetLanguageCount", dispatchID_GetLanguageCount);
       m.emplace(L"GetLanguageByIndex", dispatchID_GetLanguageByIndex);
       m.emplace(L"GetLanguageTitleByIndex", dispatchID_GetLanguageTitleByIndex);
       m.emplace(L"SetLanguage", dispatchID_SetLanguage);
       m.emplace(L"GetLanguage", dispatchID_GetLanguage);
       m.emplace(L"GetWhitelistDomains", dispatchID_GetWhitelistDomains);
       m.emplace(L"AddWhitelistDomain", dispatchID_AddWhitelistDomain);
       m.emplace(L"RemoveWhitelistDomain", dispatchID_RemoveWhitelistDomain);
       m.emplace(L"GetAppLocale", dispatchID_GetAppLocale);
       m.emplace(L"GetDocumentationLink", dispatchID_GetDocumentationLink);
       m.emplace(L"IsAcceptableAdsEnabled", dispatchID_IsAcceptableAdsEnabled);
       m.emplace(L"SetAcceptableAdsEnabled", dispatchID_SetAcceptableAdsEnabled);
+      m.emplace(L"IsUpdate", dispatchID_IsUpdate);
     }
     catch(...)
     {
     }
     return m;
   }
 
+  /**
+   * Static map from method names to dispatch identifiers.
+   */
   std::unordered_map<std::wstring, DISPID> methodIndex = InitMethodIndex();
 }
 
+// ENTRY POINT
 STDMETHODIMP CPluginUserSettings::QueryInterface(REFIID riid, void **ppvObj)
 {
-  // Entry point, but no exception handler; nothing here can throw

[Oleksandr, 2014/08/17 22:52:01]

This comment and all the others concerning the exception safety are useful in
this review, but would be weird to have in the actual code, IMHO.

[Eric, 2014/09/29 18:45:41]

I would like to have some kind of documentation in the code that identifies each
of the entry points in some way that can be searched with a regular expression.
This is to allow code audit for issue #1173.

It's a separate issue (for me) whether those comments persist in the code after
#1173 is done. Personally, I'd leave them there because they have non-ordinary
interactions with the external world. I'd prefer an in-language specification
but that's not available, so I'll settle for a comment. (Note: C++11 generalized
attributes could work, but they are not supported even in VS 2013.)

I'm open with how to write such comments.

Also, I'm also open to putting in a try-catch statement even though nothing can
throw. That would remove the need for the second half of the comment.

[Oleksandr, 2014/10/02 20:36:53]

In that case, it would seem less intrusive to have these comments right before
the method declaration, IMHO.
 
On 2014/09/29 18:45:41, Eric wrote:

   if (!ppvObj)
   {
     return E_POINTER;
   }
   if (riid == IID_IUnknown || riid == IID_IDispatch) // GUID comparison does not throw
   {
-    *ppvObj = static_cast<void *>(this);
+    *ppvObj = static_cast<void*>(this);
     return S_OK;
   }
   return E_NOINTERFACE;
 }
 
 /**
  * \par Limitation
  *   CPluginUserSettings is not allocated on the heap.
  *   It appears only as a member variable in CPluginTabBase.
  *   'AddRef' and 'Release' don't need reference counting because they don't present COM factories.
@@ skipping 18 matching lines @@
   return E_NOTIMPL;
 }
 
 /**
  * \par Limitation
  *   The specification for this method in IDispatch maps an array of names to an array of identifiers.
  *   This version only supports single-element arrays, which is enough for IE's JavaScript interpreter.
  */
 STDMETHODIMP CPluginUserSettings::GetIDsOfNames(REFIID, LPOLESTR* name, UINT count, LCID, DISPID* id)
 {
-  // Entry point exception handler
   try
   {
     if (!name || !id)
     {
       return E_POINTER;
     }
     if (count != 1)
     {
       return E_FAIL;
     }
     auto item = methodIndex.find(*name); // unordered_map::find is not declared noexcept
-    if (item==methodIndex.end())
+    if (item == methodIndex.end())
     {
       return DISP_E_UNKNOWNNAME;
     }
     *id = item->second;
   }
-  catch(...)
+  catch (...)
   {
     return E_FAIL;
   }
   return S_OK;
 }
 
 CStringW sGetMessage(const CString& section, const CString& key)
 {
   Dictionary* dictionary = Dictionary::GetInstance();
   return CStringW(dictionary->Lookup(std::string(CW2A(section)), std::string(CW2A(key))).c_str());
 }
 
 STDMETHODIMP CPluginUserSettings::Invoke(DISPID dispidMember, REFIID riid, LCID lcid, WORD wFlags, DISPPARAMS* pDispparams, VARIANT* pVarResult,
                                          EXCEPINFO* pExcepinfo, UINT* pArgErr)
 {
-  // Entry point exception handler
   try
   {
-    if (!pDispparams || !pExcepinfo)
+    if (!pDispparams)
     {
       return E_POINTER;
     }
     if (pDispparams->cNamedArgs != 0)
     {
       return DISP_E_NONAMEDARGS;
     }
-
     CPluginSettings* settings = CPluginSettings::GetInstance();
-
     switch (dispidMember)
     {
     case dispatchID_GetMessage:
       {
-        if (2 != pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
-        if (VT_BSTR != pDispparams->rgvarg[0].vt)
-          return DISP_E_TYPEMISMATCH;
-        if (VT_BSTR != pDispparams->rgvarg[1].vt)
-          return DISP_E_TYPEMISMATCH;
-
+        if (pDispparams->cArgs != 2)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
+        if (pDispparams->rgvarg[0].vt != VT_BSTR || pDispparams->rgvarg[1].vt != VT_BSTR)
+        {
+          return DISP_E_TYPEMISMATCH;
+        }
         if (pVarResult)
         {
           CComBSTR key = pDispparams->rgvarg[0].bstrVal;
           CComBSTR section = pDispparams->rgvarg[1].bstrVal;
           CStringW message = sGetMessage((BSTR)section, (BSTR)key);
 
           pVarResult->vt = VT_BSTR;
           pVarResult->bstrVal = SysAllocString(message);
         }
       }
       break;
     case dispatchID_GetLanguageCount:
       {
-        if (pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
+        if (pDispparams->cArgs != 0)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
         if (pVarResult)
         {
           std::map<CString, CString> languageList = settings->GetFilterLanguageTitleList();
 
           pVarResult->vt = VT_I4;
           pVarResult->lVal = static_cast<LONG>(languageList.size());
         }
       }
       break;
     case dispatchID_GetLanguageByIndex:
       {
-        if (1 != pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
-        if (VT_I4 != pDispparams->rgvarg[0].vt)
-          return DISP_E_TYPEMISMATCH;
-
-        if (pVarResult)
-        {
-          int indx = pDispparams->rgvarg[0].lVal;
+        if (pDispparams->cArgs != 1)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
+        if (pDispparams->rgvarg[0].vt != VT_I4)
+        {
+          return DISP_E_TYPEMISMATCH;
+        }
+        if (pVarResult)
+        {
+          int index = pDispparams->rgvarg[0].lVal;
 
           std::map<CString, CString> languageTitleList = settings->GetFilterLanguageTitleList();
 
-          if (indx < 0  ||  indx >= (int)languageTitleList.size())
+          if (index < 0  ||  index >= static_cast<int>(languageTitleList.size()))
             return DISP_E_EXCEPTION;
 
           CString language;
 
-          int curIndx = 0;
-          for(std::map<CString, CString>::const_iterator it = languageTitleList.begin(); it != languageTitleList.end(); ++it)
+          int loopIndex = 0;
+          for (std::map<CString, CString>::const_iterator it = languageTitleList.begin(); it != languageTitleList.end(); ++it)
           {
-            if (curIndx == indx)
+            if (loopIndex == index)
             {
               language = it->first;
               break;
             }
-
-            curIndx++;
+            ++loopIndex;
           }
 
           pVarResult->vt = VT_BSTR;
           pVarResult->bstrVal = SysAllocString(language);
         }
       }
       break;
     case dispatchID_GetLanguageTitleByIndex:
       {
-        if (1 != pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
-        if (VT_I4 != pDispparams->rgvarg[0].vt)
-          return DISP_E_TYPEMISMATCH;
-
-        if (pVarResult)
-        {
-          int indx = pDispparams->rgvarg[0].lVal;
+        if (pDispparams->cArgs != 1)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
+        if (pDispparams->rgvarg[0].vt != VT_I4)
+        {
+          return DISP_E_TYPEMISMATCH;
+        }
+        if (pVarResult)
+        {
+          int index = pDispparams->rgvarg[0].lVal;
 
           std::map<CString, CString> languageTitleList = settings->GetFilterLanguageTitleList();
 
-          if (indx < 0  ||  indx >= (int)languageTitleList.size())
+          if (index < 0  ||  index >= static_cast<int>(languageTitleList.size()))
             return DISP_E_EXCEPTION;
 
           CString languageTitle;
 
-          int curIndx = 0;
-          for(std::map<CString, CString>::const_iterator it = languageTitleList.begin(); it != languageTitleList.end(); ++it)
+          int loopIndex = 0;
+          for (std::map<CString, CString>::const_iterator it = languageTitleList.begin(); it != languageTitleList.end(); ++it)
           {
-            if (curIndx == indx)
+            if (loopIndex == index)
             {
               languageTitle = it->second;
               break;
             }
-
-            curIndx++;
+            loopIndex++;
           }
 
           pVarResult->vt = VT_BSTR;
           pVarResult->bstrVal = SysAllocString(languageTitle);
         }
       }
       break;
     case dispatchID_SetLanguage:
       {
-        if (1 != pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
-        if (VT_BSTR != pDispparams->rgvarg[0].vt)
-          return DISP_E_TYPEMISMATCH;
-
+        if (pDispparams->cArgs != 1)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
+        if (pDispparams->rgvarg[0].vt != VT_BSTR)
+        {
+          return DISP_E_TYPEMISMATCH;
+        }
         CComBSTR url = pDispparams->rgvarg[0].bstrVal;
-
         settings->SetSubscription((BSTR)url);
       }
       break;
     case dispatchID_GetLanguage:
       {
-        if (pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
+        if (pDispparams->cArgs != 0)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
         if (pVarResult)
         {
           CString url = settings->GetSubscription();
-
           pVarResult->vt = VT_BSTR;
           pVarResult->bstrVal = SysAllocString(url);
         }
       }
       break;
     case dispatchID_GetWhitelistDomains:
       {
-        if (pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
+        if (pDispparams->cArgs != 0)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
         if (pVarResult)
         {
           std::vector<std::wstring> whiteList = settings->GetWhiteListedDomainList();
           CString sWhiteList;
           for (size_t i = 0; i < whiteList.size(); i++)
           {
             if (!sWhiteList.IsEmpty())
             {
               sWhiteList += ',';
             }
             sWhiteList += CString(whiteList[i].c_str());
           }
-
           pVarResult->vt = VT_BSTR;
           pVarResult->bstrVal = SysAllocString(sWhiteList);
         }
       }
       break;
     case dispatchID_AddWhitelistDomain:
       {
-        if (1 != pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
-        if (VT_BSTR != pDispparams->rgvarg[0].vt)
-          return DISP_E_TYPEMISMATCH;
-
+        if (pDispparams->cArgs != 1)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
+        if (pDispparams->rgvarg[0].vt != VT_BSTR)
+        {
+          return DISP_E_TYPEMISMATCH;
+        }
         CComBSTR domain = pDispparams->rgvarg[0].bstrVal;
         if (domain.Length())
         {
           settings->AddWhiteListedDomain((BSTR)domain);
         }
       }
       break;
     case dispatchID_RemoveWhitelistDomain:
       {
-        if (1 != pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
-        if (VT_BSTR != pDispparams->rgvarg[0].vt)
-          return DISP_E_TYPEMISMATCH;
-
+        if (pDispparams->cArgs != 1)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
+        if (pDispparams->rgvarg[0].vt != VT_BSTR)
+        {
+          return DISP_E_TYPEMISMATCH;
+        }
         CComBSTR domain = pDispparams->rgvarg[0].bstrVal;
         if (domain.Length())
         {
           settings->RemoveWhiteListedDomain((BSTR)domain);
         }
       }
       break;
     case dispatchID_GetAppLocale:
       {
-        if (0 != pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
-        pVarResult->vt = VT_BSTR;
-        pVarResult->bstrVal = SysAllocString(settings->GetAppLocale());
+        if (pDispparams->cArgs != 0)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
+        if (pVarResult)
+        {
+          pVarResult->vt = VT_BSTR;
+          pVarResult->bstrVal = SysAllocString(settings->GetAppLocale());
+        }
       }
       break;
     case dispatchID_GetDocumentationLink:
       {
-        if (0 != pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
-        pVarResult->vt = VT_BSTR;
-        pVarResult->bstrVal = SysAllocString(settings->GetDocumentationLink());
+        if (pDispparams->cArgs != 0)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
+        if (pVarResult)
+        {
+          pVarResult->vt = VT_BSTR;
+          pVarResult->bstrVal = SysAllocString(settings->GetDocumentationLink());
+        }
       }
       break;
     case dispatchID_IsAcceptableAdsEnabled:
       {
-        if (0 != pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
-        pVarResult->vt = VT_BOOL;
-        pVarResult->boolVal = CPluginClient::GetInstance()->IsAcceptableAdsEnabled();
+        if (pDispparams->cArgs != 0)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
+        if (pVarResult)
+        {
+          pVarResult->vt = VT_BOOL;
+          pVarResult->boolVal = CPluginClient::GetInstance()->IsAcceptableAdsEnabled() ? VARIANT_TRUE : VARIANT_FALSE;
+        }
       }
       break;
     case dispatchID_SetAcceptableAdsEnabled:
       {
-        if (1 != pDispparams->cArgs)
-          return DISP_E_BADPARAMCOUNT;
-
-        if (VT_BOOL != pDispparams->rgvarg[0].vt)
-          return DISP_E_TYPEMISMATCH;
-
-        bool enable = pDispparams->rgvarg[0].boolVal;
-
-        if (enable)
+        if (pDispparams->cArgs != 1)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
+        if (pDispparams->rgvarg[0].vt != VT_BOOL)
+        {
+          return DISP_E_TYPEMISMATCH;
+        }
+        if (pDispparams->rgvarg[0].boolVal != VARIANT_FALSE)
         {
           CPluginClient* client = CPluginClient::GetInstance();
           client->AddSubscription(client->GetPref(L"subscriptions_exceptionsurl", L""));
         }
         else
         {
           CPluginClient* client = CPluginClient::GetInstance();
           client->RemoveSubscription(client->GetPref(L"subscriptions_exceptionsurl", L""));
         }
       }
       break;
+    case dispatchID_IsUpdate:
+      {
+        if (pDispparams->cArgs != 0)
+        {
+          return DISP_E_BADPARAMCOUNT;
+        }
+        if (pVarResult)
+        {
+          pVarResult->vt = VT_BOOL;
+          pVarResult->boolVal = CPluginClient::GetInstance()->GetPref(L"displayUpdatePage", false) ? VARIANT_TRUE : VARIANT_FALSE;
+        }
+      }
+      break;
     default:
       return DISP_E_MEMBERNOTFOUND;
       break;
     }
   }
-  catch(...)
+  catch (...)
   {
     return E_FAIL;
   }
   return S_OK;
 }
-