Base class for audio objects. More...

#include <aspl/Object.hpp>

Inheritance diagram for aspl::Object:

Public Member Functions
	Object (std::shared_ptr< const Context > context, const char *className="Object", AudioObjectID objectID=kAudioObjectUnknown)
	Construct object. Class name is used for logging. It should be the name of the derived class. If objectID is `kAudioObjectUnknown` (zero), allocates new object ID. Otherwise uses given object ID.

	Object (const Object &)=delete

Object &	operator= (const Object &)=delete

std::shared_ptr< const Context >	GetContext () const
	Get object context.

Class and ID
virtual AudioClassID	GetClass () const
	Get class ID. Each subclass overrides this method.

virtual AudioClassID	GetBaseClass () const
	Get base class ID. Each subclass overrides this method.

virtual bool	IsInstance (AudioClassID classID) const
	Check if this object is instance of given base class. Returns true if any of the base classes matches given class ID. Each subclass overrides this method.

AudioObjectID	GetID () const
	Get object ID. Returns objectID selected at construction time.

Ownership
AudioObjectID	GetOwnerID () const
	Get object owner. If the object has an owner, returns its ID. Otherwise, returns `kAudioObjectUnknown` (zero).

bool	HasOwner () const
	Check if the object is part of the hierarchy. Returns true if GetOwnerID() is not equal to kAudioObjectUnknown.

std::vector< AudioObjectID >	GetOwnedObjectIDs (AudioObjectPropertyScope scope=kAudioObjectPropertyScopeGlobal, AudioClassID classID=0) const
	Get owned objects. Returns the list of objects to which this object is the owner.

void	AddOwnedObject (std::shared_ptr< Object > object, AudioObjectPropertyScope scope=kAudioObjectPropertyScopeGlobal)
	Add object to the list of owned objects. Also invokes SetOwner() on the added object.

void	RemoveOwnedObject (AudioObjectID objectID)
	Remove object to the list of owned objects. Also invokes SetOwner() on the removed object.

Notification
void	NotifyPropertyChanged (AudioObjectPropertySelector selector, AudioObjectPropertyScope scope=kAudioObjectPropertyScopeGlobal, AudioObjectPropertyElement element=kAudioObjectPropertyElementMain) const
	Notify HAL that a property was changed. This is automatically called by all setters.

void	NotifyPropertiesChanged (std::vector< AudioObjectPropertySelector > selectors, AudioObjectPropertyScope scope=kAudioObjectPropertyScopeGlobal, AudioObjectPropertyElement element=kAudioObjectPropertyElementMain) const
	Notify HAL that some properties were changed. This is automatically called by all setters.

Property dispatch
virtual Boolean	HasProperty (AudioObjectID objectID, pid_t clientPID, const AudioObjectPropertyAddress *address) const
	Check whether given property is present.

virtual OSStatus	IsPropertySettable (AudioObjectID objectID, pid_t clientPID, const AudioObjectPropertyAddress address, Boolean outIsSettable) const
	Check whether given property can be changed.

virtual OSStatus	GetPropertyDataSize (AudioObjectID objectID, pid_t clientPID, const AudioObjectPropertyAddress address, UInt32 qualifierDataSize, const void qualifierData, UInt32 *outDataSize) const
	Get size of property value in bytes.

virtual OSStatus	GetPropertyData (AudioObjectID objectID, pid_t clientPID, const AudioObjectPropertyAddress address, UInt32 qualifierDataSize, const void qualifierData, UInt32 inDataSize, UInt32 outDataSize, void outData) const
	Get property value.

virtual OSStatus	SetPropertyData (AudioObjectID objectID, pid_t clientPID, const AudioObjectPropertyAddress address, UInt32 qualifierDataSize, const void qualifierData, UInt32 inDataSize, const void *inData)
	Change property value.

Custom properties
template<typename ObjectType , typename ValueType >
using	GetterMethod = ValueType (ObjectType::*)() const
	Pointer to custom property getter method. Used in RegisterCustomProperty().

template<typename ObjectType , typename ValueType >
using	SetterMethod = void (ObjectType::*)(ValueType)
	Pointer to custom property setter method. Used in RegisterCustomProperty().

virtual std::vector< AudioServerPlugInCustomPropertyInfo >	GetCustomProperties () const
	Get info about registered custom properties. Returns list of properties added using RegisterCustomProperty().

template<typename ObjectType , typename ValueType >
void	RegisterCustomProperty (AudioObjectPropertySelector selector, ObjectType &object, GetterMethod< ObjectType, ValueType > getter, SetterMethod< ObjectType, ValueType > setter=nullptr)
	Register custom property with getter and optional setter.

template<typename GetterFunc >
void	RegisterCustomProperty (AudioObjectPropertySelector selector, GetterFunc getter)
	Register custom property with getter and optional setter.

void	RegisterCustomProperty (AudioObjectPropertySelector selector, std::function< CFStringRef()> getter, std::function< void(CFStringRef)> setter)
	Register custom property with getter and optional setter.

void	RegisterCustomProperty (AudioObjectPropertySelector selector, std::function< CFPropertyListRef()> getter, std::function< void(CFPropertyListRef)> setter)
	Register custom property with getter and optional setter.

Detailed Description

Base class for audio objects.

CoreAudio uses property-based object model to communicate with plugins. This class is the base class for various audio objects which implement property dispatch protocol required by HAL.

This class provides the following services:

Common context. Each object belongs to Context, a common environment shared between objects of the same plugin / driver.
Identification. Each object has a unique numeric identifier. ID is unique only within the same Context.
Classification. Each object belongs to one of the predefined classes. The class defines a set of the properties and probably other operations which should be supported by object.
Ownership. All objects of the plugin forms a tree hierarchy, with the Plugin object in the root.
Property dispatch protocol. Every object implements a set of methods allowing to introspect, get, and set its properties.
Notification. Object automatically notifies HAL when some of its properties is changed.
Registration of custom properties. Object allows to register custom user-defined properties in addition to builtin properties defined by CoreAudio.

Definition at line 54 of file Object.hpp.

Member Typedef Documentation

◆ GetterMethod

template<typename ObjectType , typename ValueType >

using aspl::Object::GetterMethod = ValueType (ObjectType::*)() const

Pointer to custom property getter method. Used in RegisterCustomProperty().

Definition at line 173 of file Object.hpp.

◆ SetterMethod

template<typename ObjectType , typename ValueType >

using aspl::Object::SetterMethod = void (ObjectType::*)(ValueType)

Pointer to custom property setter method. Used in RegisterCustomProperty().

Definition at line 178 of file Object.hpp.

Constructor & Destructor Documentation

◆ Object()

aspl::Object::Object	(	std::shared_ptr< const Context >	context,
		const char *	className = "Object",
		AudioObjectID	objectID = kAudioObjectUnknown )

explicit

Construct object. Class name is used for logging. It should be the name of the derived class. If objectID is kAudioObjectUnknown (zero), allocates new object ID. Otherwise uses given object ID.

Member Function Documentation

◆ AddOwnedObject()

void aspl::Object::AddOwnedObject	(	std::shared_ptr< Object >	object,
		AudioObjectPropertyScope	scope = kAudioObjectPropertyScopeGlobal )

Add object to the list of owned objects. Also invokes SetOwner() on the added object.

◆ GetBaseClass()

virtual AudioClassID aspl::Object::GetBaseClass ( ) const

virtual

Get base class ID. Each subclass overrides this method.

Note: Backs kAudioObjectPropertyBaseClass property.

Reimplemented in aspl::Device, aspl::MuteControl, aspl::Plugin, aspl::Stream, and aspl::VolumeControl.

◆ GetClass()

virtual AudioClassID aspl::Object::GetClass ( ) const

virtual

Get class ID. Each subclass overrides this method.

Note: Backs kAudioObjectPropertyClass property.

Reimplemented in aspl::Device, aspl::MuteControl, aspl::Plugin, aspl::Stream, and aspl::VolumeControl.

◆ GetContext()

std::shared_ptr< const Context > aspl::Object::GetContext ( ) const

Get object context.

◆ GetCustomProperties()

virtual std::vector< AudioServerPlugInCustomPropertyInfo > aspl::Object::GetCustomProperties ( ) const

virtual

Get info about registered custom properties. Returns list of properties added using RegisterCustomProperty().

Note: Backs kAudioObjectPropertyCustomPropertyInfoList property.

◆ GetID()

AudioObjectID aspl::Object::GetID ( ) const

Get object ID. Returns objectID selected at construction time.

◆ GetOwnedObjectIDs()

