Still Image

[This is preliminary documentation and subject to change.]

The Still Image application programming interface (API) is the first phase of a standardized interface that Microsoft® is producing to implement support for still-image acquisition devices. The following sections cover the concepts and use of Still Image:

  • About Still Image
  • Using Still Image
  • Still Image Reference


About Still Image

The Still Image (STI) application programming interface (API) is a standardized interface for acquiring digital still images from devices that are primarily used to capture still images. Examples of devices that can be accessible through the Still Image API are:

  • Flatbed scanners. Scanners with an automatic document feeder, transparency adapter, or other options (such as a "start" button).
  • Sheet fed scanners. Scanners with paper-inserted detection mechanism.
  • Handheld scanners.
  • Still-image digital cameras. Cameras with stored images and associated data such as thumbnails and audio.

Currently, support for still-image acquisition devices is provided through individual independent hardware vendor (IHV) solutions. These implementations can vary significantly. The current version of the Still Image API is the first phase of a standardized interface Microsoft is producing that implements support for still-image acquisition devices.

Further information is provided in the following topics:

  • Data Acquisition Models
  • Advantages of Still Image
  • Still Image Availability


Data Acquisition Models

Applications typically control still-image acquisition devices through imaging APIs such as TWAIN or ISIS. For the most part, applications that utilize these APIs function under the pull model of data acquisition. In the pull model, you locate and select a source of data. The application then uses the imaging API to acquire data from the device. In effect, the application pulls data from the device toward itself. The following figure illustrates the pull model of data acquisition.

Microsoft Still Image API supports the use of both the pull model and the push model of data acquisition. Using the push model, still image devices can notify applications of their status. You then use the standard TWAIN or ISIS APIs to acquire data. The following figure shows the push model of data acquisition.

The advantage of the push model of data acquisition is that it significantly simplifies the user model. The user model is the manner in which the user interacts with the image capture system. Under the push model of image capture, you only need to activate the image capture device to initiate image capture. When the device is activated, it generates a push model event. This in turn causes the appropriate application to be launched, and, depending on the application, image capture to be initiated. If it is already running, you simply need to select Rescan from the application's menu system to acquire more images.

This simplified user model enables developers to create hardware/software combinations that operate much more intuitively. For example, a kiosk for creating security badges has a very intuitive user model under the push model of data acquisition. You only need to step up to the kiosk and press a button on the digital camera or kiosk to take a picture for the badge. The kiosk's digital camera generates a device event. The device event in turn launches an application to acquire the data and produce the badge. The only action that you need take in the process is to press a button. Under the pull model of data acquisition, you would have had to interact with a graphical user interface (GUI).


Advantages of Still Image

Incorporating Still Image (STI) into applications has the following advantages:

  • Still Image implements both pull and push models. Unlike traditional still-image device control APIs, STI allows both the pull and push models of data acquisition.
  • Still Image standardizes device interfaces. Still-image device control APIs are extremely device dependent. STI standardizes the interfaces to still-image acquisition devices. This frees application developers from having to write specialized code for all devices that they support.
  • Still Image simplifies the user model. Specialized applications can have a more intuitive user interface.
  • Still Image does not require a change in application architecture. Normally, the conversion to the push model of data acquisition would require a major change in the software architecture of application programs. Enhancing applications to use Still Image requires only minimal changes to existing programs. In the vast majority of cases, current software architectures would not be changed by a conversion to STI.


Still Image Availability

Still Image is available in the Microsoft® Windows NT® 5.0 operating system, and the Microsoft Windows® 98 operating system. It is not available for Microsoft MS-DOS®, Windows 3.1, Windows 95 or Windows NT 4.0.


Using Still Image

Several aspects are involved with using Still Image (STI).

  • Registering An Application with Still Image
  • Still Image Architecture
  • Making An Application Still Image-Aware


Registering An Application with Still Image

Once an STI-compatible application is installed, it must be registered as push model-aware with the STI API. This can be done in one of two ways:

  1. The install program can call RegisterLaunchApplication.
  2. The application itself can call RegisterLaunchApplication the first time it runs.

Either way, the application must be registered using the IStillImage::RegisterLaunchApplication function. Once that has been done, you must manually connect the application to device events by using the Still Image Control Panel.

When an application that has registered itself as push model-aware is uninstalled, it must remove its information from the Still Image system. The STI function UnRegisterLaunchApplication removes this information.


Still Image Architecture

