UPnP APIs

Overview of the UPnP APIs technology.

To develop UPnP APIs, you need these headers:

• upnp.h
• upnphost.h

For programming guidance for this technology, see:

• UPnP APIs

Functions

Abort The Abort method stops an asynchronous load operation started by IUPnPDescriptionDocument::LoadAsync.
AddCallback The AddCallback method registers an application's callback with the UPnP framework.
AddRequestHeaders Adds the supplied HTTP header to an HTTP request.
Advise The Advise method is invoked by the device host to begin receiving events from the hosted service.
AsyncOperationComplete AsyncOperationComplete callback method provides notification of the completion of an asynchronous I/O operation.
BeginInvokeAction BeginInvokeAction method invokes an action on a device in asynchronous mode. Additionally, if a delayed SCPD download and event subscription is opted-in, and it has not taken place already, this method will initiate SCPD download.
BeginQueryStateVariable BeginQueryStateVariable method initiates an asynchronous request for the state variable value from a specific service.
BeginSCPDDownload BeginSCPDDownload method initiates the asynchronous download of an Service Control Protocol Description (SCPD) document.
BeginSubscribeToEvents BeginSubscribeToEvents initiates event subscription in asynchronous mode and registers the application callback with the UPnP framework.
CancelAsyncFind The CancelAsyncFind method cancels an asynchronous search.
CancelAsyncOperation CancelAsyncOperation method cancels a pending asynchronous operation initiated by the BeginInvokeAction, BeginQueryStateVariable, BeginSubscribeToEvents, or BeginSCPDDownload methods.
CreateAsyncFind The CreateAsyncFind method creates an asynchronous search operation.
DeviceAdded The DeviceAdded method is invoked by the UPnP framework to notify the application that a device has been added to the network.
DeviceAddedWithInterface The DeviceAddedWithInterface method is invoked by the UPnP framework to notify the application that a device has been added to the network.
DeviceByUDN The DeviceByUDN method returns the device with the specified unique device name (UDN) contained within the loaded description document.
DeviceRemoved The DeviceRemoved method is invoked by the UPnP framework to notify the application that a device has been removed from the network.
EndInvokeAction EndInvokeAction method retrieves the results of a previous BeginInvokeAction operation and retrieves the resultant output arguments.
EndQueryStateVariable EndQueryStateVariable method retrieves the results of a previous BeginQueryStateVariable operation and retrieves the resultant service-specific state variable value.
EndSCPDDownload EndSCPDDownload method retrieves the results of a previous asynchronous download of an Service Control Protocol Description (SCPD) document.
EndSubscribeToEvents EndSubscribeToEvents method retrieves the results of a previous BeginSubscribeToEvents operation.
FindByType The FindByType method searches synchronously for devices by device type or service type.
FindByUDN The FindByUDN method searches synchronously for a device by its unique device name (UDN).
get__NewEnum The _NewEnum property specifies either the IEnumVARIANT or IEnumUnknown enumerator interface for the collection. (IUPnPDevices.get__NewEnum)
get__NewEnum The _NewEnum property specifies either the IEnumVARIANT or IEnumUnknown enumerator interface for the collection. (IUPnPServices.get__NewEnum)
get_Children The Children property specifies all the child devices of the device. The devices are stored in an IUPnPDevices collection.
get_Count The Count property specifies the number of devices in the collection.
get_Count The Count property specifies the number of services in the collection.
get_Description The Description property specifies a human-readable summary of the device's functionality.
get_FriendlyName The FriendlyName property specifies the device display name for the device.
get_HasChildren The HasChildren property specifies whether the device has any child devices.
get_Id The Id property specifies the service ID for the service.
get_IsRootDevice The IsRootDevice property specifies whether the device is the topmost device in the device tree.
get_Item The Item property specifies the IUPnPDevice interface for a device, identified by the UDN, in the collection.
get_Item The Item property specifies the IUPnPService interface for a service, identified by the service ID, in the collection.
get_LastTransportStatus For queries related to evented variables, the LastTransportStatus property specifies the HTTP status of the last IUPnPService::InvokeAction operation.
get_LoadResult The LoadResult property specifies the success or failure code of a completed load operation.
get_ManufacturerName The ManufacturerName property specifies a human-readable form of the manufacturer name of the device.
get_ManufacturerURL The ManufacturerURL property specifies the URL for the manufacturer's Web site.
get_ModelName The ModelName property specifies a human-readable form of the model name of the device.
get_ModelNumber The ModelNumber property specifies a human-readable form of the model number of the device.
get_ModelURL The ModelURL property specifies the URL for a Web page that contains model-specific information for the device.
get_ParentDevice The ParentDevice property specifies the parent of the device.
get_PresentationURL The PresentationURL property specifies the presentation URL for a Web page that controls the device.
get_ReadyState The ReadyState property specifies the status of the document load operation.
get_RootDevice The RootDevice property specifies the topmost device in the device tree. The root device represents a physical object.
get_SerialNumber The SerialNumber property specifies a human-readable form of the serial number of the device.
get_Services The Services property specifies the list of services provided by the device.
get_ServiceTypeIdentifier The ServiceTypeIdentifier property specifies the service type identifier for the device.
get_Type The Type method specifies the device type uniform resource identifier (URI) for the device.
get_UniqueDeviceName The UniqueDeviceName property specifies the unique device name (UDN) of the device. A UDN is unique; no two devices can have the same UDN.
get_UPC The UPC property specifies a human-readable form of the product code.
GetAddressFamily The GetAddressFamily method retrieves the current value of the address family flag of the Device Finder object.
GetDocument Retrieves the XML device description document for a UPnP device.
GetDocument GetDocument method retrieves the Service Control Protocol Description (SCPD) document for a service object.
GetDocumentURL The GetDocumentURL method returns the URL from which the device description document can be loaded.
GetDocumentURL GetDocumentURL method retrieves the Service Control Protocol Description (SCPD) URL for a service object. Using this URL, the UPnP control point can download the complete SCPD document.
GetDwordValue The GetDwordValue method gets a 4-byte value that provides information about either a request or requester.
GetGuidValue The GetGuidValue method currently is not supported.
GetServiceObject The GetServiceObject method is used to obtain the IDispatch pointer to a specific service object. The device host invokes this method once per service, the first time it receives a request for a service.
GetStringValue The GetStringValue method gets a string that provides information about either a request or requester.
GetUniqueDeviceName The GetUniqueDeviceName method retrieves the UDN for the specified device.
IconURL The IconURL method returns a URL from which an icon of the specified format can be loaded.
Initialize The Initialize method is used to initialize the device. The device host invokes this method.
InvokeAction Invokes a method on the device.
Load The Load method loads a document synchronously. This method does not return control to the caller until the load operation is complete.
LoadAsync The LoadAsync method loads a document asynchronously. This method returns control to the caller immediately, and uses the specified callback to notify the caller when the operation is complete.
LoadComplete The LoadComplete method is invoked when the UPnP framework has finished loading a device description.
OnStateChanged The OnStateChanged method sends an event to the device host with the list of DISPIDs of the state variables that have changed. The device host must query the service object to obtain the new value for each state variable that has changed.
OnStateChangedSafe The OnStateChangedSafe method sends an event to the device host with the list of DISPIDs that have changed. The device host must query the service object to obtain the new value for each state variable that has changed.
QueryStateVariable The QueryStateVariable method returns the value of the specified service's state variable.
RegisterDevice The RegisterDevice method registers a device with the device host. The device information is stored by the device host. Then, the device host returns a device identifier and publishes and announces the device on the network.
RegisterDeviceProvider The RegisterDeviceProvider method registers a device provider with the device host. The device provider is not published on the network. Instead, it creates devices dynamically and registers them using RegisterRunningDevice.
RegisterRunningDevice The RegisterRunningDevice method registers a running device with the device host.
ReregisterDevice The ReregisterDevice method re-registers a device with the device host. The device information is stored by the device host. Then, the device host returns a device identifier and publishes and announces the device on the network.
ReregisterRunningDevice The ReregisterRunningDevice method re-registers a running device with the device host.
RootDevice The RootDevice method returns the root device of the currently loaded document's device tree.
SearchComplete The SearchComplete method is invoked by the UPnP framework to notify the application that the initial search for network devices has been completed.
ServiceInstanceDied The ServiceInstanceDied method is invoked when a service is no longer sending events.
SetAddressFamily The SetAddressFamily method sets the address family flag of the Device Finder object, which uses this flag to filter the devices found.
SetServiceEnumProperty The SetServiceEnumProperty method is used to indicate opt-in to the delayed Service Control Protocol Description (SCPD) download and event subscription for the IUPnPService objects enumerated from the IUPnPServices object.
Start The Start method starts the device provider. The device host invokes this method after it loads the device provider This method performs any initialization required by the device provider.
StartAsyncFind The StartAsyncFind method starts an asynchronous search operation.
StateVariableChanged The StateVariableChanged method is invoked when a state variable has changed.
Stop The Stop method stops the device provider.
Unadvise The Unadvise method is invoked by the device host to stop receiving events. The device host passes in the same pointer that it did when it invoked the IUPnPEventSource::Advise method.
UnregisterDevice The UnregisterDevice method unregisters the device from the device host. A device is either temporarily or permanently unregistered.
UnregisterDeviceProvider The UnregisterDeviceProvider method permanently unregisters and unloads the device provider from the device host. The IUPnPDeviceProvider::Stop method is invoked.

Interfaces

IUPnPAddressFamilyControl The IUPnPAddressFamilyControl interface accesses the address family flag of the Device Finder object.
IUPnPAsyncResult The IUPnPAsyncResult interface is used to notify the UPnP control point of a completed asynchronous I/O operation.
IUPnPDescriptionDocument The IUPnPDescriptionDocument interface enables an application to load a device description.
IUPnPDescriptionDocumentCallback The IUPnPDescriptionDocumentCallback interface allows the UPnP framework to communicate the results of an asynchronous load operation to an application.
IUPnPDevice The IUPnPDevice interface enables an application to retrieve information about a specific device.
IUPnPDeviceControl The IUPnPDeviceControl interface is the central point of management for a device and its service objects.
IUPnPDeviceDocumentAccess The IUPnPDeviceDocumentAccess interface enables an application to obtain the URL of the device description document.
IUPnPDeviceDocumentAccessEx Provides a method to obtain the entire XML device description document for a specific device.
IUPnPDeviceFinder The IUPnPDeviceFinder interface enables an application to find a device.
IUPnPDeviceFinderAddCallbackWithInterface The IUPnPDeviceFinderAddCallbackWithInterface interface allows the UPnP framework to communicate to an application
IUPnPDeviceFinderCallback The IUPnPDeviceFinderCallback interface allows the UPnP framework to communicate the results of an asynchronous search to an application.
IUPnPDeviceProvider The IUPnPDeviceProvider interface allows a device provider to start and stop its processing.
IUPnPDevices The IUPnPDevices interface enumerates a collection of devices.
IUPnPEventSink The IUPnPEventSink interface allows a hosted service to send event notifications to the device host.
IUPnPEventSource The IUPnPEventSource interface allows the device host to manage event subscriptions for the hosted service.
IUPnPHttpHeaderControl Enables the caller to specify additional HTTP headers sent in HTTP requests to a device.
IUPnPRegistrar The IUPnPRegistrar interface registers the devices that run in the context of the device host.
IUPnPRemoteEndpointInfo The IUPnPRemoteEndpointInfo interface allows a hosted device to obtain information about a requester (that is, a control point) and the request.
IUPnPReregistrar The IUPnPReregistrar interface allows the application to re-register a UPnP-based device with the device host.
IUPnPService The IUPnPService interface enables an application to query state variables and invoke actions on an instance of a service.
IUPnPServiceAsync Use this interface to asynchronously query state variables and invoke actions on an instance of a service .
IUPnPServiceCallback The IUPnPServiceCallback interface is used to send event notifications to clients of Service objects.
IUPnPServiceDocumentAccess Use this interface to retrieve and provide the Service Control Protocol Description (SCPD) document to a UPnP control point application to expose actions supported by the service and provide information about state variables.
IUPnPServiceEnumProperty Use this interface to delay Service Control Protocol Description (SCPD) download and event subscription on the IUPnPService objects enumerated from the IUPnPServices object.
IUPnPServices The IUPnPServices interface enumerates a collection of services.