std::vector< AudioObjectID > aspl::Object::GetOwnedObjectIDs	(	AudioObjectPropertyScope	scope = kAudioObjectPropertyScopeGlobal,
		AudioClassID	classID = 0 ) const

Get owned objects. Returns the list of objects to which this object is the owner.

Remarks: Filters the returned list by scope and class. Global scope or zero class will match any object. Class, if non-zero, is matched using IsInstance() method, so parent classes will match derived classes too.

Note: Backs kAudioObjectPropertyOwnedObjects property.

◆ GetOwnerID()

AudioObjectID aspl::Object::GetOwnerID ( ) const

Get object owner. If the object has an owner, returns its ID. Otherwise, returns kAudioObjectUnknown (zero).

Note: Backs kAudioObjectPropertyOwner property.

◆ GetPropertyData()

virtual OSStatus aspl::Object::GetPropertyData	(	AudioObjectID	objectID,
		pid_t	clientPID,
		const AudioObjectPropertyAddress *	address,
		UInt32	qualifierDataSize,
		const void *	qualifierData,
		UInt32	inDataSize,
		UInt32 *	outDataSize,
		void *	outData ) const

virtual

Get property value.

Note: Invoked by HAL on non-realtime thread.

Reimplemented in aspl::Device, aspl::MuteControl, aspl::Plugin, aspl::Stream, and aspl::VolumeControl.

◆ GetPropertyDataSize()

virtual OSStatus aspl::Object::GetPropertyDataSize	(	AudioObjectID	objectID,
		pid_t	clientPID,
		const AudioObjectPropertyAddress *	address,
		UInt32	qualifierDataSize,
		const void *	qualifierData,
		UInt32 *	outDataSize ) const

virtual

Get size of property value in bytes.

Note: Invoked by HAL on non-realtime thread.

Reimplemented in aspl::Device, aspl::MuteControl, aspl::Plugin, aspl::Stream, and aspl::VolumeControl.

◆ HasOwner()

bool aspl::Object::HasOwner ( ) const

Check if the object is part of the hierarchy. Returns true if GetOwnerID() is not equal to kAudioObjectUnknown.

Remarks: By default, object does not have an owner. Until the object is attached to an owner, it is not part of the plugin object hierarchy and is not visible to HAL.

◆ HasProperty()

virtual Boolean aspl::Object::HasProperty	(	AudioObjectID	objectID,
		pid_t	clientPID,
		const AudioObjectPropertyAddress *	address ) const

virtual

Check whether given property is present.

Note: Invoked by HAL on non-realtime thread.

Reimplemented in aspl::Device, aspl::MuteControl, aspl::Plugin, aspl::Stream, and aspl::VolumeControl.

◆ IsInstance()

virtual bool aspl::Object::IsInstance ( AudioClassID classID ) const

virtual

Check if this object is instance of given base class. Returns true if any of the base classes matches given class ID. Each subclass overrides this method.

Reimplemented in aspl::Device, aspl::MuteControl, aspl::Plugin, aspl::Stream, and aspl::VolumeControl.

◆ IsPropertySettable()

virtual OSStatus aspl::Object::IsPropertySettable	(	AudioObjectID	objectID,
		pid_t	clientPID,
		const AudioObjectPropertyAddress *	address,
		Boolean *	outIsSettable ) const

virtual

Check whether given property can be changed.

Note: Invoked by HAL on non-realtime thread.

Reimplemented in aspl::Device, aspl::MuteControl, aspl::Plugin, aspl::Stream, and aspl::VolumeControl.

◆ NotifyPropertiesChanged()

void aspl::Object::NotifyPropertiesChanged	(	std::vector< AudioObjectPropertySelector >	selectors,
		AudioObjectPropertyScope	scope = kAudioObjectPropertyScopeGlobal,
		AudioObjectPropertyElement	element = kAudioObjectPropertyElementMain ) const

Notify HAL that some properties were changed. This is automatically called by all setters.

◆ NotifyPropertyChanged()

void aspl::Object::NotifyPropertyChanged	(	AudioObjectPropertySelector	selector,
		AudioObjectPropertyScope	scope = kAudioObjectPropertyScopeGlobal,
		AudioObjectPropertyElement	element = kAudioObjectPropertyElementMain ) const

inline

Notify HAL that a property was changed. This is automatically called by all setters.

Definition at line 146 of file Object.hpp.

◆ RegisterCustomProperty() [1/4]

template<typename GetterFunc >

void aspl::Object::RegisterCustomProperty	(	AudioObjectPropertySelector	selector,
		GetterFunc	getter )

inline

Register custom property with getter and optional setter.

This overload is for read-only properties (without setter).

GetterFunc should be convertible to std::function<ValueType()>, where value type should be either CFStringRef or CFPropertyListRef (because they are the only types allowed by CoreAudio).

Getter transfers ownership to the caller; the caller will call CFRelease().

Definition at line 232 of file Object.hpp.

◆ RegisterCustomProperty() [2/4]

template<typename ObjectType , typename ValueType >

void aspl::Object::RegisterCustomProperty	(	AudioObjectPropertySelector	selector,
		ObjectType &	object,
		GetterMethod< ObjectType, ValueType >	getter,
		SetterMethod< ObjectType, ValueType >	setter = nullptr )

inline

Register custom property with getter and optional setter.

This overload allows to use methods as getter and setter:

class MyObject : public aspl::Object
{
public:
  CFStringRef GetMyProperty() const { ... }
  void SetMyProperty(CFStringRef value) { ... }
 
  MyObject(...)
    : Object(...)
  {
    RegisterCustomProperty(
      MyPropertySelector, *this, &MyObject::GetMyProperty,
        &MyObject::SetMyProperty);
  }
};

Value type should be either CFStringRef or CFPropertyListRef because they are the only types allowed by CoreAudio.

Getter transfers ownership to the caller; the caller will call CFRelease(). Setter does not transfer ownership; the setter should call CFRetain() if it wants to store the value.

Definition at line 207 of file Object.hpp.

◆ RegisterCustomProperty() [3/4]

void aspl::Object::RegisterCustomProperty	(	AudioObjectPropertySelector	selector,
		std::function< CFPropertyListRef()>	getter,
		std::function< void(CFPropertyListRef)>	setter )

Register custom property with getter and optional setter.

This overload is for properties of type CFPropertyListRef.

Setter may be null function if the property is read-only.

Getter transfers ownership to the caller; the caller will call CFRelease(). Setter does not transfer ownership; the setter should call CFRetain() if it wants to store the value.

◆ RegisterCustomProperty() [4/4]

void aspl::Object::RegisterCustomProperty	(	AudioObjectPropertySelector	selector,
		std::function< CFStringRef()>	getter,
		std::function< void(CFStringRef)>	setter )

Register custom property with getter and optional setter.

This overload is for properties of type CFStringRef.

Setter may be null function if the property is read-only.

Getter transfers ownership to the caller; the caller will call CFRelease(). Setter does not transfer ownership; the setter should call CFRetain() if it wants to store the value.

◆ RemoveOwnedObject()

void aspl::Object::RemoveOwnedObject ( AudioObjectID objectID )

Remove object to the list of owned objects. Also invokes SetOwner() on the removed object.

◆ SetPropertyData()

virtual OSStatus aspl::Object::SetPropertyData	(	AudioObjectID	objectID,
		pid_t	clientPID,
		const AudioObjectPropertyAddress *	address,
		UInt32	qualifierDataSize,
		const void *	qualifierData,
		UInt32	inDataSize,
		const void *	inData )

virtual

Change property value.

Note: Invoked by HAL on non-realtime thread.

Reimplemented in aspl::Device, aspl::MuteControl, aspl::Plugin, aspl::Stream, and aspl::VolumeControl.

The documentation for this class was generated from the following file:

aspl/Object.hpp

Public Member Functions

Custom properties

Detailed Description

Member Typedef Documentation

◆ GetterMethod

◆ SetterMethod

Constructor & Destructor Documentation

◆ Object()

Member Function Documentation

◆ AddOwnedObject()

◆ GetBaseClass()

◆ GetClass()

◆ GetContext()

◆ GetCustomProperties()

◆ GetID()

◆ GetOwnedObjectIDs()

◆ GetOwnerID()

◆ GetPropertyData()

◆ GetPropertyDataSize()

◆ HasOwner()

◆ HasProperty()

◆ IsInstance()

◆ IsPropertySettable()

◆ NotifyPropertiesChanged()

◆ NotifyPropertyChanged()

◆ RegisterCustomProperty() [1/4]

◆ RegisterCustomProperty() [2/4]

◆ RegisterCustomProperty() [3/4]

◆ RegisterCustomProperty() [4/4]

◆ RemoveOwnedObject()

◆ SetPropertyData()