IConnectionManager::PrepareForConnection (Windows CE 5.0)
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 IAVTransport and IRenderingControl references. When control point code is finished with these objects, it must call IVirtualService::Release on each reference.
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 Values
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.
| 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.
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 IConnectionManagerImpl performs these tasks:
- Calls IConnectionManagerImpl::CreateConnection to provide developers with a chance to perform any specific connection-preparation tasks.
- Updates its internal connection data.
- Raises an event by calling IEventSink::OnStateChanged with the CurrentConnectionIDs constant documented in ConnectionManagerState.
- 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 AV DCP Documentation.
Requirements
OS Versions: Windows CE 5.0 and later.
Header: Av_upnp.h.
Link Library: Av_upnp.lib.
C++ Namespace: av_upnp.
See Also
IConnectionManager | IAVTransport | IConnectionManager::GetProtocolInfo | IConnectionManagerImpl | IConnectionManagerImpl::CreateConnection | IEventSink::OnStateChanged | IRenderingControl | IVirtualService::Release | MediaRendererDevice::GetConnectionManager | MediaServerDevice::GetConnectionManager | UPnPAVError
Send Feedback on this topic to the authors