/MEng/System/Runtime/USBHID

ClassPath:	MEng.System.Runtime.USBHID
Parent ClassPath:	MEng.Object
Copyable:	No
Final:	Yes

MEng.System.Runtime.USBHID provides access to HID style USB devices. Though USB devices can be quite complex, many of them only need a very simple interface, in which your read or write small, fixed sized buffers. Many of the simple peripherals of a computer of this source (e.g. keyboards, mice, tablets, touch screens, etc...) so this class of USB device is called HID, for 'Human Interface Device'.

But the device doesn't actually need to be such an interface device. Any USB device which has simple interfacing requirements can use this scheme, and there are a good number of them that do. This class provides the means to open such devices, read buffers from, and write buffers to such HID devices.

HID devices will define a fixed size, usually quite small like 8 bytes or so, buffer for data read/write, and all data written or read will be placed within a buffer of this size, usually with any unused bytes zeroed out. The methods below allow you to indicate how many bytes to read or write on each call, but it will almost always be the same size for a given device. So be sure that you don't just write the bytes you have, but that you put them into a buffer of the size required for the particular device.

USB devices are identified by a pair of id numbers, a vendor id and a product id. A vendor id represents a particular company and each company can have one on or more product ids for their various USB based devices. So you will open the device by passing the ids of the device type you are interested in.

 

Nested Classes:

Enum=USBHIDErrors
    CloseFailed    : "";
    DevNotFound    : "No device with ids %(1)/%(2) was found";
    OpenFailed     : "";
    ReadFailed     : "";
    WriteFailed    : "";
EndEnum;

This enumerated type provides the errors that this class can throw. Some of them don't have any text since they are just assigned the text of the underlying C++ error that caused them.

 

Constructors:

Constructor();

There is just a default constructor available.

 

Final, Const Methods:

FindDevice
(
    [In]    MEng.Card2  VendorId
    , [In]  MEng.Card2  ProductId
    , [Out] MEng.String ToFind
)   Returns MEng.Boolean;

This method will check to see if a particular device is present in the system and, if so, it will return the 'device path', which is a unique identifier for the device. The path is not used by CML, but it could be useful for debugging purposes.

If the device exists, the return will be True, then it should be safe to call Open(), but it is always possible that the open will still fail because the device is opened by some other application and does not support multiple sessions.

 

Final, Non-Const Methods:

Close();

This method will close the device if it is open. If the device is not open, it will have no effect. The device will be closed when the object is dropped, but it is preferable that you close it when you know you will no longer need it.

Though it is unlikely, if some error were to occur while closing the device, the CloseFailed exception will be thrown.

Open(In] MEng.Card2 VendorId, [In] MEng.Card2 ProductId);

This method will open the device with the passed vendor and product id, if such a device is present. If no such device is found, or an error occurs while trying to open it, the OpenFailed exception will be thrown.

Read
(
    [Out]  MEng.System.Runtime.Membuf ToFill
    , [In] MEng.Card4                 Count
    , [In] MEng.Card4                 WaitFor
    , [In] MEng.Boolean               ThrowIfTO
)   Returns Boolean;

This method will read a packet of Count bytes from the device, and put the results in the ToFill buffer. The buffer will be expanded to sufficient size if required. This method will wait for up to WaitFor milliseconds before giving up.

If the read times out (i.e. no response from the device in the indicated WaitFor period), then what happens depends on the ThrowIfTO parameter. If True, then the ReadFailed exception will be thrown. If False, then the method will just return True or False to indicate whether it got a packet or timed out.

If the read fails for any other reason besides a timeout, the ReadFailed exception will always be thrown.

Note that HID devices have a fixed packet size, so the indicate Count must always be read. There is no in between for HID devices. Either you get a full buffer's worth, or something is wrong and the read will timeout because it didn't get a full packet in the time indicated.

Write
(
    In]    MEng.System.Runtime.Membuf ToWrite
    , [In] MEng.Card4                 Count
    , [In] MEng.Card4                 WaitFor
);

This method will write a packet of Count bytes to the device, waiting for up to WaitFor milliseconds for the device to accept the data before giving up. If the write fails (including timing out) then the WriteFailed exception is thrown.