IConnectionManager::PrepareForConnection (Compact 7)

3/12/2014

This method enables devices to prepare for an upcoming media transfer. Called immediately before a media transfer, its input parameters contain information about the upcoming transfer. The implementation uses this information and the internal state of the device to create virtual AVTransport and RenderingControl service instances, which it returns.

Syntax

virtual DWORD PrepareForConnection(
  LPCWSTR pszRemoteProtocolInfo,
  LPCWSTR pszPeerConnectionManager,
  long PeerConnectionID,
  DIRECTION Direction,
  long* pConnectionID,
  IAVTransport** ppAVTransport,
  IRenderingControl** ppRenderingControl
) = 0;

Parameters

• pszRemoteProtocolInfo
  [in] Specifies the protocol, network, and media format to be used when the content is transferred. The value of this parameter is the same as one of the entries in the list returned by the remote device's GetProtocolInfo action (GetProtocolInfo is exposed in the UPnP AV Framework by IConnectionManager::GetProtocolInfo). If the remote device does not provide the GetProtocolInfo action, this value is one of the entries in the protocol information list on this device. Corresponds to the A_ARG_TYPE_ProtocolInfo state variable.

• pszPeerConnectionManager
  [in] UPnP UDN and service ID of the ConnectionManager instance on the remote device. Control points that use the UPnP AV Framework can retrieve this value from the second parameter of MediaServerDevice::GetConnectionManager and MediaRendererDevice::GetConnectionManager. Corresponds to the A_ARG_TYPE_ConnectionManager state variable.

• PeerConnectionID
  [in] Connection ID value maintained by the remote ConnectionManager instance for this connection. Returns -1 if the remote connection ID is not known, either because this is the first of the paired calls to the PrepareForConnection action or because the remote device does not implement PrepareForConnection. Corresponds to the A_ARG_TYPE_ConnectionID state variable.

• Direction
  [in] If OUTPUT, the local device uses this connection to send content. If INPUT, the local device uses this connection to receive content. Corresponds to the A_ARG_TYPE_Direction state variable.

• pConnectionID
  [in, out] Pointer to an integer allocated by the caller that this method modifies to contain the connection ID for this connection on the local device. Corresponds to the A_ARG_TYPE_ConnectionID state variable.

• ppAVTransport
  [in, out] Pointer to an IAVTransport implementation that implements the virtual AVTransport service on the local device for this connection. Corresponds to the A_ARG_TYPE_AVTransportID state variable, except that instead of a numeric ID, the method returns a pointer to an IAVTransport object. Control points using this pointer must call IVirtualService::Release when the object is no longer needed.

• ppRenderingControl
  [in, out] Pointer to an IRenderingControl implementation that implements the virtual RenderingControl service on the local device for this connection. Corresponds to the A_ARG_TYPE_ProtocolInfo state variable, except that instead of a numeric ID, the method returns a pointer to an IRenderingControl object. Control points using this pointer must call IVirtualService::Release when the object is no longer needed.

Return Value

Custom implementations can return appropriate error codes. If this method succeeds, it should return SUCCESS_AV. Otherwise, it should return an error code defined in WinError.h or UPnP.h, or one of the UPnP AV-specific return values specified in UPnPAVError, especially the following errors documented for this action in the ConnectionManager DCP documentation:

• ERROR_AV_UPNP_CM_INCOMPATIBLE_PROTOCOL
• ERROR_AV_UPNP_CM_INCOMPATIBLE_DIRECTION
• ERROR_AV_UPNP_CM_INSUFFICIENT_NET_RESOURCES
• ERROR_AV_UPNP_CM_LOCAL_RESTRICTIONS
• ERROR_AV_UPNP_CM_ACCESS_DENIED
• ERROR_AV_UPNP_CM_NOT_IN_NETWORK

The implementation of this method in IConnectionManagerImpl returns the errors in the following table. In addition, it returns any error returned by the custom IConnectionManagerImpl::CreateConnection implementation.

Remarks

This method corresponds to the ConnectionManager service's PrepareForConnection action.

The implementation of this method in IConnectionManagerImpl performs these tasks:

1. Calls IConnectionManagerImpl::CreateConnection to provide developers with a chance to perform any specific connection-preparation tasks.
2. Updates its internal connection data.
3. Raises an event by calling IEventSink::OnStateChanged with the CurrentConnectionIDs constant.
4. Uses the [out] parameters in the method signature to return the new connection ID and references to the IAVTransport and IRenderingControl objects that it has created.

Control point applications that call PrepareForConnection must call IVirtualService::Release on the IAVTransport and IRenderingControl pointers when the objects are no longer needed.

The AVTransport service's PrepareForConnection action is defined as optional in the UPnP AV DCP. The AV renderer sample implements PrepareForConnection, or does not, depending on the value of the CM_NO_PREPARE_FOR_CONNECTION preprocessor definition. If this constant is defined, the sample does not support PrepareForConnection; otherwise, the sample provides support for multiple connections. To see how this definition is used, examine ConnectionManager.cpp in the AV renderer sample's source directory.

For more information about the actions in the ConnectionManager service, including detailed information about when and how PrepareForConnection is used, see UPnP Forum AV Web site.

Requirements

See Also

Reference

IConnectionManager
IAVTransport
IConnectionManager::GetProtocolInfo
IConnectionManagerImpl
IConnectionManagerImpl::CreateConnection
IEventSink::OnStateChanged
IRenderingControl
IVirtualService::Release
MediaRendererDevice::GetConnectionManager
MediaServerDevice::GetConnectionManager
UPnPAVError