dx::proxy::device Class Reference

OS proxy device interface class. More...

#include <dx_proxy_device.h>

Inheritance diagram for dx::proxy::device:

Collaboration diagram for dx::proxy::device:

Public Member Functions
void	conclude () noexcept override
	conclude notification: object will be removed. If you overwrite conclude() you also need to overwrite destructor and check if its needed to be called from there.
void	conclude () noexcept override
	conclude notifacation: device will be removed from tree
auto	count () const noexcept
void	ctl (uint32_t ioctl) const
void	ctl (unsigned int ioctl) const
	device (decltype(driver)&driver, ::io_service_t id)
	the device class constructor
	device (decltype(super::driver)&driver, const std::string &id)
	the device class constructor
	dx_catchall_rethrow () ~device() noexcept override
	the device class destructor
	dx_catchall_rethrow (, "name: %s, access rights: %x, sharing options:%x", name, access, share)
registry &	erase (const char *key=nullptr)
void	exception (const dx::exception &exception, bool filtered=false) const noexcept override
	notification exception handler
void	exception (const dx::exception &exception, bool filtered=false) const noexcept override
	notification exception handler
::CFTypeRef	get (::CFStringRef key) const
template<typename value_t , typename = cf::enable_if_convertible<value_t>>
value_t	get (::CFStringRef key) const
::CFTypeRef	get (::CFStringRef key, ::CFTypeRef dflt) const noexcept
template<typename value_t , typename = cf::enable_if_convertible<value_t>>
value_t	get (::CFStringRef key, ::CFTypeRef dflt) const noexcept
template<typename value_t , typename = cf::enable_if_convertible<value_t>>
value_t	get (::CFStringRef key, value_t dflt) const noexcept
template<typename key_t , typename = cf::enable_if_convertible<key_t>>
::CFTypeRef	get (key_t key) const
template<typename key_t , typename value_t , typename = cf::enable_if_convertible<key_t>, typename = cf::enable_if_convertible<value_t>>
value_t	get (key_t key) const
template<typename rx_t >
rx_t	ictl (uint32_t ioctl) const
	member ioctl
template<typename rx_t >
size_t	ictl (uint32_t ioctl, rx_t &rx) const
template<typename rx_t >
rx_t	ictl (unsigned int ioctl) const
	Windows: member ioctl.
template<typename rx_t >
size_t	ictl (unsigned int ioctl, rx_t &rx) const
void	info (std::ostream &os) noexcept override
	log object class information
void	info (std::ostream &os) noexcept override
	log object class information
void	initialize (const char *name, ::DWORD access=GENERIC_READ|GENERIC_WRITE, ::DWORD share=FILE_SHARE_READ|FILE_SHARE_WRITE) try
	(re-)initialization the underlaying windows API is CreateFile(). for detailed information see http://msdn.microsoft.com/en-us/library/aa363858(VS.85).aspx
void	initialize (const char *path, ::HKEY root, ::REGSAM rights=KEY_READ, const char *key=nullptr)
void	initialize (const char *path, ::REGSAM rights=KEY_READ, ::HKEY root=HKEY_CURRENT_USER, const char *key=nullptr)
template<typename rx_t , typename tx_t >
rx_t	ioctl (uint32_t ioctl, const tx_t &tx) const
template<typename rx_t , typename tx_t >
size_t	ioctl (uint32_t ioctl, const tx_t &tx, rx_t &rx) const
size_t	ioctl (uint32_t ioctl, const void *tx=nullptr, size_t tx_size=0, void *rx=nullptr, size_t rx_size=0) const
template<typename rx_t , typename tx_t >
rx_t	ioctl (unsigned int ioctl, const tx_t &tx) const
template<typename tx_t , typename rx_t >
size_t	ioctl (unsigned int ioctl, const tx_t &tx, rx_t &rx) const
virtual void	launch ()
	launch notification: object mounted and ready to use
template<typename tx_t >
void	octl (uint32_t ioctl, const tx_t &tx) const
template<typename tx_t >
void	octl (unsigned int ioctl, const tx_t &tx) const
	operator const io_registry_entry_t & () const noexcept
	auto converter into const io_object
	operator io_registry_entry_t & () noexcept
	auto converter into io_object
	operator io_registry_entry_t * () noexcept
	auto converter into io_object pointer
	operator std::string () const
	operator uint64_t () const
template<typename value_t >
	operator value_t () const
template<typename value_t >
value_t	operator() (value_t dflt) const
	operator::CFMutableDictionaryRef () const
	operator::CFStringRef () const
	operator::HKEY () const noexcept
registry &	operator= (::CFTypeRef properties)
bool	operator== (io_registry_entry_t io_object) const noexcept
::CFTypeRef	operator[] (::CFStringRef key) const
registry	operator[] (const char *key) const
template<typename key_t , typename = cf::enable_if_convertible<key_t>>
::CFTypeRef	operator[] (key_t key) const
reference &	retain ()
registry &	set (::CFStringRef key, ::CFTypeRef value) noexcept
template<typename value_t , typename = cf::enable_if_convertible<value_t>>
registry &	set (::CFStringRef key, value_t value)
registry &	set (::CFTypeRef properties)
	Setting properties in a registry entry is not generally supported, it is more common to support setting of properties of the connection based property setting of dx::device.
template<typename key_t , typename = cf::enable_if_convertible<key_t>>
registry &	set (key_t key, ::CFTypeRef value)
template<typename key_t , typename value_t , typename = cf::enable_if_convertible<key_t>, typename = cf::enable_if_convertible<value_t>>
registry &	set (key_t key, value_t value)

Public Attributes
dx::driver< decltype(id)> &	driver
dx::driver< decltype(id)> &	driver
const ::io_service_t	id
const std::string	id
bool	launched {}
bool	launched {}
sc::preference	preference
registry	preference
std::string	puid
	persistent UID (i.e. serial number) - system unique - if no other option to identify could change with location
std::string	puuid
	persistent universal UID - universally unique ID
uint32_t	version
uint32_t	version

Protected Attributes
bool	connected = false
struct {
cf::type< const char * >   bundle_id
cf::type< const char * >   class_name
}	kernel
io::port	port

Detailed Description

OS proxy device interface class.

This is the OS proxy device interface class. This class is used for a platform independent way of accessing kernel/driverkit devices. The device class uses the driver interface helper class to construct the device object and to bind the device to the driver identified by the io_service.

example:

try() { // guard the block
    // choose a driver
    dx::driver<>driver (match);
 
    // enumerate devices
    std::cout<< driver.size()<< " device(s) found:"<< std::endl;
 
    // go thru all devices; you have to lock the driver if this multi-threaded
    for (auto device: driver){
        // return an int32_t from an IOCTL served by the driver
        int32_t my_data= device.ioctl<int32_t>(kMyIoctl);
    }
} cd_catchall()

Exceptions

In	case of an error returned by the underlaying API the device class throws a dx::exception.

This is the OS proxy device interface class. This class is used for a platform independent way of accessing kernel/driverkit devices. The device class uses the driver interface helper class to construct the device object and to bind the device to the driver identified by the GUID.

example:

try() { // guard the block
    // choose a driver
    dx::proxy::driver<>driver (match);
 
    // enumerate devices
    std::cout<< driver.size()<< " device(s) found:"<< std::endl;
 
    // go thru all devices; you have to lock the driver if this multi-threaded
    for (auto device: driver){
        // return an int32_t from an IOCTL served by the driver
        int32_t my_data= device.ioctl<int32_t>(kMyIoctl);
    }
} cd_catchall()

Exceptions

in	case of an error returned by the underlaying API the device class throws an exception converted from dx::os_result. with the default exception_t=dx::os_result template parameter the dx::os_result itself will be thrown.

Constructor & Destructor Documentation

device() [1/2]

dx::proxy::device::device ( decltype(driver)& driver, ::io_service_t id )

inline

the device class constructor

Exceptions

kIOReturn

NoMemory means that the system couldn't allocate the class defined in the drivers plist, or nub which ever its trying connecting to

Constructs and open device,

connects notification port and ignores if it failed: It will fail on drivers not providing a notificaion port, like Apple Family drivers.

Todo

proxy::device: find a way to set notification port only propratary DriverKit devices and except on failure to do so.

Parameters

driver	device tree hosting dx::driver
id	the IOService object to open the device connection for. This will be retained during device class lifetime

device() [2/2]

dx::proxy::device::device ( decltype(super::driver)& driver, const std::string & id )

inline

the device class constructor

the underlaying windows API is RegisterDeviceNotification(). for detailed information see http://msdn.microsoft.com/en-us/library/windows/desktop/aa363431(v=vs.85).aspx

Exceptions

n/a	microsoft does not give information about what possible errors values are provided by its OS

