Version
menu_open
Wwise SDK 2021.1.14
AkMMDevice.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Version: v2021.1.14 Build: 6590
25  Copyright (c) 2006-2023 Audiokinetic Inc.
26 *******************************************************************************/
27 
28 // AkMMDevice.h -- C++ RIAA object wrappers for Win32 MMDevice enumeration APIs
29 
30 #pragma once
31 
32 #include <AK/SoundEngine/Common/AkSoundEngine.h>
33 #include <AK/Tools/Common/AkPlatformFuncs.h>
34 #include <mmdeviceapi.h>
35 
36 namespace AK
37 {
38  namespace Win32
39  {
40  class DeviceProperty
41  {
42  public:
43  // Default constructor
44  DeviceProperty()
45  {
46  PropVariantInit(&variant);
47  }
48 
49  // Construct a property from an existing property store
50  DeviceProperty(const PROPERTYKEY &key, IPropertyStore* in_pProps)
51  {
52  PropVariantInit(&variant);
53  if (in_pProps) in_pProps->GetValue(key, &variant);
54  }
55 
56  // Move constructor
57  DeviceProperty(DeviceProperty&& other)
58  {
59  variant = other.variant;
60  PropVariantInit(&other.variant);
61  }
62 
63  // Copy construction is not allowed
64  DeviceProperty(const DeviceProperty& other) = delete;
65 
66  // Destructor
67  ~DeviceProperty()
68  {
69  PropVariantClear(&variant);
70  }
71 
72  // Move assignment
73  DeviceProperty& operator=(DeviceProperty&& other)
74  {
75  PropVariantClear(&variant);
76  variant = other.variant;
77  PropVariantInit(&other.variant);
78  return *this;
79  }
80 
81  // Copy assignment is not allowed
82  DeviceProperty& operator=(const DeviceProperty& other) = delete;
83 
84  bool IsEmpty() const { return variant.vt == VT_EMPTY; }
85 
86  PROPVARIANT variant;
87  };
88 
89  class DeviceProperties
90  {
91  public:
92  // Default constructor
93  DeviceProperties()
94  : pProps(nullptr)
95  {
96  }
97 
98  // Construct properties from an IMMDevice
99  DeviceProperties(IMMDevice* in_pDevice)
100  {
101  in_pDevice->OpenPropertyStore(STGM_READ, &pProps);
102  }
103 
104  // Move constructor
105  DeviceProperties(DeviceProperties&& other)
106  {
107  pProps = other.pProps;
108  other.pProps = nullptr;
109  }
110 
111  // Copy construction is not allowed
112  DeviceProperties(const DeviceProperties& other) = delete;
113 
114  // Destructor
115  ~DeviceProperties()
116  {
117  if (pProps)
118  {
119  pProps->Release();
120  pProps = nullptr;
121  }
122  }
123 
124  // Move assignment
125  DeviceProperties& operator=(DeviceProperties&& other)
126  {
127  if (pProps)
128  pProps->Release();
129  pProps = other.pProps;
130  other.pProps = nullptr;
131  return *this;
132  }
133 
134  // Copy assignment is not allowed
135  DeviceProperties& operator=(const DeviceProperties& other) = delete;
136 
137  bool IsValid() { return pProps != nullptr; }
138 
139  DeviceProperty GetProperty(const PROPERTYKEY& key)
140  {
141  return DeviceProperty(key, pProps);
142  }
143 
144  IPropertyStore* pProps;
145  };
146  class Device
147  {
148  public:
149  // Default constructor
150  Device()
151  : pDevice(nullptr)
152  , idDevice(AK_INVALID_DEVICE_ID)
153  {
154  }
155 
156  // Move constructor
157  Device(Device&& other)
158  : pDevice(nullptr)
159  {
160  SetDevice(other.pDevice);
161  other.pDevice = nullptr;
162  }
163 
164  Device(const Device& other)
165  : pDevice(nullptr)
166  {
167  *this = other;
168  }
169 
170  // Destructor
171  ~Device()
172  {
173  if (pDevice)
174  {
175  pDevice->Release();
176  pDevice = nullptr;
177  }
178  }
179 
180  // Move assignment
181  Device& operator=(Device&& other)
182  {
183  if (pDevice)
184  {
185  pDevice->Release();
186  pDevice = nullptr; // Do not remove, protects against this == &other
187  }
188  pDevice = other.pDevice;
189  idDevice = other.idDevice;
190  other.pDevice = nullptr;
191  return *this;
192  }
193 
194  Device& operator=(const Device& other)
195  {
196  if (pDevice)
197  {
198  pDevice->Release();
199  pDevice = nullptr; // Do not remove, protects against this == &other
200  }
201  pDevice = other.pDevice;
202  if (pDevice)
203  pDevice->AddRef();
204  idDevice = other.idDevice;
205  return *this;
206  }
207 
208  Device& operator=(IMMDevice* pOther)
209  {
210  SetDevice(pOther);
211  if (pDevice)
212  pDevice->AddRef();
213  return *this;
214  }
215 
216  bool IsValid() const { return pDevice != nullptr; }
217 
218  AkUInt32 GetDeviceID() const
219  {
220  return pDevice ? idDevice : AK_INVALID_DEVICE_ID;
221  }
222 
223  DeviceProperties GetProperties() const
224  {
225  return DeviceProperties(pDevice);
226  }
227 
228  void ComputeId()
229  {
230  idDevice = AK_INVALID_DEVICE_ID;
231  if (pDevice)
232  {
233  //Inlined version of GetDeviceID.
234  LPWSTR pwszID = NULL;
235  if (pDevice->GetId(&pwszID) == S_OK)
236  {
237  char szString[260];
238  AKPLATFORM::AkWideCharToChar(pwszID, 260 - 1, szString);
239  szString[260 - 1] = 0;
240 
241  idDevice = FNVHash32::ComputeLowerCase((const char*)szString);
242  CoTaskMemFree(pwszID);
243  }
244  }
245  }
246 
247  void SetDevice(IMMDevice* in_pNew)
248  {
249  if (pDevice)
250  pDevice->Release();
251  pDevice = in_pNew;
252  ComputeId();
253  }
254 
255  interface IMMDevice* pDevice;
256  AkUInt32 idDevice;
257  };
258  class DeviceCollection
259  {
260  public:
261  class Iterator
262  {
263  public:
264  Iterator(IMMDeviceCollection* in_pDevices, UINT in_i)
265  : pDevices(in_pDevices)
266  , i(in_i)
267  {
268  }
269 
270  /// + operator</span>
271  Iterator operator+(AkUInt32 inc) const
272  {
273  Iterator returnedIt(pDevices, i + inc);
274  return returnedIt;
275  }
276 
277  /// - operator</span>
278  AkUInt32 operator-(Iterator const& rhs) const
279  {
280  return (AkUInt32)(i - rhs.i);
281  }
282 
283  /// ++ operator</span>
284  Iterator& operator++()
285  {
286  ++i;
287  return *this;
288  }
289 
290  /// -- operator</span>
291  Iterator& operator--()
292  {
293  --i;
294  return *this;
295  }
296 
297  /// == operator</span>
298  bool operator ==(const Iterator& in_rOp) const
299  {
300  return (pDevices == in_rOp.pDevices && i == in_rOp.i);
301  }
302 
303  /// != operator</span>
304  bool operator !=(const Iterator& in_rOp) const
305  {
306  return (pDevices != in_rOp.pDevices || i != in_rOp.i);
307  }
308 
309  Device GetDevice()
310  {
311  Device pDevice;
312  pDevices->Item(i, (IMMDevice**)&pDevice.pDevice); //Transfer the ref
313  if (pDevice.pDevice)
314  pDevice.ComputeId();
315  return pDevice;
316  }
317 
318  interface IMMDeviceCollection* pDevices; //Keep first.
319  UINT i;
320  };
321 
322  DeviceCollection(IMMDeviceEnumerator* pEnumerator)
323  : pDevices(nullptr)
324  , uCount(0)
325  {
326  pEnumerator->EnumAudioEndpoints(eRender, DEVICE_STATEMASK_ALL, &pDevices);
327  if (pDevices)
328  pDevices->GetCount(&uCount);
329  }
330  DeviceCollection(IMMDeviceEnumerator* pEnumerator, EDataFlow eFlow, DWORD dwStateMask)
331  : pDevices(nullptr)
332  , uCount(0)
333  {
334 
335  pEnumerator->EnumAudioEndpoints(eFlow, dwStateMask, &pDevices);
336  if (pDevices)
337  pDevices->GetCount(&uCount);
338  }
339 
340  // Move constructor
341  DeviceCollection(DeviceCollection&& other)
342  {
343  pDevices = other.pDevices;
344  uCount = other.uCount;
345  other.pDevices = nullptr;
346  other.uCount = 0;
347  }
348 
349  // Copy construction is not allowed
350  DeviceCollection(const DeviceCollection& other) = delete;
351 
352  // Destructor
353  ~DeviceCollection()
354  {
355  if (pDevices)
356  {
357  pDevices->Release();
358  pDevices = nullptr;
359  }
360  }
361 
362  // Move assignment
363  DeviceCollection& operator=(DeviceCollection&& other)
364  {
365  if (pDevices)
366  {
367  pDevices->Release();
368  }
369  pDevices = other.pDevices;
370  uCount = other.uCount;
371  other.pDevices = nullptr;
372  other.uCount = 0;
373  return *this;
374  }
375 
376  // Copy assignment is not allowed
377  DeviceCollection& operator=(const DeviceCollection& other) = delete;
378 
379  bool IsValid() const { return pDevices != nullptr; }
380 
381  UINT Count() const
382  {
383  return uCount;
384  }
385 
386  Iterator Begin()
387  {
388  Iterator it(pDevices, 0);
389  return it;
390  }
391  Iterator End()
392  {
393  Iterator it(pDevices, uCount);
394  return it;
395  }
396 
397  interface IMMDeviceCollection* pDevices;
398  UINT uCount;
399  };
400 
401  class DeviceEnumerator
402  {
403  public:
404 
405  DeviceEnumerator()
406  : pEnumerator(nullptr)
407  {
408  CoCreateInstance(
409  __uuidof(MMDeviceEnumerator), NULL,
410  CLSCTX_ALL, __uuidof(IMMDeviceEnumerator),
411  (void**)&pEnumerator);
412  }
413 
414  // Move constructor
415  DeviceEnumerator(DeviceEnumerator&& other)
416  {
417  pEnumerator = other.pEnumerator;
418  other.pEnumerator = nullptr;
419  }
420 
421  // Copy construction is not allowed
422  DeviceEnumerator(const DeviceEnumerator& other) = delete;
423 
424  // Destructor
425  ~DeviceEnumerator()
426  {
427  if (pEnumerator)
428  {
429  pEnumerator->Release();
430  pEnumerator = nullptr;
431  }
432  }
433 
434  // Move assignment
435  DeviceEnumerator& operator=(DeviceEnumerator&& other)
436  {
437  if (pEnumerator)
438  {
439  pEnumerator->Release();
440  }
441  pEnumerator = other.pEnumerator;
442  other.pEnumerator = nullptr;
443  return *this;
444  }
445 
446  // Copy assignment is not allowed
447  DeviceEnumerator& operator=(const DeviceEnumerator& other) = delete;
448 
449  bool IsValid() { return pEnumerator != nullptr; }
450 
451  Device GetDefaultDevice(ERole in_eRole)
452  {
453  Device pDevice;
454  pEnumerator->GetDefaultAudioEndpoint(eRender, in_eRole, (IMMDevice**)&pDevice.pDevice); //Transfer the ref
455  if (pDevice.pDevice)
456  pDevice.ComputeId();
457  return pDevice;
458  }
459 
460  interface IMMDeviceEnumerator* pEnumerator;
461  };
462 
463  /// Interface to access the IMMDevice cache. This avoids driver accesses.
464  class IAkDeviceEnumerator
465  {
466  public:
467  virtual AkUInt32 Count() = 0; ///Returns the number of devices. This function can block.
468  virtual Device Item(AkUInt32 in_idx) = 0; ///Gets item in_idx from the cache. Must be smaller than Count(). This function can block.
469  virtual void Lock() = 0; /// For thread safety. If you iterate through all the devices, lock the enumerator to avoid changes. However, if only accessing one single item, Item() is thread safe in itself.
470  virtual void Unlock() = 0; /// For thread safety. See \ref Lock()
471  virtual Device FindDevice(AkUInt32 in_id) = 0; ///Find a device that has this unique ID. The Id is one returned by AK::GetDeviceID.
472  };
473  }
474 };
AK::Win32::Device::idDevice
AkUInt32 idDevice
Definition: AkMMDevice.h:256
AK::Win32::Device::GetDeviceID
AkUInt32 GetDeviceID() const
Definition: AkMMDevice.h:218
AK
Audiokinetic namespace.
Definition: AkWwiseSDKVersion.cs:32
AK::Win32::IAkDeviceEnumerator::Item
virtual Device Item(AkUInt32 in_idx)=0
Returns the number of devices. This function can block.
AK::Win32::DeviceProperty::DeviceProperty
DeviceProperty(const PROPERTYKEY &key, IPropertyStore *in_pProps)
Definition: AkMMDevice.h:50
AK::Win32::DeviceCollection::DeviceCollection
DeviceCollection(IMMDeviceEnumerator *pEnumerator, EDataFlow eFlow, DWORD dwStateMask)
Definition: AkMMDevice.h:330
AK::Win32::DeviceProperties::DeviceProperties
DeviceProperties(const DeviceProperties &other)=delete
AK::Win32::DeviceEnumerator::operator=
DeviceEnumerator & operator=(const DeviceEnumerator &other)=delete
AK::Win32::DeviceCollection::Iterator::Iterator
Iterator(IMMDeviceCollection *in_pDevices, UINT in_i)
Definition: AkMMDevice.h:264
AK::Win32::Device::SetDevice
void SetDevice(IMMDevice *in_pNew)
Definition: AkMMDevice.h:247
AK::Win32::DeviceProperties::GetProperty
DeviceProperty GetProperty(const PROPERTYKEY &key)
Definition: AkMMDevice.h:139
AK::Win32::IAkDeviceEnumerator::Lock
virtual void Lock()=0
Gets item in_idx from the cache. Must be smaller than Count(). This function can block.
AK::Win32::Device::operator=
Device & operator=(const Device &other)
Definition: AkMMDevice.h:194
AK::Win32::DeviceProperties::operator=
DeviceProperties & operator=(DeviceProperties &&other)
Definition: AkMMDevice.h:125
AK_INVALID_DEVICE_ID
static const AkDeviceID AK_INVALID_DEVICE_ID
Invalid streaming device ID.
Definition: AkTypes.h:110
AK::Win32::DeviceCollection::DeviceCollection
DeviceCollection(const DeviceCollection &other)=delete
AK::Win32::Device::GetProperties
DeviceProperties GetProperties() const
Definition: AkMMDevice.h:223
AK::Win32::DeviceCollection::Count
UINT Count() const
Definition: AkMMDevice.h:381
AK::Win32::Device::pDevice
interface IMMDevice * pDevice
Definition: AkMMDevice.h:255
AK::Win32::DeviceCollection::IsValid
bool IsValid() const
Definition: AkMMDevice.h:379
NULL
#define NULL
Definition: AkTypes.h:47
AK::Win32::Device::Device
Device(const Device &other)
Definition: AkMMDevice.h:164
AK::Win32::DeviceCollection::operator=
DeviceCollection & operator=(DeviceCollection &&other)
Definition: AkMMDevice.h:363
AK::Win32::DeviceCollection::DeviceCollection
DeviceCollection(DeviceCollection &&other)
Definition: AkMMDevice.h:341
AK::Win32::Device::ComputeId
void ComputeId()
Definition: AkMMDevice.h:228
AK::Win32::DeviceProperties::operator=
DeviceProperties & operator=(const DeviceProperties &other)=delete
AK::Win32::IAkDeviceEnumerator
Interface to access the IMMDevice cache. This avoids driver accesses.
Definition: AkMMDevice.h:465
AK::Win32::DeviceProperty::DeviceProperty
DeviceProperty(const DeviceProperty &other)=delete
AK::Win32::DeviceCollection::Iterator::operator+
Iterator operator+(AkUInt32 inc) const
Definition: AkMMDevice.h:271
AK::Win32::DeviceEnumerator::DeviceEnumerator
DeviceEnumerator(DeviceEnumerator &&other)
Definition: AkMMDevice.h:415
AK::Win32::DeviceCollection::Iterator::pDevices
interface IMMDeviceCollection * pDevices
Definition: AkMMDevice.h:318
AK::Win32::DeviceEnumerator::pEnumerator
interface IMMDeviceEnumerator * pEnumerator
Definition: AkMMDevice.h:460
AK::Win32::Device::operator=
Device & operator=(Device &&other)
Definition: AkMMDevice.h:181
AK::Win32::IAkDeviceEnumerator::Count
virtual AkUInt32 Count()=0
AK::Win32::DeviceCollection::pDevices
interface IMMDeviceCollection * pDevices
Definition: AkMMDevice.h:397
AK::Win32::Device::IsValid
bool IsValid() const
Definition: AkMMDevice.h:216
AK::Win32::DeviceCollection::Iterator::operator!=
bool operator!=(const Iterator &in_rOp) const
!= operator</div>
Definition: AkMMDevice.h:304
AK::Win32::DeviceProperties::pProps
IPropertyStore * pProps
Definition: AkMMDevice.h:144
AK::Win32::DeviceProperty::operator=
DeviceProperty & operator=(const DeviceProperty &other)=delete
AK::Win32::DeviceProperty::IsEmpty
bool IsEmpty() const
Definition: AkMMDevice.h:84
AK::Win32::DeviceProperty::variant
PROPVARIANT variant
Definition: AkMMDevice.h:86
AK::Win32::DeviceCollection::Iterator::operator-
AkUInt32 operator-(Iterator const &rhs) const
Definition: AkMMDevice.h:278
AK::Win32::DeviceEnumerator::DeviceEnumerator
DeviceEnumerator(const DeviceEnumerator &other)=delete
AK::Win32::DeviceCollection::Iterator::operator++
Iterator & operator++()
++ operator</div>
Definition: AkMMDevice.h:284
AK::Win32::DeviceProperties::DeviceProperties
DeviceProperties(IMMDevice *in_pDevice)
Definition: AkMMDevice.h:99
AK::Win32::IAkDeviceEnumerator::Unlock
virtual void Unlock()=0
For thread safety. If you iterate through all the devices, lock the enumerator to avoid changes....
AK::Win32::DeviceCollection::Iterator::operator==
bool operator==(const Iterator &in_rOp) const
== operator</div>
Definition: AkMMDevice.h:298
AK::Win32::DeviceProperty::DeviceProperty
DeviceProperty(DeviceProperty &&other)
Definition: AkMMDevice.h:57
AK::Win32::DeviceCollection::DeviceCollection
DeviceCollection(IMMDeviceEnumerator *pEnumerator)
Definition: AkMMDevice.h:322
AkUInt32
uint32_t AkUInt32
Unsigned 32-bit integer.
Definition: AkTypes.h:59
AK::Win32::IAkDeviceEnumerator::FindDevice
virtual Device FindDevice(AkUInt32 in_id)=0
For thread safety. See Lock()
AK::Win32::Device::operator=
Device & operator=(IMMDevice *pOther)
Definition: AkMMDevice.h:208
AK::Win32::DeviceEnumerator::operator=
DeviceEnumerator & operator=(DeviceEnumerator &&other)
Definition: AkMMDevice.h:435
AK::Win32::DeviceEnumerator::GetDefaultDevice
Device GetDefaultDevice(ERole in_eRole)
Definition: AkMMDevice.h:451
AKPLATFORM::AkWideCharToChar
AkForceInline AkInt32 AkWideCharToChar(const wchar_t *in_pszUnicodeString, AkUInt32 in_uiOutBufferSize, char *io_pszAnsiString)
String conversion helper.
Definition: AkPlatformFuncs.h:437
AK::Win32::DeviceCollection::operator=
DeviceCollection & operator=(const DeviceCollection &other)=delete
AK::Win32::DeviceCollection::Iterator::operator--
Iterator & operator--()
– operator</div>
Definition: AkMMDevice.h:291
AK::FNVHash::ComputeLowerCase
static HashParams::HashType ComputeLowerCase(const char *in_pData)
Definition: AkFNVHash.h:131
AK::Win32::Device::Device
Device(Device &&other)
Definition: AkMMDevice.h:157
AK::Win32::DeviceProperty::operator=
DeviceProperty & operator=(DeviceProperty &&other)
Definition: AkMMDevice.h:73
AK::Win32::DeviceProperties::DeviceProperties
DeviceProperties(DeviceProperties &&other)
Definition: AkMMDevice.h:105

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise