/*

* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

#ifndef __CXPSPACKETSUPPLIER_H__

#define __CXPSPACKETSUPPLIER_H__

#include <e32base.h>

#include "CXPSPacket.h"

#include "CXPSPktSinkObserver.h"

//

//	Class CXPSPacketSink

//	eXternal Packet Sink provides the functionality to rendering RTP media data 

//	along with the MMF controller. MMF Controller is used for control signals and

//  packet sink is used for RTP media data communication.

//

//  CXPSPacketSink provides APIs for media description and for sending packets

//	to the playback engine.

//

//

class CXPSPacketSink : public CBase

{

public:

    //

    // Creates packet sink

    //

    // Returns NULL on memory error

    // 

    static CXPSPacketSink* New();

    //

    // Virtual destructor

    //

    virtual ~CXPSPacketSink();

    //

    // Creates the symbian server with the specified name and 

    // waits for client connection.

    //

    // Parameters:

    //		ServerName	: Name of the server to be created.

    //		pObserver	: Observer for packet sink callbacks

    //

    // Returns KErrNone on success or system wide error otherwise

    // 

    //

    TInt Init(const TDesC& ServerName, MXPSPktSinkObserver* pObserver);

    //

    // AuthenticateClient sets the minimum capability that a client SHALL 

    // possess for connecting to the server.

    //

    // Note: 

    //		AuthenticateClient SHALL be invoked before the application

    //		issues a open URL on the MMF controller. OpenURL on controller 

    //		will result in a connect.

    //

    //		Init SHALL be called prior to this API invocation

    //

    // Parameters:

    //		aSecurityPolicy	: Security policy

    // 

    // Returns KErrNone on success or system wide error otherwise

    //

    //

    //

    TInt AuthenticateClient(TSecurityPolicy& aSecurityPolicy);

    //

    // Sets the SDP info into the server.

    // 

    // Optional xps related sdp attributes

    //      Session Level Attribute

    //          XpsStreamSyncOffset: Inter stream synchronization offset value 

    //                               in msec. This makes sure that XPS packet 

    //                               reading between streams can be offset only

    //                               by specified value. Default: 1000 msec

    //

    //		DisableVideoClock: Flag to disable clock source for video playback.

    // 	

    //      Media Level Attribute

    //          XpsHdrBufSize:  XPS transport Header buffer size between XPS server

    //                          & XPS client. Default: 512 bytes

    //          XpsPyldBufSize: XPS transport payload buffer size between XPS server

    //                          & XPS client. Default: 4096 bytes

    //

    //

    // Note: 

    //		SetSessionDescription SHALL be invoked before the application

    //		issues a open URL on the MMF controller. OpenURL on controller 

    //		will result in a connect and query for SDP by the client

    //

    //		Init SHALL be called prior to this API invocation

    //    

    //    The stream number is based on the order of the streams (m=mediatype) in the

    //    SDP file. Currently only m=audio and m=video would be valid streams and id 

    //    would be assigned in increasing order starting with zero.

    //

    // Parameters:

    //		aSDPDesc	: Session description protocol message

    //		unNumStreams: Number of streams

    // 

    // Returns KErrNone on success or system wide error otherwise

    //

    //

    //

    TInt SetSessionDescription(TDesC8& aSDPDesc, TUint unNumStreams);

    //

    // Sets the session's output device mode. 

    // Audio, Video or other streams will use the bit mask to make a decision

    // on routing to external devices (eg., Bluetooth, TV-Out,etc)

    //

    // Note: 

    //      SetSecureOutputMode is an optional API and SHALL be invoked while

    //      playing protected content. Default behaviour is allow all ie., 

    //      no restrictions applied in routing streams to output devices.

    //

    //		Init SHALL be called prior to this API invocation

    // 

    //      SetSecureOutputMode can be called anytime after Init. If it is called

    //      after playback started then the Secure output settings will take effect 

    //      at the presentation time of the first packet enqueued after SetSecureOutputMode

    //      is called.

    //

    // Parameters:

    //		ulSecureOutBitMask	: 32-Bit mask representing the secure output mode

    //                            All bits zero will result in BLOCKING of unsecure 

    //                            output devices. (0x0) (eg. TV-Out will be blocked)

    //                            All bits one will result in allowing streams to 

    //                            render to both secure and unsecure output devices. 

    //                            (0xFFFFFFFF) Rest of the bit mask combinations 

    //                            are reserved for future use.

    // 

    // Returns KErrNone on success or system wide error otherwise

    //

    //

    //

    TInt SetSecureOutputMode(TUint32 ulSecureOutBitMask);

    //

    // Enqueues the packet on the packet sink. 

    // 

    // Parameters:

    //		unStreamId	: Stream identifier

    //		CXPSPacket	: transferred packet, XPS takes over ownership

    //

    // Returns KErrNone on success or system wide error otherwise. 

    //			Packet overflow scenario will result in KErrOverflow.

    //		    Application SHALL stop supplying more packets on receiving KErrOverflow. 

    //			Packet supply can be resumed after the callback from the packet sink.

    //          MXPSPacketSinkObserver::ResumePacketSupply API will be used to notify. 

    //

    //  NOTE:

    //      KErrOverflow return indicates that the slots are filled out. Current packet 

    //      has been enqueued and there are no slots for more packets. Packet supply 

    //      SHALL be resumed after observer callback (MXPSPktSinkObserver::RestorePacketSupply).

    //      KErrNotReady will be returned if packets are enqueued after overflow and before

    //      resume callback

    //			

    // 

    TInt Enqueue(TUint unStreamNumber, CXPSPacket* pPacket);

    //

    // Enqueues the packet on the packet sink. 

    // 

    // Parameters:

    //		unStreamId	: Stream identifier

    //		aHeaderInfo	: RTP header of the packet

    //		aPayloadData: RTP payload

    //

    // Returns KErrNone on success or system wide error otherwise. 

    //			Packet overflow scenario will result in KErrOverflow.

    //		    Application SHALL stop supplying more packets on receiving KErrOverflow. 

    //			Packet supply can be resumed after the callback from the packet sink.

    //          MXPSPacketSinkObserver::ResumePacketSupply API will be used to notify. 

    //

    //  NOTE:

    //      KErrOverflow return indicates that the slots are filled out. Current packet 

    //      has been enqueued and there are no slots for more packets. Packet supply 

    //      SHALL be resumed after observer callback (MXPSPktSinkObserver::RestorePacketSupply).

    //      KErrNotReady will be returned if packets are enqueued after overflow and before

    //      resume callback

    //			

    // 

    TInt Enqueue(TUint unStreamId, const TRtpRecvHeader& aHeaderInfo, const TDesC8& aPayloadData);

    //

    // StreamEnd indicates the end of given stream

    //

    // Paramaters:

    //		unStreamId	: Stream identifier

    //

    // Returns KErrNone on success or system wide error otherwise

    //

    // 

    TInt StreamEnd(TUint unStreamId);

    //

    // Configures the stream's buffering capability. Sets the 

    // queue to the size specified.

    //

    // Note:

    //		This API is optional. Packet sink will start with default values

    //

    // Paramaters:

    //		unStreamId	: Stream identifier

    //		unNumSlots	: Maximum number of packets that may be bufferred in

    //					  packet sink for the given stream

    //

    // Returns KErrNone on success or system wide error otherwise

    //

    // Warning: It is strongly recommended to use ConfigStreamBySize()

    // instead of ConfigStream()

    //

    TInt ConfigStream(TUint unStreamId, TUint unNumSlots);

    //

    // Configures the stream's buffering capability. Sets the 

    // queue to the heap size specified.

    //

    // Note:

    //		This API is optional. Packet sink will start with default values

    //      This API could be called during runtime to re-adjust the queue size

    //

    // Paramaters:

    //		unStreamId	        : Stream identifier

    //		unQueueSiezInBytes	: Maximum number of heap size that may be 

    //                    bufferred in packet sink for the given stream

    //

    // Returns KErrNone on success or system wide error otherwise

    //

    TInt ConfigStreamBySize(TUint unStreamId, TUint32 unQueueSiezInBytes);

    //

    // Resets the packet sink. Releases all the packets stored in packet sink

    // Does not affect the SDP or intialization attributes. It only cleans up the

    // bufferred packets on the packet sink

    //

    // Returns KErrNone on success or system wide error otherwise

    //

    // 

    TInt Reset();

    //

    // SetOverflowAutoManage instructs XPS whether to do buffer overflow control or not

    //

    // Paramaters:

    //		bIsOverflowAutoManaged: 

    //        ETrue: if XPS has no packet for one stream, and Helix is demanding 

    //               for it, XPS will drop 1 packet from any stream whose queue

    //               is full. It allows XPS client to push further packets into XPS 

    //               in the hope that required stream packet could come to XPS 

    //               eventually. This process repeats till XPS receives deired packet.

    //        EFalse:XPS dose not do buffer management described above

    //

    //      Note: If XPS client has single queue implementation, it is better to

    //            let XPS handle the overflow situation.

    //      

    //      Default: ETrue

    //

    // Returns: the previous status of Overflow Management

    //

    // 

    TBool SetOverflowAutoManage(TBool bIsOverflowAutoManaged);

private:

    // private member functions

    CXPSPacketSink();

private:

    // private data members

};

#endif // End of __CXPSPACKETSUPPLIER_H__