IWiaDevMgr::RegisterEventCallbackProgram method (wia_xp.h)

The IWiaDevMgr::RegisterEventCallbackProgram method registers an application to receive device events. It is primarily provided for backward compatibility with applications that were not written for WIA.

Syntax

HRESULT RegisterEventCallbackProgram(
  [in] LONG       lFlags,
  [in] BSTR       bstrDeviceID,
  [in] const GUID *pEventGUID,
  [in] BSTR       bstrCommandline,
  [in] BSTR       bstrName,
  [in] BSTR       bstrDescription,
  [in] BSTR       bstrIcon
);

Parameters

[in] lFlags

Type: LONG

Specifies registration flags. Can be set to the following values:

[in] bstrDeviceID

Type: BSTR

Specifies a device identifier. Pass NULL to register for the event on all WIA devices.

[in] pEventGUID

Type: const GUID*

Specifies the event for which the application is registering. For a list of valid event GUIDs, see WIA Event Identifiers.

[in] bstrCommandline

Type: BSTR

Specifies a string that contains the full path name and the appropriate command-line arguments needed to invoke the application. Two pairs of quotation marks should be used, for example, ""C:\Program Files\MyExe.exe" /arg1".

[in] bstrName

Type: BSTR

Specifies the name of the application. This name is displayed to the user when multiple applications register for the same event.

[in] bstrDescription

Type: BSTR

Specifies the description of the application. This description is displayed to the user when multiple applications register for the same event.

[in] bstrIcon

Type: BSTR

Specifies the icon that represents the application. The icon is displayed to the user when multiple applications register for the same event. The string contains the name of the application and the 0-based index of the icon (there may be more than one icon that represent application) separated by a comma. For example, "MyApp, 0".

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Use IWiaDevMgr::RegisterEventCallbackProgram to register for hardware device events of the type WIA_ACTION_EVENT. When an event occurs for which an application is registered, the application is launched and the event information is transmitted to the application.

Applications use the EnumRegisterEventInfo method to retrieve a pointer to an enumerator object for event registration properties.

An application can find whether an event is an action type or notification type (or both) event by examining the ulFlags value of a WIA_DEV_CAP structure returned by event enumeration.

Programs should only use the IWiaDevMgr::RegisterEventCallbackProgram method for backward compatibility with applications not written for the WIA architecture. New applications should use the Component Object Model (COM) interfaces provided by the WIA architecture. Specifically, they should call IWiaDevMgr::RegisterEventCallbackInterface or IWiaDevMgr::RegisterEventCallbackCLSID to register for device events.

Typically, this method is called by an install program or a script. The install program or script registers the application to receive WIA device events. When the event occurs, the application will be started by the WIA run-time system.

Requirements