http://www.aros.orgAROS-ExecAROS-Exec ArchivesPower2People
kitty mascottop logo menu

hidd_hidd

Index



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.

CLID_HW

--background_hwclass-- aoHW_ClassName aoHW_InUse moHW_AddDriver
moHW_CleanUpDriver moHW_EnumDrivers moHW_RemoveDriver moHW_SetUpDriver

--background_hwclass--

Notes

This class is a base class for all hardware subsystems in AROS. Its
main purpose is to manage hardware drivers.

A "subsystem" is a kind of devices, e. g. keyboards, mice, etc. This
class stores information about existing device instances and can provide
this information to user's software.

A typical subsystem class should be a singletone. This greatly simplifies
handling it.

aoHW_ClassName

Synopsis

[I.G], CONST_STRPTR

Function

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

aoHW_InUse

Synopsis

[..G], BOOL

Function

Return 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 and registers it in the subsystem.

Inputs

obj         - A 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.

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.

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 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    - A subsystem object from which the driver should be removed.
driver - A pointer to a driver object, returned by HW_AddDriver().

Result

TRUE if removal succesful 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.

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 succesfully 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.

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.

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!

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.

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.

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!

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.

Docutils System Messages

System Message: ERROR/3 (/home/mazze/projects/aros-src/documentation/documentation/developers/autodocs/hidd_hidd.en, line 174); backlink

Unknown target name: "mohw_remhardwaredriver".

Copyright © 1995-2014, The AROS Development Team. All rights reserved.
Amiga®, AmigaOS®, Workbench and Intuition are trademarks of Amiga Inc. All other trademarks belong to their respective owners.