include/systools/win32/comtools.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #pragma once
  21
  22 #include <string>
  23 #include <string_view>
  24 #include <stdexcept>
  25 #include <type_traits>
  26 #include <utility>
  27
  28 #include <prewin.h>
  29 #include <objbase.h>
  30 #include <postwin.h>
  31
  32 namespace sal::systools
  33 {
  34     /* Simple exception class for propagating COM errors */
  35     class ComError : public std::runtime_error
  36     {
  37     public:
  38         ComError(const std::string& message, HRESULT hr) :
  39             std::runtime_error(message),
  40             hr_(hr)
  41         {}
  42
  43         HRESULT GetHresult() const { return hr_; }
  44
  45     private:
  46         HRESULT hr_;
  47     };
  48
  49     /* Convert failed HRESULT to thrown ComError */
  50     inline void ThrowIfFailed(HRESULT hr, std::string_view msg)
  51     {
  52         if (FAILED(hr))
  53             throw ComError(std::string(msg), hr);
  54     }
  55
  56     /* A guard class to call CoInitializeEx/CoUninitialize in proper pairs
  57      * See also: o3tl::safeCoInitializeEx doing dangerous re-initialization
  58      */
  59     class CoInitializeGuard
  60     {
  61     public:
  62         enum class WhenFailed
  63         {
  64             NoThrow, // do not throw
  65             Throw, // throw on failure
  66             Abort, // std::abort on failure
  67         };
  68         explicit CoInitializeGuard(DWORD dwCoInit, bool failChangeMode = false,
  69                                    WhenFailed whenFailed = WhenFailed::Throw)
  70         {
  71             HRESULT hr = ::CoInitializeEx(nullptr, dwCoInit);
  72             if (whenFailed != WhenFailed::NoThrow && FAILED(hr)
  73                 && (failChangeMode || hr != RPC_E_CHANGED_MODE))
  74             {
  75                 if (whenFailed == WhenFailed::Throw)
  76                     throw ComError("CoInitializeEx failed", hr);
  77                 else // if (whenFailed == Abort)
  78                     std::abort();
  79             }
  80             mbUninit = SUCCEEDED(hr);
  81         }
  82         CoInitializeGuard(const CoInitializeGuard&) = delete; // non-construction-copyable
  83         void operator=(const CoInitializeGuard&) = delete; // non-copyable
  84         ~CoInitializeGuard()
  85         {
  86             if (mbUninit)
  87                 ::CoUninitialize();
  88         }
  89
  90     private:
  91         bool mbUninit;
  92     };
  93
  94     struct COM_QUERY_TAG {} constexpr COM_QUERY;
  95     struct COM_QUERY_THROW_TAG {} constexpr COM_QUERY_THROW;
  96     template <typename TAG>
  97     constexpr bool is_COM_query_tag
  98         = std::is_same_v<TAG, COM_QUERY_TAG> || std::is_same_v<TAG, COM_QUERY_THROW_TAG>;
  99
 100     /* A simple COM smart pointer template */
 101     template <typename T>
 102     class COMReference
 103     {
 104     public:
 105         /* Explicitly controllable whether AddRef will be called or not */
 106         COMReference(T* comptr = nullptr, bool bAddRef = true) :
 107             com_ptr_(comptr)
 108         {
 109             if (bAddRef)
 110                 addRef(com_ptr_);
 111         }
 112
 113         COMReference(const COMReference<T>& other) :
 114             COMReference(other.com_ptr_)
 115         {
 116         }
 117
 118         COMReference(COMReference<T>&& other) :
 119             COMReference(std::exchange(other.com_ptr_, nullptr), false)
 120         {
 121         }
 122
 123         // Query from IUnknown*, using COM_QUERY or COM_QUERY_THROW tags
 124         template <typename T2, typename TAG>
 125         COMReference(const COMReference<T2>& p, TAG t)
 126             : COMReference(p.template QueryInterface<T>(t))
 127         {
 128         }
 129
 130         // Using CoCreateInstance
 131         COMReference(REFCLSID clsid, IUnknown* pOuter = nullptr, DWORD nCtx = CLSCTX_ALL)
 132             : com_ptr_(nullptr)
 133         {
 134             ThrowIfFailed(CoCreateInstance(clsid, pOuter, nCtx), "CoCreateInstance failed");
 135         }
 136
 137         COMReference<T>& operator=(const COMReference<T>& other)
 138         {
 139             return operator=(other.com_ptr_);
 140         }
 141
 142         COMReference<T>& operator=(COMReference<T>&& other)
 143         {
 144             if (com_ptr_ != other.com_ptr_)
 145             {
 146                 clear();
 147                 std::swap(com_ptr_, other.com_ptr_);
 148             }
 149             return *this;
 150         }
 151
 152         COMReference<T>& operator=(T* comptr)
 153         {
 154             assign(comptr);
 155             return *this;
 156         }
 157
 158         ~COMReference() { release(com_ptr_); }
 159
 160         template <typename T2, typename TAG, std::enable_if_t<is_COM_query_tag<TAG>, int> = 0>
 161         COMReference<T2> QueryInterface(TAG) const
 162         {
 163             T2* ip = nullptr;
 164             HRESULT hr = E_POINTER;
 165             if (com_ptr_)
 166                 hr = com_ptr_->QueryInterface(&ip);
 167
 168             if constexpr (std::is_same_v<TAG, COM_QUERY_THROW_TAG>)
 169                 ThrowIfFailed(hr, "QueryInterface failed");
 170
 171             return { ip, false };
 172         }
 173
 174         template <typename T2, typename TAG>
 175         COMReference<T>& set(const COMReference<T2>& p, TAG t)
 176         {
 177             return operator=(p.template QueryInterface<T>(t));
 178         }
 179
 180         HRESULT CoCreateInstance(REFCLSID clsid, IUnknown* pOuter = nullptr,
 181                                  DWORD nCtx = CLSCTX_ALL)
 182         {
 183             T* ip;
 184             HRESULT hr = ::CoCreateInstance(clsid, pOuter, nCtx, IID_PPV_ARGS(&ip));
 185             if (SUCCEEDED(hr))
 186                 release(std::exchange(com_ptr_, ip));
 187             return hr;
 188         }
 189
 190         HRESULT CoGetClassObject(REFCLSID clsid, DWORD nCtx = CLSCTX_ALL)
 191         {
 192             T* ip;
 193             HRESULT hr = ::CoGetClassObject(clsid, nCtx, nullptr, IID_PPV_ARGS(&ip));
 194             if (SUCCEEDED(hr))
 195                 release(std::exchange(com_ptr_, ip));
 196             return hr;
 197         }
 198
 199         T* operator->() const { return com_ptr_; }
 200
 201         T& operator*() const { return *com_ptr_; }
 202
 203         /* Necessary for assigning com_ptr_ from functions like
 204            CoCreateInstance which require a 'void**' */
 205         T** operator&()
 206         {
 207             clear();
 208             return &com_ptr_;
 209         }
 210
 211         T* get() const { return com_ptr_; }
 212         operator T* () const { return get(); }
 213
 214         void clear() { assign(nullptr); }
 215
 216         bool is() const { return (com_ptr_ != nullptr); }
 217         operator bool() const { return is(); }
 218
 219     private:
 220         static void addRef(T* ptr)
 221         {
 222             if (ptr)
 223                 ptr->AddRef();
 224         }
 225
 226         static void release(T* ptr)
 227         {
 228             if (ptr)
 229                 ptr->Release();
 230         }
 231
 232         void assign(T* ptr)
 233         {
 234             if (com_ptr_ == ptr)
 235                 return;
 236             addRef(ptr);
 237             release(std::exchange(com_ptr_, ptr));
 238         }
 239
 240         T* com_ptr_;
 241     };
 242
 243     // A class to use with functions taking an out pointer argument,
 244     // that needs to be freed with CoTaskMemFree - like SHGetKnownFolderPath
 245     template <typename T> class CoTaskMemAllocated
 246     {
 247     public:
 248         ~CoTaskMemAllocated() { CoTaskMemFree(m_pv); }
 249
 250         T** operator&()
 251         {
 252             CoTaskMemFree(std::exchange(m_pv, nullptr));
 253             return &m_pv;
 254         };
 255
 256         operator T*() { return m_pv; }
 257
 258     private:
 259         T* m_pv = nullptr;
 260     };
 261
 262 } // sal::systools
 263
 264 /* Typedefs for some popular COM interfaces */
 265 typedef sal::systools::COMReference<IDataObject> IDataObjectPtr;
 266
 267 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */