RMCreateDevice

This rmcall service obtains a device handle and allows a driver to register a device with the Resource Manager and assign the device to an adapter. A device handle (HDEVICE) is returned by this service to identify the device.

Syntax

rc = RMCreateDevice(hDriver, hDevice, DeviceStruct, hParentAdapter, ResourceList);

Parameters

hDriver (HDRIVER) - input

Handle of the device driver creating this device.

hDevice (PHDEVICE) - output

Pointer to a variable to receive the returned device handle.

DeviceStruct (PDEVICESTRUCT) - output

Pointer to the DEVICESTRUCT structure.

hParentAdapter (HADAPTER) - input

Handle of the parent adapter for the device being created.

ResourceList (PAHRESOURCE) - output

Pointer to the AHRESOURCE structure, which contains a count and a list of resource handles to be assigned to this device.

Return Code

rc (APIRET) - returns

On systems where the Resource Manager driver is not installed, the library interface code will return RMRC_SUCCESS and an adapter handle of -1L.

RMRC_IRQ_ENTRY_ILLEGAL : A Resource Manager service was issued at interrupt time. The Resource Manager service request can be issued only at task time or INIT time.

RMRC_NULL_POINTER : A Resource Manager service received a NULL value for a pointer that was expected to contain a valid 16:16 address.

RMRC_NULL_STRINGS : A descriptive text pointer in a DRIVERSTRUCT, ADAPTERSTRUCT, or DEVICESTRUCT datatype was found to be NULL rather than pointing to the expected ASCIIZ text data.

RMRC_BAD_DRIVERHANDLE: The expected Resource Manager handles were not provided because the handle was not a valid Resource Manager handle or the handle did not point to the type of object the service required.

RMRC_BAD_ADAPTERHANDLE: The expected Resource Manager handles were not provided because the handle was not a valid Resource Manager handle or the handle did not point to the type of object the service required.

RMRC_BAD_RESOURCEHANDLE: The expected Resource Manager handles were not provided because the handle was not a valid Resource Manager handle or the handle did not point to the type of object the service required.

Remarks

When a device is registered, a list of resource handles (representing hardware resources used by this device) can be assigned optionally to the device.

Information about the device being registered is passed in a DEVICESTRUCT.

Resources are usually assigned to the adapter (parent) that owns the device. In some cases, resources are used specifically by a particular device rather than shared between multiple devices supported by an adapter. In this case, resources should be assigned to the device, as appropriate.

Example Code

C

#include <os2.h>
#include <rmcalls.h>

HDRIVER          hDriver;
PHDEVICE         hDevice;
PDEVICESTRUCT    DeviceStruct;
HADAPTER         hParentAdapter;
PAHRESOURCE      ResourceList;
APIRET           rc;

rc = RMCreateDevice(hDriver, hDevice, DeviceStruct,
       hParentAdapter, ResourceList);