Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

IODeviceMaster

Inherits From:	Object

Declared In:	driverkit/IODeviceMaster.h

Class Description

IODeviceMaster is a class used by user-level programs to gain access to device driver instances. To use IODeviceMaster, the program uses the alloc and init methods to obtain and initialize an IODeviceMaster instance. It then attempts to get the object number of the device driver instance using one of the lookUp... methods. If successful, it can use this object number to get and set parameters associated with the driver instance.

Programs don't need superuser privileges to get information from IODeviceMaster. However, they do need superuser privileges to be able to set device information (with the setCharValues:... and setIntValues: methods).

Here's an example of using IODeviceMaster. It's taken from the DriverInspector directory located in /NextLibrary/Documentation/NextDev/Examples/DriverKit. 

IOReturn        ret;
IOObjectNumber  objectNumber;
IOString        kind;
IOCharParameter value;
unsigned int    count = IO_MAX_PARAMETER_ARRAY_LENGTH, unit = 0;
char            name[80];
IODeviceMaster *devMaster;

/* Look up the test driver, using IODeviceMaster. */
devMaster = [IODeviceMaster new];
sprintf(name, "%s%d", my_DEVICE_NAME, unit);
ret = [devMaster lookUpByDeviceName:name objectNumber:&objectNumber 
    deviceKind:&kind];
if (ret != IO_R_SUCCESS) { /* handle the error */
    fprintf(stderr, "Lookup failed: %s\n", 
        [IODevice stringFromReturn:ret]);
    exit(-1);
} else { /* Successfully got the object number */

    /* Get the value of the test driver's parameter. */
    ret = [devMaster getCharValues:value 
        forParameter:my_PARAMETER_NAME objectNumber:objectNumber
        count:&count];
    if (ret != IO_R_SUCCESS) { /* handle the error */
        fprintf(stderr, "Failed to get parameter value: %s\n", 
            [IODevice stringFromReturn:ret]);
        exit(-1);
    } else /* Successfully got the parameter value */
        printf("Parameter value: %s; count = %d\n", value, count);

Instance Variables

None declared in this class.

Method Types

Creating and freeing instances	+ new
- free

Finding IODevice objects	- lookUpByDeviceName:objectNumber:deviceKind:
- lookUpByObjectNumber:deviceKind:deviceName:

Getting and setting parameter values	
- getCharValues:forParameter:objectNumber:count:
- getIntValues:forParameter:objectNumber:count:
- setCharValues:forParameter:objectNumber:count:
- setIntValues:forParameter:objectNumber:count:

Class Methods

new

+ new

Returns an IODeviceMaster object. An application has no more than one IODeviceManager object, so this method either returns the previously created object (if it exists) or creates a new one. 

Instead of new, use alloc and init to create and initialize an instance:

[[IODeviceMaster alloc] init];

Instance Methods

free

- free

Does nothing; an IODeviceMaster should never be freed.

getCharValues:forParameter:objectNumber:count:

- (IOReturn)getCharValues:(unsigned char *)array
forParameter:(IOParameterName)parameter
objectNumber:(IOObjectNumber)objectNumber
count:(unsigned int *)count

Gets the array of values associated with parameter for the IODevice object specified by objectNumber; returns IO_R_SUCCESS. Unless count is specified to be 0, the returned array contains no more than count characters. On return, count is set to the number of characters in the array. You can obtain values for objectNumber using the method lookUpByDeviceName:objectNumber:deviceKind:. 

If objectNumber is larger than the highest existing object number, this method returns IO_R_NO_DEVICE. If objectNumber refers to an object number for a device driver that's no longer registered, this method returns IO_R_OFFLINE. If parameter is invalid (it isn't recognized by the IODevice instance to have character values that can be read), this method returns IO_R_UNSUPPORTED. 

See also:  - getIntValues:forParameter:objectNumber:count:, - setCharValues:forParameter:objectNumber:count:

getIntValues:forParameter:objectNumber:count:

- (IOReturn)getIntValues:(unsigned int *)array
forParameter:(IOParameterName)parameter
objectNumber:(IOObjectNumber)objectNumber
count:(unsigned int *)count

Gets the array of values associated with parameter for the IODevice object specified by objectNumber; returns IO_R_SUCCESS. Unless count is specified to be 0, the returned array contains no more than count characters. On return, count is set to the number of characters in the array. You can obtain values for objectNumber using the method lookUpByDeviceName:objectNumber:deviceKind:. 

If objectNumber is larger than the highest existing object number, this method returns IO_R_NO_DEVICE. If objectNumber refers to an object number for a device driver that's no longer registered, this method returns IO_R_OFFLINE. If parameter is invalid (it isn't recognized by the IODevice instance to have integer values that can be read), this method returns IO_R_UNSUPPORTED. 

See also:  - getCharValues:forParameter:objectNumber:count:, - setIntValues:forParameter:objectNumber:count:

lookUpByDeviceName:objectNumber:deviceKind:

- (IOReturn)lookUpByDeviceName:(IOString)deviceName
objectNumber:(IOObjectNumber *)objectNumber
deviceKind:(IOString *)deviceKind

Gets the object number and descriptive string associated with the specified device name. The name is device-specific; it's the same as the value the driver sets using setName:. Returns IO_R_SUCCESS if the lookup was successful. Otherwise, returns IO_R_NO_DEVICE.

See also:  - lookUpByObjectNumber:deviceKind:deviceName:

lookUpByObjectNumber:deviceKind:deviceName:

- (IOReturn)lookUpByObjectNumber:(IOObjectNumber)objectNumber
deviceKind:(IOString *)deviceKind
deviceName:(IOString *)deviceName

Gets the descriptive strings associated with the IODevice specified by objectNumber. Returns IO_R_SUCCESS if the lookup was successful. If objectNumber is larger than the highest existing object number, returns IO_R_NO_DEVICE. If objectNumber refers to an object number for a device driver that's no longer registered, returns IO_R_OFFLINE.

See also:  - lookUpByDeviceName:objectNumber:deviceKind:

setCharValues:forParameter:objectNumber:count:

- (IOReturn)setCharValues:(unsigned char *)array
forParameter:(IOParameterName)parameter
objectNumber:(IOObjectNumber)objectNumber
count:(unsigned int)count

Sets the array of values associated with parameter for the IODevice object specified by objectNumber; returns IO_R_SUCCESS.  The count argument specifies the number of elements in the array.  You can obtain values for objectNumber using the method lookUpByDeviceName:objectNumber:deviceKind:.  

If objectNumber is larger than the highest existing object number, this method returns IO_R_NO_DEVICE.  If objectNumber refers to an object number for a device driver that's no longer registered, this method returns IO_R_OFFLINE.  If parameter is invalid (it isn't recognized by the IODevice instance to have character values that can be written), this method returns IO_R_UNSUPPORTED. 

See also:  - setIntValues:forParameter:objectNumber:count:, - getCharValues:forParameter:objectNumber:count:

setIntValues:forParameter:objectNumber:count:

- (IOReturn)setIntValues:(unsigned int *)array
forParameter:(IOParameterName)parameter
	objectNumber:(IOObjectNumber)objectNumber
count:(unsigned int)count

Sets the array of values associated with parameter for the IODevice object specified by objectNumber; returns IO_R_SUCCESS.  The count argument specifies the number of elements in the array.  You can obtain values for objectNumber using the method lookUpByDeviceName:objectNumber:deviceKind:.  

If objectNumber is larger than the highest existing object number, this method returns IO_R_NO_DEVICE.  If objectNumber refers to an object number for a device driver that's no longer registered, this method returns IO_R_OFFLINE.  If parameter is invalid (it isn't recognized by the IODevice instance to have integer values that can be written), this method returns IO_R_UNSUPPORTED. 

See also:  - setCharValues:forParameter:objectNumber:count:, - getIntValues:forParameter:objectNumber:count: