Implement the Device Access Object

  • Article

This topic explains how to instantiate the device access object and use it to access a device. The instantiated class implements the IDeviceIoControl and ICreateDeviceAccessAsync interfaces.

Instructions

Step 1:

To instantiate the device access object, you must first call the CreateDeviceAccessInstance function. If CreateDeviceAccessInstance succeeds, you can then call the Wait method to wait for the asynchronous operation to finish. If Wait succeeds, you can retrieve an IDeviceIoControl object (or the appropriate error) from the GetResult method.

HRESULT
CMyServer::Initialize(
        PCWSTR   pszDeviceInterfacePath
    )

/*++
Routine Description:

    This routine is called to initialize the Device Access object.
    It's not part of the constructor as the initialization can fail.
    It opens the device and gets the IDeviceIoControl interface to the device instance
    via the broker.

Arguments:
    pszDeviceInterfacePath - the device interface string that needs to be opened

Return Value:

    HRESULT

--*/

{
    HRESULT hr;
    ICreateDeviceAccessAsync *pDeviceAccess;

     //
     // Here's the actual open call.  This will *fail* if your lowbox does
     // not have the capability mapped to the interface class specified.
     // If you are running this as normal user, it will just pass through to
     // create file.
     //

   hr = CreateDeviceAccessInstance(pszDeviceInterfacePath,
                                   GENERIC_READ|GENERIC_WRITE,
                                   &pDeviceAccess);

    if (FAILED(hr)) {
        return hr;
    }

    if (SUCCEEDED(hr)) {
        hr = pDeviceAccess->Wait(INFINITE);
    }

    if (SUCCEEDED(hr)) {
        hr = pDeviceAccess->GetResult(IID_IDeviceIoControl,
                                            (void **)&m_pDeviceIoControl);
    }

    pDeviceAccess->Release();

    return hr;
}

Step 2:

This is an example of a call to the DeviceIoControlSync method.

IFACEMETHODIMP 
CMyServer::put_SevenSegmentDisplay(
    BYTE   value
    )
/*++

Routine Description:
    This routine puts the display value into the device.

Arguments:
    
    value - The value to be written to the device.
    
Return Value:

    HRESULT

--*/
{
    BYTE sevenSegment = 0;
    HRESULT hr;

    if (value >= ARRAYSIZE(g_NumberToMask)) {
        return E_INVALIDARG;
    }


    sevenSegment = g_NumberToMask[value];
    hr = m_pDeviceIoControl->DeviceIoControlSync(
                         IOCTL_OSRUSBFX2_SET_7_SEGMENT_DISPLAY,
                         &sevenSegment,
                         sizeof(BYTE),
                         NULL,
                         0,
                         NULL
                         );

    return hr;
}

Remarks

You can also send an IOCTL asynchronously by using the DeviceIoControlAsync method. In that case, you must implement the IDeviceRequestCompletionCallback interface.

Samples

Custom Driver Access Sample

White papers

Windows Store device app Design Guide for Specialized Devices

Other resources

Device Experience for Specialized Devices

Device Experience for Windows 8