Step 3: Control

Items for control points to invoke actions on UPnP devices with SOAP the Simple Object Access Protocol. More...

PUPNP_Api int	UpnpGetServiceVarStatus (UpnpClient_Handle Hnd, const char *ActionURL_const, const char *VarName_const, DOMString *StVar)
	Queries the state of a state variable of a service on another device.
PUPNP_Api int	UpnpGetServiceVarStatusAsync (UpnpClient_Handle Hnd, const char *ActionURL_const, const char *VarName_const, Upnp_FunPtr Fun, const void *Cookie_const)
	Queries the state of a variable of a service, generating a callback when the operation is complete.
PUPNP_Api int	UpnpSendAction (UpnpClient_Handle Hnd, const char *ActionURL_const, const char *ServiceType_const, const char *DevUDN_const, IXML_Document *Action, IXML_Document **RespNodePtr)
	Sends a message to change a state variable in a service.
PUPNP_Api int	UpnpSendActionEx (UpnpClient_Handle Hnd, const char *ActionURL_const, const char *ServiceType_const, const char *DevUDN_const, IXML_Document *Header, IXML_Document *Action, IXML_Document **RespNodePtr)
	Sends a message to change a state variable in a service.
PUPNP_Api int	UpnpSendActionAsync (UpnpClient_Handle Hnd, const char *ActionURL_const, const char *ServiceType_const, const char *DevUDN_const, IXML_Document *Act, Upnp_FunPtr Fun, const void *Cookie_const)
	Sends a message to change a state variable in a service, generating a callback when the operation is complete.
PUPNP_Api int	UpnpSendActionExAsync (UpnpClient_Handle Hnd, const char *ActionURL_const, const char *ServiceType_const, const char *DevUDN_const, IXML_Document *Header, IXML_Document *Act, Upnp_FunPtr Fun, const void *Cookie_const)
	Sends a message to change a state variable in a service, generating a callback when the operation is complete.

Detailed Description

Items for control points to invoke actions on UPnP devices with SOAP the Simple Object Access Protocol.

Control is Step 3 in UPnP networking. Control comes after addressing (Step 0) where devices get a network address, after discovery (Step 1) where control points find interesting device(s), and after description (Step 2) where control points learn about device capabilities. Control is independent of eventing (Step 4) where control points listen to state changes in device(s). Through control, control points invoke actions on devices and poll for values. Control and eventing are complementary to presentation (Step 5) where control points display a user interface provided by device(s).

Function Documentation

UpnpGetServiceVarStatus()

PUPNP_Api int UpnpGetServiceVarStatus	(	UpnpClient_Handle	Hnd,
		const char *	ActionURL_const,
		const char *	VarName_const,
		DOMString *	StVar
	)

Queries the state of a state variable of a service on another device.

Deprecated:

The use of this function is deprecated by the UPnP Forum.

This is a synchronous call.

A positive return value indicates a SOAP error code, whereas a negative return code indicates an SDK error code.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_FINISH: The SDK is already terminated or is not initialized.
• UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
• UPNP_E_INVALID_URL: ActionUrl is not a valid URL.
• UPNP_E_INVALID_DESC: The XML document was not found or it does not contain a valid XML description.
• UPNP_E_INVALID_PARAM: StVarVal is not a valid pointer or VarName or ActionUrl is a nullptr.
• UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.
• UPNP_SOAP_E_INVALID_VAR: The given variable is invalid according to the device.

Parameters

[in]	Hnd	The handle of the control point.
[in]	ActionURL_const	The URL of the service.
[in]	VarName_const	The name of the variable to query.
[out]	StVar	The pointer to store the value for VarName. The SDK allocates this string and the caller needs to free it using ixmlFreeDOMString.

Definition at line 2896 of file upnpapi.cpp.

Here is the call graph for this function:

UpnpGetServiceVarStatusAsync()

PUPNP_Api int UpnpGetServiceVarStatusAsync	(	UpnpClient_Handle	Hnd,
		const char *	ActionURL_const,
		const char *	VarName_const,
		Upnp_FunPtr	Fun,
		const void *	Cookie_const
	)

Queries the state of a variable of a service, generating a callback when the operation is complete.

Deprecated:

The use of this function is deprecated by the UPnP Forum.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_FINISH: The SDK is already terminated or is not initialized.
• UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
• UPNP_E_INVALID_URL: The ActionUrl is not a valid URL.
• UPNP_E_INVALID_PARAM: VarName, Fun or ActionUrl is not a valid pointer.
• UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the control point.
[in]	ActionURL_const	The URL of the service.
[in]	VarName_const	The name of the variable to query.
[in]	Fun	Pointer to a callback function to be invoked when the operation is complete.
[in]	Cookie_const	Pointer to user data to pass to the callback function when invoked.

Definition at line 2832 of file upnpapi.cpp.

Here is the call graph for this function:

UpnpSendAction()

PUPNP_Api int UpnpSendAction	(	UpnpClient_Handle	Hnd,
		const char *	ActionURL_const,
		const char *	ServiceType_const,
		const char *	DevUDN_const,
		IXML_Document *	Action,
		IXML_Document **	RespNodePtr
	)

Sends a message to change a state variable in a service.

This is a synchronous call that does not return until the action is complete.