Member Function Documentation

conclude() [1/2]

void dx::proxy::device::conclude ( )

inlineoverridevirtualnoexcept

conclude notification: object will be removed. If you overwrite conclude() you also need to overwrite destructor and check if its needed to be called from there.

Reimplemented from dx::object.

Here is the call graph for this function:

Here is the caller graph for this function:

conclude() [2/2]

void dx::proxy::device::conclude ( )

inlineoverridevirtualnoexcept

conclude notifacation: device will be removed from tree

Reimplemented from dx::object.

count()

auto dx::io::reference< io_registry_entry_t >::count ( ) const

inlinenoexceptinherited

ctl() [1/2]

void dx::proxy::device::ctl ( uint32_t ioctl ) const

inline

ctl() [2/2]

void dx::proxy::device::ctl ( unsigned int ioctl ) const

inline

dx_catchall_rethrow() [1/2]

dx::proxy::device::dx_catchall_rethrow ( )

inlineoverridenoexcept

the device class destructor

the underlaying IOKit API is IOServiceClose().

remark: The io_service reference itself is managed by inherited io::reference

for detailed information see

Disconnect notification port,

closes the connection to the IOService object

dx_catchall_rethrow() [2/2]

dx::file::dx_catchall_rethrow ( "name: % s, access rights:% x, sharing options:%x" , name , access , share  )

inherited

erase()

registry & dx::registry::erase ( const char * key = nullptr )

inlineinherited

Todo

registry::erase(): investigate why it's not working

exception() [1/2]

void dx::proxy::device::exception ( const dx::exception & exception, bool filtered = false ) const

inlineoverridevirtualnoexcept

notification exception handler

Reimplemented from dx::device<::io_service_t >.

Reimplemented in dx::usb::platform::device.

exception() [2/2]

void dx::proxy::device::exception ( const dx::exception & exception, bool filtered = false ) const

inlineoverridevirtualnoexcept

notification exception handler

Reimplemented from dx::device<::io_service_t >.

Reimplemented in dx::usb::platform::device.

Here is the call graph for this function:

get() [1/7]

::CFTypeRef dx::io::registry::get ( ::CFStringRef key ) const

inlineinherited

Here is the caller graph for this function:

get() [2/7]

template<typename value_t , typename = cf::enable_if_convertible<value_t>>

value_t dx::io::registry::get ( ::CFStringRef key ) const

inlineinherited

Here is the call graph for this function:

get() [3/7]

::CFTypeRef dx::io::registry::get ( ::CFStringRef key, ::CFTypeRef dflt ) const

inlinenoexceptinherited

get() [4/7]

template<typename value_t , typename = cf::enable_if_convertible<value_t>>

value_t dx::io::registry::get ( ::CFStringRef key, ::CFTypeRef dflt ) const

inlinenoexceptinherited

Here is the call graph for this function:

get() [5/7]

template<typename value_t , typename = cf::enable_if_convertible<value_t>>

value_t dx::io::registry::get ( ::CFStringRef key, value_t dflt ) const

inlinenoexceptinherited

Here is the call graph for this function:

get() [6/7]

template<typename key_t , typename = cf::enable_if_convertible<key_t>>

::CFTypeRef dx::io::registry::get ( key_t key ) const

inlineinherited

Here is the call graph for this function:

Here is the caller graph for this function:

get() [7/7]

template<typename key_t , typename value_t , typename = cf::enable_if_convertible<key_t>, typename = cf::enable_if_convertible<value_t>>

value_t dx::io::registry::get ( key_t key ) const

inlineinherited

Here is the call graph for this function:

ictl() [1/4]

template<typename rx_t >

rx_t dx::proxy::device::ictl ( uint32_t ioctl ) const

inline

member ioctl

this member retreives data from the device by providing an IOCTL code. the template argument defines the type of data to be retreived. this member is intended as a convinient way to retreive only small amounts of data since there is an intermediate stack copy involved in returning the data.

ictl() [2/4]

template<typename rx_t >

size_t dx::proxy::device::ictl ( uint32_t ioctl, rx_t & rx ) const

inline

ictl() [3/4]

template<typename rx_t >

rx_t dx::proxy::device::ictl ( unsigned int ioctl ) const

inline

Windows: member ioctl.

this member retreives data from the device by providing an IOCTL code. the template argument defines the type of data to be retreived. this member is intended as a convinient way to retreive only small amounts of data since there is an intermediate stack copy involved in returning the data.

