MagTek MAGTEK - Manual (Page 54)

MagTek Communications Protocol, Driver Reference Manual
48
DEVICE CHANNEL LIFE CYCLE
Devices are identified at the API level by names. The host application enumerates (gets the
name of) the available devices using the McpEnum function. On every subsequent call the
function returns a name of an MCP device connected and configured on the host computer. By
calling this function in a loop, an application can enumerate all devices.
The host application may use a hard-coded device name, a name obtained from the registry or
other configuration data, or it may ask the user to select a device from the list returned by
McpEnum. The application can establish a communication channel with the desired device, by
calling McpOpen with the device name (the device name can be any of the names returned by the
McpEnum function). McpOpen returns a device handle which the application uses on all
subsequent MCP function calls regarding this device.
Any application on the host computer may open any device. There is no limitation of the
number of the devices that one application can open but a device can be opened by no more than
one application at a time.
After opening the device, the host application can reestablish, or reset the channel by calling
McpReset. This function cancels any outstanding commands and restores the communication
channel to its initial state. The result of reset is the same as closing and re-opening the device,
except that the device handle remains the same. Using the McpReset operation is preferable to
closing and reopening the device.
PROPERTIES
Each device application can have its own set of properties. Generic commands can be supported
by devices that allow these properties to be retrieved and set. Each driver device instance also
has its own set of properties. The MCPAPI interface provides two functions, McpGet and
McpSet, which give an application the ability to get and set properties. These functions are
general purpose so that additional properties may be easily added in the future without modifying
the interface.
The MCP property interface allows the device application properties to be accessed through their
numeric property ID and Application ID. Device applications identify properties only by
numeric IDs as opposed to being specified by name due to thier limited amount of memory and
processing power.
The host application can access the driver device instance properties through the same set of
commands. These properties can be specified by name only as opposed to numeric IDs. See the
device instance properties section of this document for more details on these properties. Only
active-time driver properties can be modified by the application.