=========
hidd_hidd
=========

.. This document is automatically generated. Don't edit it!

`Index <index>`_

----------

Classes
-------

+ `CLID_HW`_
+ `hiddclass`_
+ `CLID_HW_Root`_

----------

CLID_HW
-------

========================================== ========================================== ========================================== ========================================== 
`--background_hwclass--`_                  `aoHW_ClassName`_                          `aoHW_InUse`_                              `moHW_AddDriver`_                          
`moHW_CleanUpDriver`_                      `moHW_EnumDrivers`_                        `moHW_RemoveDriver`_                       `moHW_SetUpDriver`_                        

========================================== ========================================== ========================================== ========================================== 

-----------

--background_hwclass--
======================

Notes
~~~~~
::

     The hwclass is the base class for all hardware subsystems in AROS. Its
     main purpose is to manage hardware driver instances.
     
     A hardware subsystem is typically a class of devices, e. g. keyboards, mice, etc.
     The hwclass stores information about existing driver instances, for enumeration by client
     applications.

     A typical hardware subsystem class should be implemented as a singleton to simplify
     handling.



----------

aoHW_ClassName
==============

Synopsis
~~~~~~~~
::

     [I.G], CONST_STRPTR


Function
~~~~~~~~
::

     Query human-readable description of the class. E. g. "Keyboards".



----------

aoHW_InUse
==========

Synopsis
~~~~~~~~
::

     [..G], BOOL


Function
~~~~~~~~
::

     Returns TRUE if the subsystem is currently in use by some driver(s)
     and FALSE otherwise.



----------

moHW_AddDriver
==============

Synopsis
~~~~~~~~
::

     OOP_Object *OOP_DoMethod(OOP_Object *obj, struct pHW_AddHardwareDriver *Msg);

     OOP_Object *HW_AddDriver(OOP_Object *obj, OOP_Class *driverClass,
                              struct TagItem *tags);


Function
~~~~~~~~
::

     Creates a hardware driver object instance, and registers it in the subsystem.


Inputs
~~~~~~
::

     obj         - The subsystem object to operate on.
     driverClass - A pointer to OOP class of the driver. In order to create an object
                   of some previously registered public class, use
                   oop.library/OOP_FindClass().
     tags        - An optional taglist which will be passed to driver class' New() method.


Result
~~~~~~
::

     A pointer to driver object or NULL in case of failure.


Notes
~~~~~
::

     Do not dispose the returned object yourself, use HW_RemoveDriver() for it.



See also
~~~~~~~~

`moHW_RemHardwareDriver`_ 

----------

moHW_CleanUpDriver
==================

Synopsis
~~~~~~~~
::

     void OOP_DoMethod(OOP_Object *obj, struct pHW_CleanUpDriver *Msg);

     void HW_CleanUpDriver(OOP_Object *obj, OOP_Object *driverObject);


Function
~~~~~~~~
::

     Performs subsystem-specific cleanup before driver object disposal.
     This method is intended to be used only by subclasses of CLID_HW.


Inputs
~~~~~~
::

     obj          - A subsystem object.
     driverObject - Device driver object.


Result
~~~~~~
::

     None.


Notes
~~~~~
::

     In base class this method does nothing.



See also
~~~~~~~~

`moHW_SetUpDriver`_ 

----------

moHW_EnumDrivers
================

Synopsis
~~~~~~~~
::

     void OOP_DoMethod(OOP_Object *obj, struct pHW_EnumDrivers *Msg);

     void HW_EnumDrivers(OOP_Object *obj, struct Hook *callback, APTR hookMsg);


Function
~~~~~~~~
::

     Enumerates all installed driver in the subsystem.


Inputs
~~~~~~
::

     obj      - A subsystem object to query.
     callback - A user-supplied hook which will be called for every driver.
     hookMsg  - A user-defined data to be passed to the hook.

     The hook must be defined using the AROS_UFH family of macros,
     and it will be called with the following parameters:
         AROS_UFHA(struct Hook *, hook        , A0)
             - A pointer to hook structure itself
         AROS_UFHA(OOP_Object * , driverObject, A2)
             - A device driver object
         AROS_UFHA(APTR         , message     , A1)
             - User-defined data

     The hook should return FALSE in order to continue enumeration
     or TRUE in order to stop it.


Result
~~~~~~
::

     None.



----------

moHW_RemoveDriver
=================

Synopsis
~~~~~~~~
::

     void OOP_DoMethod(OOP_Object *obj, struct pHW_RemoveDriver *Msg);

     void HW_RemoveDriver(OOP_Object *obj, OOP_Object *driver);


Function
~~~~~~~~
::

     Unregisters and disposes hardware driver object.


Inputs
~~~~~~
::

     obj    - The subsystem object from which the driver should be removed.
     driver - A pointer to a driver object, returned by HW_AddDriver().


Result
~~~~~~
::

     TRUE if removal successful or FALSE upon failure.


Notes
~~~~~
::

     The base class returns FALSE only if the driver is not registered
     in the subsystem. However, subclasses implementing actual subsystems
     can add their own checks, for example whether the driver currently
     owns some objects which are in use, and thus cannot be disposed.



See also
~~~~~~~~

`moHW_AddDriver`_ 

----------

moHW_SetUpDriver
================

Synopsis
~~~~~~~~
::

     void OOP_DoMethod(OOP_Object *obj, struct pHW_SetUpDriver *Msg);

     void HW_SetUpDriver(OOP_Object *obj, OOP_Object *driverObject);


Function
~~~~~~~~
::

     Performs subsystem-specific setup after driver object creation.
     This method is intended to be used only by subclasses of CLID_HW.