Developing STI-aware applications does not require a comprehensive knowledge of its inner workings. However, an overview of the STI architecture aids in understanding the use of the STIAPI. A major design goal of this architecture is to reduce the software investment an application developer must make to support image acquisition devices. It is intended to allow application developers to focus on application features, rather than hardware controls.

The STI architecture has several components:

  • Still Image-Aware Applications
  • Imaging APIs
  • Still Image Run-Time Components
  • Still Image API

Note STI can take advantage of color management systems, such as the Microsoft Image Color Management (ICM) 2.0, if they are present. However, since color management systems are not part of the STI architecture, they are not shown in the figure.

The following figure illustrates the STI architecture.


Still Image-Aware Applications

Two primary types of applications use still digital images. These are:

  1. Applications that edit image data. Adobe Photoshop or Microsoft PictureIt!™ are examples of this type of application.
  2. Applications that are used for authoring documents that include image data but cannot edit the image data. Typical applications of this type are word processors such as Microsoft Word, or presentation applications such as Microsoft PowerPoint®.


Imaging APIs

Most applications that can control image acquisition devices use the TWAIN, ISIS, or Adobe Systems Acquire interfaces. None of these APIs directly support the push model of data acquisition. All are based on the pull model. STI allows the use of these Imaging APIs to acquire data. However, STI-aware applications may also use the push model of data acquisition.


Still Image Run-Time Components

The STI system is composed of three run-time components:

  • Event Monitor
  • Control Center
  • Control Panel

The STI architecture components provide the following services for use by the Still Image Control Panel, the Still Image Control Center, and Still Image-aware applications:

  • Maintain the event types that are associated with devices. These events are identified by the IHV as push events for their device.
  • Dispatch push events to the Control Center.
  • Maintain a list of all push model-aware applications.
  • Launch or notify an application on behalf of the Control Center and provide information to the application as to which device and event initiated the notification.

Still Image Event Monitor

The Event Monitor maintains a list of active push model devices. Devices have a capability that indicates they support push model events. When devices are installed or removed, they can be added or deleted to the Event Monitor's device list using Plug And Play messages. They can also be added or deleted by the STI Control Panel.

The Event Monitor opens all devices that support the push model. The device is opened in control mode. All devices that are opened in control mode are opened for push model events. Since the Event Monitor should be the only component receiving push model events, the Event Monitor is the only component able to open the devices in control mode. Other software, such as application programs, can open the devices in data mode. When a device is opened in data mode, it is functioning under the pull model of data acquisition. The Event Monitor does not place a restriction on the number of programs that open a device in data mode.

The Event Monitor waits for events on all open image acquisition devices. Currently, few devices are capable of actually generating an event directly from the device when data transfer has been initiated. In most cases, a separate thread within the Still Image Event Monitor simulates this behavior by polling the device and causing an event when the device becomes active.

The Event Monitor directs device events to the Control Center.

Still Image Control Center

The Control Center implements a specific policy for how device push events are interpreted. The Control Center uses the list of applications registered as being push model-aware, and the list of those applications that are running.

It also maintains a list of device events that are associated with applications. You create the list that associates device events and applications with the Still Image Control Panel. Registering an application as push model-aware using the IStillImage::RegisterLaunchApplication function does not connect it with particular device events. You must create the association between a device event and an application with the Control Panel. If this is not done, the application will not receive push events from a device.

When the device event occurs, the Control Center launches the application associated with that device event. The application is launched with arguments of Event:event_name and Device:STI_device_friendly_name on the command line. However, the application doesn't parse these arguments off the command line. Instead, there is a method called IStillImage::GetSTILaunchInformation that returns the device event and the device-friendly name.

The control center uses the following simple policy to dispatch device events:

  • Upon receiving a device event from the Event Monitor, the Control Center obtains the subset of all registered applications you have selected to respond to this device event. This list is referred to as PREFERREDAPPS. The Control Center maintains this information.
  • If there are PREFERREDAPPS selected for this device event and PREFERREDAPPS has only one item, it is launched. Otherwise, a dialog box containing PREFERREDAPPS is displayed and you select the application to be launched.
  • Otherwise, you are informed that no application is associated with the event. If this is the case, the device has essentially been disabled for push model behavior.

In the current release, the Control Panel only allows one of the registered application to be selected. You will never see a dialog box asking you to choose one of several applications. This restriction will be removed in future releases.

Still Image Control Panel

The STI Control Panel provides you with a common interface for directing some of the Control Center behavior. These behaviors include:

  • Enumerate devices. Lists the installed still-image devices.
  • Add or remove devices. Still-image devices may be added or removed.
  • Test devices. Allows verification of still-image device installation and operation.
  • Configure or control devices. For each device, the Control Center adds a Microsoft or vendor property sheet to the Control Panel. The property sheet allows you to alter the behavior of the Control Center.
  • Associate device events with applications. Using the Control Panel, you select a device and one of the push model events for this device. Given this device and event pair, you then select the subset of push model aware-applications to which the event will be directed. In this way, the control panel is used to associate device events with applications

Application programs should not have to access the STI Control Panel. When an image acquisition device is installed, a property page for the device is added to the control panel. The property page is supplied by the vendor. You use it to manually associate device events with applications.


Still Image API

Applications use the Still Image API functions to gain access to Still Image features. An application does not need to communicate directly with the Event Monitor, the Control Center, or the Control Panel. The Control Center launches an application that is associated with a device event. That is the only communication that it has with an application. The application gets the launch information it needs by calling the IStillImage::GetSTILaunchInformation function.


Making An Application Still Image-Aware

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);
}


Still Image Reference

This reference section contains an alphabetical listing of the Still Image API. The API functions and interface methods are:

IStillImage::GetDeviceValue

IStillImage::GetSTILaunchInformation

IStillImage::RegisterLaunchApplication

IStillImage::UnRegisterLaunchApplication

StiCreateInstance


IStillImage::GetDeviceValue

The IStillImage::GetDeviceValue function is used to obtain information from the registry that has been associated with an image acquisition device API such as TWAIN or ISIS.

HRESULT GetDeviceValue(
  LPWSTR pwszDeviceName,
  LPWSTR pValueName,
  LPDWORD pType,
  LPBYTE pData,
  LPDWORD cbData
);

Parameters

pwszDeviceName
Pointer to the friendly device name of the still-image device that caused the event. The device friendly name is retrieved when IStillImage::GetSTILaunchInformation is called. See the code fragment in the section entitled Making An Application Still Image-Aware.

Pointer to a string that represents the name of the value tag. It is the key that will be used with GetDeviceValue to lookup the ancillary data. The defined device values that are defined and reserved by Microsoft :

STI_DEVICE_VALUE_TWAIN_NAME
The data associated with this registry key is the name of the TWAIN device.
STI_DEVICE_VALUE_ISIS_NAME
The data associated with this registry key is the name of the ISIS device.
STI_DEVICE_VALUE_ICM_PROFILE
The data associated with this registry key is the file name of the ICM device profile for the device.
STI_DEVICE_VALUE_DEFAULT_LAUNCHAPP
The data associated with this registry key is the name of the default launch application for events on the device.
pValueName
Pointer to a string that will be filled with information from the registry that has been associated with an image acquisition device API.
pType
Pointer to a variable that receives the key's value type. The value returned through this parameter will be one of the following.
Value | Meaning
REG_BINARY | Binary data in any form.
REG_DWORD | A 32-bit number.
REG_DWORD_LITTLE_ENDIAN | A 32-bit number in little-endian format (same as REG_DWORD). In little-endian format, the most significant byte of a word is the high-order byte. This is the most common format for computers running Windows NT and Windows 95.
REG_DWORD_BIG_ENDIAN | A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order byte.
REG_EXPAND_SZ | A null-terminated string that contains unexpanded references to environment variables (for example, "%PATH%"). It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.
REG_LINK | A Unicode symbolic link.
REG_MULTI_SZ | An array of null-terminated strings, terminated by two null characters.
REG_NONE | No defined value type.
REG_RESOURCE_LIST | A device-driver resource list.
REG_SZ | A null-terminated string. It will be a Unicode or ANSI string depending on whether you use the Unicode or ANSI functions.

The pType parameter can be NULL if the type is not required.

pData
Pointer to a buffer that receives the value's data. This parameter can be NULL if the data is not required.
cbData
Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pData parameter. When the function returns, this variable contains the size of the data copied to pData.

If the buffer specified by pData parameter is not large enough to hold the data, the function returns the value ERROR_MORE_DATA, and stores the required buffer size, in bytes, into the variable pointed to by cbData.

If pData is NULL, and cbData is non-NULL, the function returns S_OK, and stores the size of the data, in bytes, in the variable pointed to by cbData. This lets an application determine the best way to allocate a buffer for the value key's data.

If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, then pData will also include the size of the terminating null character.

The cbData parameter can be NULL only if pData is NULL.

Return Values

If the function succeeds, the return value is S_OK.

If the function fails because the buffer specified by pData parameter is not large enough to hold the data, the return value is ERROR_MORE_DATA.

If the function fails for another reason, the return value is the appropriate COM error.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in sti.h.
Import Library: Included as a resource in sti.dll.

See Also

Still Image Overview, Making An Application Still Image-Aware


IStillImage::GetSTILaunchInformation

The IStillImage::GetSTILaunchInformation method is used to determine if an application was launched by a push model device event. It is also used to retrieve the device event information.

HRESULT GetSTILaunchInformation(
  LPWSTR pwszDeviceName,
  DWORD pdwEventCode,
  LPWSTR pwszEventName
);

Parameters

pwszDeviceName
If the application was launched by a push model event by means of the Control Center, this will be set to the friendly device name of the device which caused the event.
pdwEventCode
Reserved for future use.
pwszEventName
If the application was launched by a push model event from the Control Center, this will be set to the name of the event. This name is supplied by the vendor of the image acquisition device. It is the same string that is used in the Events tab of the STI Control Panel property page for the device.

Return Values

If the application was launched by the Control Center in response to a device event, this function will return S_OK, and the device event information will be stored in the function arguments.

If the application was not launched by the STI Control Center in response to a device event, this function will return a COM error code.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in sti.h.
Import Library: Included as a resource in sti.dll.

See Also

Still Image Overview, Making An Application Still Image-Aware


IStillImage::RegisterLaunchApplication

The IStillImage::RegisterLaunchApplication method puts an application in the Control Center's list of currently running applications that are push model aware.

HRESULT RegisterLaunchApplication(
  LPWSTR pwszAppName,
  LPWSTR pwszCommandLine
);

Parameters

pwszAppName
Pointer to a null-terminated string containing the name of the application. This name will be used in the control panel property sheet where you associate applications with device events.
pwszCommandLine
Pointer to a null-terminated string containing the full path to the executable file for this application. Additional command line arguments can be appended to this command.

Return Values

If the function succeeds, the return value is S_OK.

If the function fails, the return value is the appropriate COM error.

Remarks

This function must be called after an application is launched. It tells the Control Center to add the application to its list of currently running push model-aware applications.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in sti.h.
Import Library: Included as a resource in sti.dll.

See Also

Still Image Overview, Making An Application Still Image-Aware


IStillImage::UnRegisterLaunchApplication

The IStillImage::UnRegisterLaunchAppliction method removes the application from the Control Center's list of push model-aware applications. Once this function has executed, the application no longer receives device events.

HRESULT UnRegisterLaunchApplication(
  PSTI pSti,
  LPWSTR pwszAppName
);

Parameters

pSti
Pointer to the IStillImage interface object.
pwszAppName
The name that the application used when it registered itself using RegisterLaunchApplication.

Return Values

If the function succeeds, the return value is S_OK.

If the function fails, the return value is the appropriate COM error.

See Also

Still Image Overview, Making An Application Still Image-Aware


StiCreateInstance

The StiCreateInstance function is used to obtain a pointer to the IStillImage interface. All other Still Image functions are called through the pointer obtained from this function. Calling this function can be done instead of calling CoCreateInstance and Initialize.

HRESULT StiCreateInstance(
  HINSTANCE hinst,
  DWORD dwVer,
  PSTI *ppSti,
  LPUNKNOWN punkOuter
);

Parameters

hinst
Instance handle to the application or DLL that is creating the IStillImage object.

STI uses this value to determine whether the application or DLL has been certified.

dwVer
Version number of the Sti.h header file that was used. This value must be STI_VERSION. STI uses this value to determine for what version of STI the application or DLL was designed.
ppSti
Pointer to a pointer to the IStillImage interface. This is an output parameter. When the function returns, this parameter contains a pointer to an IStillImage interface if the function is successful.
punkOuter
Pointer to controlling unknown for COM aggregation, or 0 if the interface is not aggregated. Most callers will pass 0.

Note If aggregation is requested, the object returned in *ppSti is a pointer to an IUnknown rather than an ISti, as required by COM aggregation.

Return Values

If the function succeeds, the return value is S_OK.

If the function fails, the return value is the appropriate COM error.

Remarks

Calling this function with punkOuter = NULL is equivalent to creating the object with CoCreateInstance(&CLSID_Sti, punkOuter, CLSCTX_INPROC_SERVER, &IID_ISti, ppSti); then initializing it with Initialize.

Calling this function with punkOuter != NULL is equivalent to creating the object with CoCreateInstance(&CLSID_Sti, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, ppSti). The aggregated object must be initialized manually.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in sti.h.
Import Library: Included as a resource in sti.dll.

See Also

Still Image Overview, Making An Application Still Image-Aware


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.