[This is preliminary documentation and subject to change.]
Existing applications must be revised to make use of the Still Image (STI) push model behavior.
An application can detect whether or not it was launched by the Control Center. If the IStillImage::GetSTILaunchInformation function return value indicates success, then the application was launched by the Control Center. An application, TWAIN data source, or other software can decide to reject using the device that caused the push model event. However, it must notify you in some manner as to why the device is not acceptable. This allows you to utilize the STI Control Panel to deselect this particular application for use with this device.
If the Control Center launched an application, the application may need additional information to locate the device by means of its imaging API. TWAIN and ISIS are the two imaging APIs for which Microsoft defines information. However, any imaging API can use the STI mechanism for obtaining additional information. On installation of the imaging API, an .inf file is used to place information into the registry that provides this supplementary information. A key/value string is used to specify this information, such as:
TWAIN="HP PictureScan 3.0"
ISIS="epson.pxw"
The application then uses the GetDeviceValue function to obtain the associated data.
Once a TWAIN data source has been loaded, it can obtain the device and event by the same IStillImage::GetSTILaunchInformation function since it is in the original address space. With this information, it can open the device and start communication. This provides a seamless transition from push event to application launch and image acquisition.
Once an application (or a TWAIN data source) has a device open, all events are sent to this application. The Control Center is not aware of device activity until the device is closed.
When an application is uninstalled, it needs to call UnRegisterLaunchApplication to remove the itself from the permanent list of push model-aware applications. You may not add or remove an application from the Control Panel. You may only select or deselect those applications to be associated with particular devices.
The following code fragment illustrates how an application can be made Still Image-aware.
Example code:
// call STI to find out whether we were launched by STI
HRESULT hres;
hres = StiCreateInstance(GetModuleHandle(NULL), STI_VERSION,
&g_pSti,NULL);
hres = g_pSti->RegisterLaunchApplication(L"MyApp",szModulePathW);
// Was this a STI launch?
// Call STI-API and get the device name, event and event code
WCHAR szDeviceName[65];
WCHAR szEventName[65];
char ActualDeviceName [256];
DWORD dwEventCode;
hres = g_pSti->GetSTILaunchInformation(szDeviceName,
&dwEventCode,
szEventName);
if (SUCCEEDED(hres))
{
DWORD val = 256, type;
g_pSti->GetDeviceValue(szDeviceName, STI_DEVICE_VALUE_TWAIN_NAME, &type,
(unsigned char*)&ActualDeviceName[0], &val);
}