the underlaying windows API is DeviceIoControl(). for detailed information see http://msdn.microsoft.com/en-us/library/aa363216(VS.85).aspx

Exceptions

n/a	microsoft does not give information about what possible errors values are provided by its OS other than
ERROR_INSUFFICIENT_BUFFER	if the output buffer is too small to receive any data

ictl() [4/4]

template<typename rx_t >

size_t dx::proxy::device::ictl ( unsigned int ioctl, rx_t & rx ) const

inline

info() [1/2]

void dx::proxy::device::info ( std::ostream & os )

inlineoverridevirtualnoexcept

log object class information

Reimplemented from dx::device<::io_service_t >.

info() [2/2]

void dx::proxy::device::info ( std::ostream & os )

inlineoverridevirtualnoexcept

log object class information

Reimplemented from dx::device<::io_service_t >.

Here is the call graph for this function:

initialize() [1/3]

void dx::file::initialize ( const char * name, ::DWORD access = GENERIC_READ| GENERIC_WRITE, ::DWORD share = FILE_SHARE_READ| FILE_SHARE_WRITE )

inlineinherited

(re-)initialization the underlaying windows API is CreateFile(). for detailed information see http://msdn.microsoft.com/en-us/library/aa363858(VS.85).aspx

Exceptions

n/a	microsoft does not give information about what possible errors values are provided by its OS

Here is the caller graph for this function:

initialize() [2/3]

void dx::registry::initialize ( const char * path, ::HKEY root, ::REGSAM rights = KEY_READ, const char * key = nullptr )

inlineinherited

Here is the caller graph for this function:

initialize() [3/3]

void dx::registry::initialize ( const char * path, ::REGSAM rights = KEY_READ, ::HKEY root = HKEY_CURRENT_USER, const char * key = nullptr )

inlineinherited

ioctl() [1/5]

template<typename rx_t , typename tx_t >

rx_t dx::proxy::device::ioctl ( uint32_t ioctl, const tx_t & tx ) const

inline

ioctl() [2/5]

template<typename rx_t , typename tx_t >

size_t dx::proxy::device::ioctl ( uint32_t ioctl, const tx_t & tx, rx_t & rx ) const

inline

ioctl() [3/5]

size_t dx::proxy::device::ioctl ( uint32_t ioctl, const void * tx = nullptr, size_t tx_size = 0, void * rx = nullptr, size_t rx_size = 0 ) const

inline

ioctl() [4/5]

template<typename rx_t , typename tx_t >

rx_t dx::proxy::device::ioctl ( unsigned int ioctl, const tx_t & tx ) const

inline

ioctl() [5/5]

template<typename tx_t , typename rx_t >

size_t dx::proxy::device::ioctl ( unsigned int ioctl, const tx_t & tx, rx_t & rx ) const

inline

launch()

virtual void dx::object::launch ( )

inlinevirtualinherited

launch notification: object mounted and ready to use

Reimplemented in dx::stream::stream< device_t, circular_t >, dx::stream::stream< dx::stream::device >, dx::usb::stream::device< desc_t >, dx::virtuel::driver< dx::test::device< typename audio_pin_t::circular_t, super_device_t > >, dx::virtuel::driver< device_t >, dx::coreaudio::driver< device_t >, dx::proxy::driver< device< pin_t > >, dx::proxy::driver< device< typename audio_pin_t::circular_t, super_device_t > >, dx::proxy::driver< device_t >, dx::proxy::driver< dx::test::midi::device< typename audio_pin_t::circular_t, super_device_t, typename midi_pin_t::circular_t > >, dx::proxy::driver< device_t >, dx::proxy::driver< device< pin_t > >, dx::proxy::driver< device< typename audio_pin_t::circular_t, super_device_t > >, dx::proxy::driver< device_t >, dx::proxy::driver< dx::test::midi::device< typename audio_pin_t::circular_t, super_device_t, typename midi_pin_t::circular_t > >, and dx::proxy::driver< device_t >.

Here is the caller graph for this function:

octl() [1/2]

template<typename tx_t >

void dx::proxy::device::octl ( uint32_t ioctl, const tx_t & tx ) const

inline

octl() [2/2]

template<typename tx_t >

void dx::proxy::device::octl ( unsigned int ioctl, const tx_t & tx ) const

inline

operator const io_registry_entry_t &()

dx::io::reference< io_registry_entry_t >::operator const io_registry_entry_t & ( ) const

inlinenoexceptinherited

auto converter into const io_object

operator io_registry_entry_t &()

dx::io::reference< io_registry_entry_t >::operator io_registry_entry_t & ( )

inlinenoexceptinherited

auto converter into io_object

operator io_registry_entry_t *()

dx::io::reference< io_registry_entry_t >::operator io_registry_entry_t * ( )

inlinenoexceptinherited

auto converter into io_object pointer

operator std::string()

dx::registry::operator std::string ( ) const

inlineinherited

operator uint64_t()

dx::io::registry::operator uint64_t ( ) const

inlineexplicitinherited

operator value_t()

template<typename value_t >

dx::registry::operator value_t ( ) const

inlineinherited

operator()()

template<typename value_t >

value_t dx::registry::operator() ( value_t dflt ) const

inlineinherited

operator::CFMutableDictionaryRef()

dx::io::registry::operator::CFMutableDictionaryRef ( ) const

inlineexplicitinherited

Here is the call graph for this function:

Here is the caller graph for this function:

operator::CFStringRef()

dx::io::registry::operator::CFStringRef ( ) const

inlineexplicitinherited

operator::HKEY()

dx::registry::operator::HKEY ( ) const

inlinenoexceptinherited

operator=()

registry & dx::proxy::device::operator= ( ::CFTypeRef properties )

inline

operator==()

bool dx::io::reference< io_registry_entry_t >::operator== ( io_registry_entry_t io_object ) const

inlinenoexceptinherited

operator[]() [1/3]

::CFTypeRef dx::io::registry::operator[] ( ::CFStringRef key ) const

inlineinherited

Here is the call graph for this function:

operator[]() [2/3]

registry dx::registry::operator[] ( const char * key ) const

inlineinherited

operator[]() [3/3]

template<typename key_t , typename = cf::enable_if_convertible<key_t>>

::CFTypeRef dx::io::registry::operator[] ( key_t key ) const

inlineinherited

Here is the call graph for this function:

retain()

reference & dx::io::reference< io_registry_entry_t >::retain ( )

inlineinherited

set() [1/5]

registry & dx::proxy::device::set ( ::CFStringRef key, ::CFTypeRef value )

inlinenoexcept

set() [2/5]

template<typename value_t , typename = cf::enable_if_convertible<value_t>>

registry & dx::proxy::device::set ( ::CFStringRef key, value_t value )

inline

set() [3/5]

registry & dx::proxy::device::set ( ::CFTypeRef properties )

inline

Setting properties in a registry entry is not generally supported, it is more common to support setting of properties of the connection based property setting of dx::device.

set() [4/5]

template<typename key_t , typename = cf::enable_if_convertible<key_t>>

registry & dx::proxy::device::set ( key_t key, ::CFTypeRef value )

inline

set() [5/5]

template<typename key_t , typename value_t , typename = cf::enable_if_convertible<key_t>, typename = cf::enable_if_convertible<value_t>>

registry & dx::proxy::device::set ( key_t key, value_t value )

inline

Member Data Documentation

bundle_id

cf::type<const char*> dx::proxy::device::bundle_id

class_name

cf::type<const char*> dx::proxy::device::class_name

connected

bool dx::proxy::device::connected = false

protected

driver [1/2]

dx::driver<decltype(id)>& dx::device< std::string >::driver

inherited

driver [2/2]

dx::driver<decltype(id)>& dx::device< ::io_service_t >::driver

inherited

id [1/2]

const std::string dx::device< std::string >::id

inherited

id [2/2]

const ::io_service_t dx::device< ::io_service_t >::id

inherited

[struct]

struct { ... } dx::proxy::device::kernel

launched [1/2]

bool dx::object::launched {}

inherited

launched [2/2]

bool dx::object::launched {}

inherited

port

io::port dx::proxy::device::port

protected

preference [1/2]

sc::preference dx::proxy::device::preference

preference [2/2]

registry dx::proxy::device::preference

puid

std::string dx::proxy::device::puid

persistent UID (i.e. serial number) - system unique - if no other option to identify could change with location

puuid

std::string dx::proxy::device::puuid

persistent universal UID - universally unique ID

version [1/2]

uint32_t dx::device< ::io_service_t >::version

inherited

version [2/2]

uint32_t dx::device< std::string >::version

inherited

---

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

• macOS/dx_proxy_device.h
• windows/dx_proxy_device.h