IStillImageW::CreateDevice method (sti.h)

Article
03/13/2023

The IStillImage::CreateDevice method creates an instance of the COM object that defines the IStiDevice COM Interface, and returns a pointer to the interface.

Syntax

HRESULT CreateDevice(
  [in]           LPWSTR     pwszDeviceName,
                 DWORD      dwMode,
  [out]          PSTIDEVICE *pDevice,
  [in, optional] LPUNKNOWN  punkOuter
);

Parameters

[in] pwszDeviceName

Caller-supplied pointer to a string representing an internal device name, obtained by calling IStillImage::GetSTILaunchInformation or IStillImage::GetDeviceList.

dwMode

Caller-supplied constant value indicating the Transfer Modes in which the device is to be used. The following values are valid.

Mode	Description
STI_DEVICE_CREATE_BOTH	The device is being opened for both obtaining status and transferring data.
STI_DEVICE_CREATE_DATA	The device is being opened only for data transfers.
STI_DEVICE_CREATE_STATUS	The device is being opened only for obtaining status information.

[out] pDevice

Receives a pointer to the IStiDevice COM Interface.

[in, optional] punkOuter

Optional, caller-supplied pointer to the "controlling unknown" for object aggregation. See the following Remarks section.

Return value

If the operation succeeds, the method returns S_OK. Otherwise, it returns one of the STIERR-prefixed error codes defined in stierr.h.

Remarks

For an application to use the IStiDevice interface, it must first call IStillImage::StiCreateInstance to get a pointer to the IStillImage interface, then call IStillImage::CreateDevice to get a pointer to the IStiDevice interface. The pointer received in pDevice is used subsequently when calling IStiDevice methods, as illustrated in the sample still image code, to obtain access to the specified device.

If you want to create an aggregate COM object that includes IStiDevice, you must supply a pointer to the "controlling unknown" in punkOuter. In most cases you will not be creating an aggregate object, so punkOuter should be NULL. Object aggregation and the controlling unknown are described in the Microsoft Windows SDK documentation and in the Component Object Model Specification.

Requirements

Requirement	Value
Target Platform	Desktop
Header	sti.h (include Sti.h)