Inputs
~~~~~~
::

     obj          - A subsystem object.
     driverObject - Device driver object.


Result
~~~~~~
::

     TRUE if setup completed successfully and FALSE in case of error.
     If this method returns error, the driver object will be disposed
     and moHW_AddDriver method will fail.


Notes
~~~~~
::

     In base class this method does nothing and always returns TRUE.



See also
~~~~~~~~

`moHW_CleanUpDriver`_ 

hiddclass
---------

========================================== ========================================== ========================================== ========================================== 
`--background_hiddclass--`_                `aoHidd_DriverData`_                       `aoHidd_HardwareName`_                     `aoHidd_Name`_                             
`aoHidd_Producer`_                         `aoHidd_ProducerName`_                     `aoHidd_Product`_                          
========================================== ========================================== ========================================== ========================================== 

-----------

--background_hiddclass--
========================

Notes
~~~~~
::

     This class is a base class for all object-oriented hardware drivers in AROS. Its
     main purpose is to provide some information about the driver itself.
     
     At the moment this class is just a primary design. Many defined attributes and
     methods are drafts and reserved. This documentation includes only already
     estabilished definitions. Do not use any other methods and attributes, their
     definitions may change at any moment.



----------

aoHidd_DriverData
=================

Synopsis
~~~~~~~~
::

     [I..], APTR


Function
~~~~~~~~
::

     Provide private data for driver creation.

     This attribute is actually reserved for private use by device drivers.
     Many driver classes will scan the system and instantiate one or more
     objects of own class to control the discovered hardware. This attribute
     is intended to specify details of the actual device. For example for
     PCI device drivers this can be a pointer to PCI device objects.


Notes
~~~~~
::

     Be careful and do not use this attribute if you implement a public reusable
     class which is meant to be subclassed. In this case this attribute can be
     used by subclasses, and your own use will make a conflict.

     This attribute actually exists only in order to free the developer from need
     to create own private interface just for one attribute.



See also
~~~~~~~~

`aoHidd_Producer`_ 

----------

aoHidd_HardwareName
===================

Synopsis
~~~~~~~~
::

     [I.G], STRPTR


Function
~~~~~~~~
::

     Query hardware name string.


Notes
~~~~~
::

     Initial value for this attribute is usually supplied by driver class in its
     moRoot_New implementation.

     The supplied string is not copied!



See also
~~~~~~~~

`aoHidd_Name`_ 

----------

aoHidd_Name
===========

Synopsis
~~~~~~~~
::

     [I.G], STRPTR


Function
~~~~~~~~
::

     Name of the driver instance under which it is known to the OS. This name is
     provided to OS components that use the driver. For example Intuition's MONITORCLASS
     expects to find something like "ati_dvi1.monitor", "ati_vga1.monitor" or
     "pcvga.monitor" here.

     Note that is is instance name, not class name. Different instances of the driver may
     need to provide different names for different objects (like in ATI example) in order
     to let the OS to distinguish between them.

     The supplied string is internally copied, you may destroy it after object creation.


Notes
~~~~~
::

     Initial value for this attribute is usually supplied by driver class in its
     moRoot_New implementation.



See also
~~~~~~~~

`aoHidd_HardwareName`_ 

----------

aoHidd_Producer
===============

Synopsis
~~~~~~~~
::

     [I.G], ULONG


Function
~~~~~~~~
::

     Query hardware manufacturer's numeric ID. This ID may come for example from PCI
     or Zorro bus configuration data.


Notes
~~~~~
::

     It is valid to return 0 if your hardware doesn't provide any ID number.
     
     Initial value for this attribute is usually supplied by driver class in its
     moRoot_New implementation.



See also
~~~~~~~~

`aoHidd_Product`_ 

----------

aoHidd_ProducerName
===================

Synopsis
~~~~~~~~
::

     [I.G], STRPTR


Function
~~~~~~~~
::

     Query hardware manufacturer string. NULL is a valid value for this attribute
     meaning that the information is not specified.


Notes
~~~~~
::

     Initial value for this attribute is usually supplied by driver class in its
     moRoot_New implementation.

     The supplied string is not copied!



See also
~~~~~~~~

`aoHidd_HardwareName`_ 

----------

aoHidd_Product
==============

Synopsis
~~~~~~~~
::

     [I.G], ULONG


Function
~~~~~~~~
::

     Query hardware's numeric produce ID. This ID may come for example from PCI
     or Zorro bus configuration data.


Notes
~~~~~
::

     It is valid to return 0 if your hardware doesn't provide any ID number.

     Initial value for this attribute is usually supplied by driver class in its
     moRoot_New implementation.



See also
~~~~~~~~

`aoHidd_Producer`_ 

CLID_HW_Root
------------

========================================== ========================================== ========================================== ========================================== 
`--background_hwroot--`_                   
========================================== ========================================== ========================================== ========================================== 

-----------

--background_hwroot--
=====================

Notes
~~~~~
::

     This class represents a root of HIDD subsystem tree. In other words, it
     represents your computer. Calling HW_EnumDrivers() on it will enumerate
     installed subsystem classes.

     By design this class is a singletone. In order to get access to it, just
     call OOP_NewObject() on it. Every call will return the same pointer to
     the same object. You do not need to call OOP_Dispose object on it. Such
     calls will simply do nothing.

     Subsystem classes need to register themselves in the tree by calling
     HW_AddDriver() on this class. The class keeps an eye on the subsystem
     usage and will allow to remove it using HW_RemoveDriver() only if the
     subsystem being removed is not in use by any other components.



