aspl::Driver Class Reference

Plugin driver. More...

#include <aspl/Driver.hpp>

Public Member Functions
	Driver (std::shared_ptr< Context > context={}, std::shared_ptr< Plugin > plugin={}, std::shared_ptr< Storage > storage={})
	Construct driver. If context, plugin, or storage is not set, it is created automatically.
	Driver (const Driver &)=delete
Driver &	operator= (const Driver &)=delete
std::shared_ptr< const Context >	GetContext () const
	Get context. Context contains data shared among all driver objects.
std::shared_ptr< Plugin >	GetPlugin () const
	Get plugin. Plugin is the root of driver's object tree.
std::shared_ptr< Storage >	GetStorage () const
	Get storage. Storage provides API for persistent key-value database.
const AudioServerPlugInDriverInterface &	GetPluginInterface () const
	Get plugin interface. Plugin interface is a table with function pointers which implement various plugin operations.
AudioServerPlugInDriverRef	GetReference ()
	Get driver reference. This is what should be returned from plugin entry point.
void	SetDriverHandler (std::shared_ptr< DriverRequestHandler > handler)
	Set handler for HAL requests to driver. Optional. Use when you need to do custom handling.
void	SetDriverHandler (DriverRequestHandler *handler)
	Set handler for HAL requests to driver (raw pointer overload). This overload uses raw pointer instead of shared_ptr, and the user is responsible for keeping handler object alive until it's reset or Driver is destroyed.

Static Public Member Functions
static Driver *	GetDriver (AudioServerPlugInDriverRef driverRef)
	Cast driver reference back to driver.

Protected Member Functions
virtual OSStatus	Initialize ()
	Initialize driver. Default implementation invokes DriverRequestHandler::OnInitialize().
virtual OSStatus	CreateDevice (CFDictionaryRef description, const AudioServerPlugInClientInfo *clientInfo, AudioObjectID *outDeviceObjectID)
	Create device. Default implementation returns kAudioHardwareUnsupportedOperationError.
virtual OSStatus	DestroyDevice (AudioObjectID objectID)
	Destroy device. Default implementation returns kAudioHardwareUnsupportedOperationError.

Detailed Description

Plugin driver.

Driver is the top-level object of AudioServer plugin. It contains Plugin object, which is the root of the whole object hierarchy. The driver's job is to receive requests from HAL and redirect them to appropriate objects.

Driver is exposed to HAL as "driver reference" (AudioServerPlugInDriverRef). The driver reference is actually a pointer to pointer to "plugin driver interface" (AudioServerPlugInDriverInterface), which is a struct with a bunch of function pointers for various operations (mostly for property dispatch and I/O).

Driver fills this struct with its private functions. Each of them just finds the registered object by ID and redirects operation to it. Objects are searched in Context::Dispatcher. Every object requires Context as constructor argument and automatically registers and unregisters itself in Dispatcher.

Driver also provides Storage object, which provides API for persistent storage associated with plugin, and managed by CoreAudio daemon.

By default driver creates its own Context, Plugin, and Storage objects, but you can provide your own if desired.

After constructing driver, you need to use GetReference() method to obtain the "driver reference" and return it from the plugin entry point, like:

extern "C" void* MyEntryPoint(CFAllocatorRef, CFUUIDRef typeUUID)
{
  if (!CFEqual(typeUUID, kAudioServerPlugInTypeUUID)) {
    return nullptr;
  }
  static auto driver = std::make_shared<aspl::Driver>();
  return driver->GetReference();
}

Don't forget do declare your entry point in Info.plist of the plugin.

Right after the Driver object is created, it is not fully initialized yet. The final initialization is performed by HAL asynchronously, after returning from plugin entry point.

Until asynchronous initialization is done, most driver services are not really functioning yet: devices don't appear in system, persistent storage returns errors for all requests, etc.

The user can be notified when the initialization is done by providing custom DriverRequestHandler, or by inheriting Driver and overriding appropriate method.

Definition at line 71 of file Driver.hpp.

Constructor & Destructor Documentation

Driver()

aspl::Driver::Driver ( std::shared_ptr< Context > context = {}, std::shared_ptr< Plugin > plugin = {}, std::shared_ptr< Storage > storage = {} )

explicit

Construct driver. If context, plugin, or storage is not set, it is created automatically.

Member Function Documentation

CreateDevice()

virtual OSStatus aspl::Driver::CreateDevice ( CFDictionaryRef description, const AudioServerPlugInClientInfo * clientInfo, AudioObjectID * outDeviceObjectID )

protectedvirtual

Create device. Default implementation returns kAudioHardwareUnsupportedOperationError.

DestroyDevice()

virtual OSStatus aspl::Driver::DestroyDevice ( AudioObjectID objectID )

protectedvirtual

Destroy device. Default implementation returns kAudioHardwareUnsupportedOperationError.

GetContext()

std::shared_ptr< const Context > aspl::Driver::GetContext

(

)

const

Get context. Context contains data shared among all driver objects.

GetDriver()

static Driver * aspl::Driver::GetDriver ( AudioServerPlugInDriverRef driverRef )

static

Cast driver reference back to driver.

GetPlugin()

std::shared_ptr< Plugin > aspl::Driver::GetPlugin

(

)

const

Get plugin. Plugin is the root of driver's object tree.

GetPluginInterface()

const AudioServerPlugInDriverInterface & aspl::Driver::GetPluginInterface

(

)

const

Get plugin interface. Plugin interface is a table with function pointers which implement various plugin operations.

GetReference()

AudioServerPlugInDriverRef aspl::Driver::GetReference

(

)

Get driver reference. This is what should be returned from plugin entry point.

GetStorage()

std::shared_ptr< Storage > aspl::Driver::GetStorage

(

)

const

Get storage. Storage provides API for persistent key-value database.

Initialize()

virtual OSStatus aspl::Driver::Initialize ( )

protectedvirtual

Initialize driver. Default implementation invokes DriverRequestHandler::OnInitialize().

SetDriverHandler() [1/2]

void aspl::Driver::SetDriverHandler

(

DriverRequestHandler *

handler

)

Set handler for HAL requests to driver (raw pointer overload). This overload uses raw pointer instead of shared_ptr, and the user is responsible for keeping handler object alive until it's reset or Driver is destroyed.

SetDriverHandler() [2/2]

void aspl::Driver::SetDriverHandler

(

std::shared_ptr< DriverRequestHandler >

handler

)

Set handler for HAL requests to driver. Optional. Use when you need to do custom handling.

---

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

• aspl/Driver.hpp