Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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.

Note:
This method returns IAVTransportand IRenderingControlreferences. When control point code is finished with these objects, it must call IVirtualService::Releaseon each reference.

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::GetConnectionManagerand 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 IAVTransportimplementation 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 IAVTransportobject. Control points using this pointer must call IVirtualService::Releasewhen the object is no longer needed.

ppRenderingControl

[in, out] Pointer to an IRenderingControlimplementation 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 IRenderingControlobject. Control points using this pointer must call IVirtualService::Releasewhen 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 IConnectionManagerImplreturns the errors in the following table. In addition, it returns any error returned by the custom IConnectionManagerImpl::CreateConnectionimplementation.

Value Description

ERROR_AV_UPNP_CM_LOCAL_RESTRICTIONS

All available connection IDs are in use.

ERROR_AV_POINTER

At least one of pointers in the following list is NULL.

  • pszRemoteProtocolInfo

  • pszPeerConnectionManager

  • pConnectionID

  • ppAVTransport

  • ppRenderingControl

All of these pointers must point to valid memory locations.

ERROR_AV_OOM

There was not enough memory to complete connection preparation.

SUCCESS_AV

Connection preparation completed successfully.

Remarks

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

The implementation of this method in IConnectionManagerImplperforms these tasks:

  1. Calls IConnectionManagerImpl::CreateConnectionto 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::OnStateChangedwith the CurrentConnectionIDs constant documented in ConnectionManagerState.

  4. Uses the [out] parameters in the method signature to return the new connection ID and references to the IAVTransportand IRenderingControlobjects that it has created.

Control point applications that call PrepareForConnectionmust call IVirtualService::Releaseon the IAVTransportand IRenderingControlpointers 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 PrepareForConnectionis used, see UPnP AV DCP Documentation.

Requirements

Header av_upnp.h
Library Av_upnp.lib
Windows Embedded CE Windows CE 5.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also