Note that a positive return value indicates a SOAP-protocol error code. In this case, the error description can be retrieved from RespNode. A negative return value indicates an SDK error.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_FINISH: The SDK is already terminated or is not initialized.
• UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
• UPNP_E_INVALID_URL: ActionUrl is not a valid URL.
• UPNP_E_INVALID_ACTION: This action is not valid.
• UPNP_E_INVALID_DEVICE: DevUDN is not a valid device.
• UPNP_E_INVALID_PARAM: ServiceType, Action, ActionUrl, or RespNode is not a valid pointer.
• UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the control point sending the action.
[in]	ActionURL_const	The action URL of the service.
[in]	ServiceType_const	The type of the service.
[in]	DevUDN_const	This parameter is ignored and must be a nullptr.
[in]	Action	The DOM document for the action.
[out]	RespNodePtr	The DOM document for the response to the action. The SDK allocates this document and the caller needs to free it.

Definition at line 2538 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

UpnpSendActionEx()

PUPNP_Api int UpnpSendActionEx	(	UpnpClient_Handle	Hnd,
		const char *	ActionURL_const,
		const char *	ServiceType_const,
		const char *	DevUDN_const,
		IXML_Document *	Header,
		IXML_Document *	Action,
		IXML_Document **	RespNodePtr
	)

Sends a message to change a state variable in a service.

This is a synchronous call that does not return until the action is complete.

Note that a positive return value indicates a SOAP-protocol error code. In this case, the error description can be retrieved from RespNode. A negative return value indicates an SDK error.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_FINISH: The SDK is already terminated or is not initialized.
• UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
• UPNP_E_INVALID_URL: ActionUrl is not a valid URL.
• UPNP_E_INVALID_ACTION: This action is not valid.
• UPNP_E_INVALID_DEVICE: DevUDN is not a valid device.
• UPNP_E_INVALID_PARAM: ServiceType, Action, ActionUrl, or RespNode is not a valid pointer.
• UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the control point sending the action.
[in]	ActionURL_const	The action URL of the service.
[in]	ServiceType_const	The type of the service.
[in]	DevUDN_const	This parameter is ignored and must be a nullptr.
[in]	Header	The DOM document for the SOAP header. This may be a nullptr if the header is not required.
[in]	Action	The DOM document for the action.
[out]	RespNodePtr	The DOM document for the response to the action. The SDK allocates this document and the caller needs to free it.

Definition at line 2586 of file upnpapi.cpp.

Here is the call graph for this function:

UpnpSendActionAsync()

PUPNP_Api int UpnpSendActionAsync	(	UpnpClient_Handle	Hnd,
		const char *	ActionURL_const,
		const char *	ServiceType_const,
		const char *	DevUDN_const,
		IXML_Document *	Act,
		Upnp_FunPtr	Fun,
		const void *	Cookie_const
	)

Sends a message to change a state variable in a service, generating a callback when the operation is complete.

See UpnpSendAction() for comments on positive return values. These positive return values are sent in the event struct associated with the UPNP_CONTROL_ACTION_COMPLETE event.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_FINISH: The SDK is already terminated or is not initialized.
• UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
• UPNP_E_INVALID_URL: ActionUrl is an invalid URL.
• UPNP_E_INVALID_DEVICE: DevUDN is an invalid device.
• UPNP_E_INVALID_PARAM: Either Fun is not a valid callback function or ServiceType, Act, or ActionUrl is a nullptr.
• UPNP_E_INVALID_ACTION: This action is not valid.
• UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the control point sending the action.
[in]	ActionURL_const	The action URL of the service.
[in]	ServiceType_const	The type of the service.
[in]	DevUDN_const	This parameter is ignored and must be a nullptr.
[in]	Act	The DOM document for the action to perform on this device.
[in]	Fun	Pointer to a callback function to be invoked when the operation completes.
[in]	Cookie_const	Pointer to user data that to be passed to the callback when invoked.

Definition at line 2634 of file upnpapi.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

UpnpSendActionExAsync()

PUPNP_Api int UpnpSendActionExAsync	(	UpnpClient_Handle	Hnd,
		const char *	ActionURL_const,
		const char *	ServiceType_const,
		const char *	DevUDN_const,
		IXML_Document *	Header,
		IXML_Document *	Act,
		Upnp_FunPtr	Fun,
		const void *	Cookie_const
	)

Sends a message to change a state variable in a service, generating a callback when the operation is complete.

See UpnpSendAction() for comments on positive return values. These positive return values are sent in the event struct associated with the UPNP_CONTROL_ACTION_COMPLETE event.

Returns

An integer representing one of the following:

• UPNP_E_SUCCESS: The operation completed successfully.
• UPNP_E_FINISH: The SDK is already terminated or is not initialized.
• UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
• UPNP_E_INVALID_URL: ActionUrl is an invalid URL.
• UPNP_E_INVALID_DEVICE: DevUDN is an invalid device.
• UPNP_E_INVALID_PARAM: Either Fun is not a valid callback function or ServiceType, Act, or ActionUrl is a nullptr.
• UPNP_E_INVALID_ACTION: This action is not valid.
• UPNP_E_OUTOF_MEMORY: Insufficient resources exist to complete this operation.

Parameters

[in]	Hnd	The handle of the control point sending the action.
[in]	ActionURL_const	The action URL of the service.
[in]	ServiceType_const	The type of the service.
[in]	DevUDN_const	This parameter is ignored and must be a nullptr.
[in]	Header	The DOM document for the SOAP header. This may be a nullptr if the header is not required.
[in]	Act	The DOM document for the action to perform on this device.
[in]	Fun	Pointer to a callback function to be invoked when the operation completes.
[in]	Cookie_const	Pointer to user data that to be passed to the callback when invoked.

Definition at line 2720 of file upnpapi.cpp.

Here is the call graph for this function: