IUPnPDeviceControl::Initialize method (upnphost.h)

Article
10/13/2021

The Initialize method is used to initialize the device. The device host invokes this method.

Syntax

HRESULT Initialize(
  [in] BSTR bstrXMLDesc,
  [in] BSTR bstrDeviceIdentifier,
  [in] BSTR bstrInitString
);

Parameters

[in] bstrXMLDesc

Specifies the full XML device description, as published by the device host. The device description is based on the template provided by the device.

[in] bstrDeviceIdentifier

Identifies the device to initialize. This is the same identifier returned by IUPnPRegistrar::RegisterDevice or IUPnPRegistrar::RegisterRunningDevice. It is also used to retrieve the UDN of the device using IUPnPRegistrar::GetUniqueDeviceName.

[in] bstrInitString

Specifies the initialization string used when this device was registered.

Return value

When implementing this method, return S_OK if the method succeeds. Otherwise, return one of the COM error codes defined in WinError.h.

Remarks

This method is invoked immediately after the device control object is instantiated. It must be invoked before IUPnPDeviceControl::GetServiceObject is invoked.

The difference between a running device and a non-running device is when the Initialize method is invoked.

For running devices, Initialize is invoked when IUPnPRegistrar::RegisterRunningDevice is invoked, and the initialization is completed before IUPnPRegistrar::RegisterRunningDevice returns.

For non-running devices, Initialize is not necessarily invoked when IUPnPRegistrar::RegisterDevice is invoked. Initialize is invoked when the first control or event request arrives.

The bstrDeviceIdentifier can also be used to call IUPnPRegistrar::GetUniqueDeviceName.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	None supported
Target Platform	Windows
Header	upnphost.h
DLL	Upnphost.dll