PATH 
ADC Home > Documentation > Hardware > Device Managers and Drivers > PCI Card Services > Designing PCI Cards and Drivers for Power Macintosh Computers


  

FindDriverCandidates

OSErr FindDriverCandidates (
                     RegEntryIDPtr deviceID,
                     Ptr *propBasedDriver,
                     RegPropertyValueSize *propBasedDriverSize,
                     StringPtr deviceName,
                     DriverType *propBasedDriverType,
                     Boolean *gotPropBasedDriver,
                     FileBasedDriverRecordPtr fileBasedDrivers,
                     ItemCount *nFileBasedDrivers);
deviceID
Name Registry ID of target device.
propBasedDriver
Address of property-based driver.
propBasedDriverSize
Size of property-based driver.
deviceName
Returned name of the device.
propBasedDriverType
Type of property-based driver.
gotPropBasedDriver
Value is true if property-based driver was found.
fileBasedDrivers
List of sorted file-based driver records.
nFileBasedDrivers
Count of file-based driver records.
DESCRIPTION

Given the name entry ID of a device, FindDriverCandidates constructs a list of file-based drivers that match the device name or one of the device-compatible names. The list is sorted from best match to least favorable match. Drivers that match the device name are listed before drivers that match a compatible name. Each of these groups are further sorted by version numbers, using the HigherDriverVersion service. Property-based drivers are always matched using the device name and are returned separately from file-based drivers. An I/O expert can determine a property-based driver's ranking using the HigherDriverVersion service.

If a nil list output buffer is passed, only the count of matched file-based drivers is returned. An I/O expert can call FindDriverCandidates first with a nil buffer, allocate a buffer large enough for the list, and then call FindDriverCandidates again with the appropriately sized buffer.

If a nil value is passed in deviceID, all drivers from the Extensions folder are returned. When using this option, pass nil values for all parameters except fileBasedDrivers and nFileBasedDrivers.

The list of matched drivers consists of an array of file-based driver records:

struct FileBasedDriverRecord {
    FSSpec          theSpec;                /* file specification */
    DriverType      theType;                /* nameInfoStr & version
                                                number */
    Boolean         compatibleProp;         /* true if matched using a
                                                compatible name */
    UInt8           pad[3];                 /* alignment*/
};


typedef struct FileBasedDriverRecord
FileBasedDriverRecord,*FileBasedDriverRecordPtr;

A file-based driver consists of a file specification, the driver's type, and whether the driver was matched using the device name or a compatible device name.

An I/O expert can use the program logic summarized in Listing 9-1 to cycle through a list of file-based candidates.

Listing 9-1 Finding file-based driver candidates

FindDriverCandidates();     /* get list of candidates for a device */
    while (Candidates in the list)
{
        GetDriverFromFile ( FSSpec_in_Record, &driverConnectionID );
        if (InitializeThisDriver(Candidate) != NoErr))
            {
              /* unhold this failed driver's memory */
               /* and close its CFM connection */

               UnloadTheDriver ( driverConnectionID );

                /* advance to next position in the list */

                GetNextCandidate();
            }
        else
            break;      /* driver loaded and initialized */
}


RESULT CODES
noErr 0 No error
fnfErr -43 File not found
All CFM errors (see Inside Macintosh: PowerPC System Software)

© 1999 Apple Computer, Inc. – (Last Updated 26 March 99)