1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:    

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef CMCEMEDIASTREAM_H

    22 #define CMCEMEDIASTREAM_H

    23 

    24 // INCLUDES

    25 #include <e32std.h>  	

    26 #include <e32base.h>

    27 #include <mcedefs.h>

    28 

    29 // DATA TYPES

    30 typedef TUint TMceMediaType;

    31  

    32 // FORWARD DECLARATIONS

    33 class CMceComMediaStream;

    34 class TMceFactory;

    35 class TMceMediaStreamFactory;

    36 class RWriteStream;

    37 class RReadStream;

    38 class CDesC8Array;

    39 class MDesC8Array;

    40 class CMceSession;

    41 class TMceIds;

    42 class TMceEvent;

    43 class TMceMediaId;

    44 class CMceManager;

    45 class CMceSession;

    46 class CMceMediaSource;

    47 class CMceMediaSink;

    48 class MMceComSerializationContext;

    49 class CMceFileSource;

    50 class CMceCodec;

    51 

    52 // CLASS DECLARATION

    53 

    54 /**

    55 * Base class for MCE media streams.

    56 *

    57 * MCE Media stream represents stream of data negotiated between two terminals.

    58 * Streams may transfer any data.

    59 *

    60 * Enabling or disabling of a stream is not a local operation, but it requires

    61 * always signalling. Thus, these operation require always to be completed by

    62 * calling CMceSession::UpdateL() function.

    63 *

    64 *  @lib mceclient.lib

    65 */

    66 class CMceMediaStream : public CBase

    67 	{

    68 	public: // Stream states

    69 

    70 	    enum TState

    71 	        {

    72 	        EUninitialized,       // Stream is created

    73 	        EInitialized,         // Stream is initialized

    74 	        EBuffering,           // Stream is buffering

    75 	        EIdle,                // Stream is not receiving RTP

    76 	        EStreaming,           // Stream is streaming

    77 	        EDisabled,            // Stream is explicitly disabled

    78 	        ENoResources,         // Stream has no needed resources to stream

    79 	        ETranscodingRequired, // Stream requires non-realtime transcoding

    80 	        ETranscoding          // Stream is transcoding in non-realtime

    81 	        };

    82 	        

    83 	public: // Destructor

    84 

    85 	    /**

    86 	    * Destructor.

    87 	    */

    88 		IMPORT_C ~CMceMediaStream();

    89 

    90 	public: // Functions

    91 	

    92 	    /**

    93 	    * Gets the state of the stream.

    94 	    * @return the current state of the stream

    95 	    */

    96 	    IMPORT_C CMceMediaStream::TState State() const;

    97 

    98 	    /**

    99 	    * Returns the type of the stream.

   100 	    * @return The type of the stream.

   101 	    */

   102 		IMPORT_C TMceMediaType Type() const;

   103 

   104 	    /**

   105 		* Configures media stream by updating SDP media lines. 

   106 		* In order to get complete update, whole session must be 

   107 		* updated causing sending of re-invite.

   108 	    * @param aMediaSDPLines, application specific SDP media lines for

   109 		*		 the stream. Ownership is transferred.

   110 	    */

   111 		IMPORT_C void SetMediaAttributeLinesL( CDesC8Array* aMediaSDPLines );

   112 		

   113 		/**

   114 		* Gets attribute lines of the media.

   115 		* @return array of media attribute lines, owneship is transferred.

   116 		*/

   117 		IMPORT_C MDesC8Array* MediaAttributeLinesL();

   118 

   119 		/** 

   120 	    * Sets local media port

   121 	    * @param aLocalMediaPort, local port for the media

   122 	    */

   123 	    IMPORT_C void SetLocalMediaPortL(TUint aLocalMediaPort); 

   124 	    

   125 	    /**

   126 	    * Gets the local media port.

   127 	    * @return Local port used for media.

   128 	    */

   129 	    IMPORT_C TUint LocalMediaPort() const;

   130 	    

   131 	    /**

   132 	    * Gets the session this stream belongs to, if exists. The

   133 	    * ownership is not transfered.

   134 	    * @return Session object

   135 	    */

   136 		IMPORT_C CMceSession* Session() const;

   137 	              

   138 

   139 	public: // Local stream control

   140 

   141 	    /**

   142 	    * Enables streaming explicitly.

   143 	    */

   144 	    virtual void EnableL(); 

   145 

   146 	    /**

   147 	    * Disables streaming explicitly.

   148 	    */

   149 		virtual void DisableL(); 

   150 		

   151 		/**

   152 	    * Returns the state of the stream.

   153 	    * @return ETrue if enabled, EFalse if disabled.

   154 	    */

   155     	IMPORT_C TBool IsEnabled() const;

   156 

   157 		/**

   158 	    * Sets state of stream

   159 	    * @param aState the state

   160 	    */

   161 	    TBool SetState( TState aState );

   162 

   163     public: // Source and sink functions

   164 

   165         /**

   166         * Adds source to the stream. CMceMediaStream can only

   167         * have one source at a time. Ownership of passed source is transferred.

   168         * However, the same source can be also passed to other streams resulting

   169         * that streams share ownership of the source. Passing NULL source will

   170         * remove source from stream.

   171         * In some cases the source might contain a codec. The codec is derived

   172         * to the stream when such source is added to the stream. 

   173         * Derived codec will get automatically highest preference.

   174         * @param aSource source to be added to the stream; ownership is 

   175         *        transferred

   176         */

   177         IMPORT_C void SetSourceL( CMceMediaSource* aSource );

   178 

   179         /**

   180         * Adds sink to the stream. CMceMediaStream can have

   181         * many sinks at a time. Ownership of passed sink is transferred.

   182         * However, the same sink can be also passed to other streams resulting

   183         * that streams share ownership of the sink.

   184         * @param aSink sink to be added to the stream; ownership is transferred

   185         */

   186         IMPORT_C void AddSinkL( CMceMediaSink* aSink );

   187 

   188         /**

   189         * Gets source of the stream. Returns NULL if source is not set.

   190         * @return source of the stream; ownership is not transferred

   191         */

   192         IMPORT_C CMceMediaSource* Source() const;

   193 

   194         /**

   195         * Gets array of sinks of the stream.

   196         * @return array of sinks

   197         */

   198         IMPORT_C const RPointerArray<CMceMediaSink>& Sinks() const;

   199 

   200         /**

   201         * Removes sink from the stream.

   202         * @post aSink cannot be used anymore and contents of 

   203         *       previously returned sink array (CMceMediaStream::Sinks())

   204         *       are not anymore valid

   205         * @param aSink sink to be removed from the stream

   206         */

   207         IMPORT_C void RemoveSinkL( CMceMediaSink& aSink );

   208 

   209     public: // Binding opposite way stream

   210 

   211         /**

   212         * Binds opposite direction stream to this stream.

   213         * @param aStream another stream to be bind to the stream; 

   214         *        ownership is transferred

   215         */

   216         IMPORT_C void BindL( CMceMediaStream* aStream );

   217 

   218         /**

   219         * Gets opposite direction stream of this stream.

   220         * @return opposite direction stream

   221         */

   222         IMPORT_C CMceMediaStream& BoundStreamL() const;

   223 

   224         /**

   225         * Checks if opposite direction stream is set.

   226         * @return ETrue if opposite direction stream is set; 

   227         *         otherwise EFalse

   228         */

   229         IMPORT_C TBool BoundStream() const;

   230 

   231     public: // from MMceComSerializableMedia

   232 

   233 

   234         /**

   235         * Returns serialization id

   236         * @return serialization id

   237         */

   238         TUint64 SerializationId() const;

   239         

   240         /**

   241         * Internalizes flat data

   242         * @param aReadStream read stream

   243         */

   244         void InternalizeFlatL( RReadStream& aReadStream );

   245 

   246         /**

   247         * Externalizes flat data

   248         * @param aWriteStream write stream

   249         */

   250         void ExternalizeFlatL( RWriteStream& aWriteStream );

   251         

   252         /**

   253         * Internalizes

   254         * @param aSerCtx context for serialization

   255         */

   256         virtual void InternalizeL( MMceComSerializationContext& aSerCtx );

   257         

   258         /**

   259         * Externalizes

   260         * @param aSerCtx context for serialization

   261         */

   262         virtual void ExternalizeL( MMceComSerializationContext& aSerCtx );

   263 

   264 

   265 public:// internal serialization

   266 	    

   267         /**

   268         * Adds source, during serialization, to the stream.

   269         * @param aSerCtx serialization context

   270         */

   271         void SetSourceL( MMceComSerializationContext& aSerCtx );

   272 

   273         /**

   274         * Adds sink, during serialization, to the stream.

   275         * @param aSerCtx serialization context

   276         */

   277         void AddSinkL( MMceComSerializationContext& aSerCtx );

   278 	    

   279 	    /**

   280 	    * Factory

   281 	    * @return factory

   282 	    */

   283 	    TMceFactory BaseFactory() const;

   284 

   285 	    /**

   286 	    * Factory

   287 	    * @return factory

   288 	    */

   289 	    static TMceMediaStreamFactory Factory();

   290 

   291 	public: //internal

   292 

   293 	    /**

   294 	    * Checks if this is binder (biding owner)

   295 	    * @return ETrue if this is binder (biding owner)

   296 	    */

   297 		TBool Binder() const;

   298 		

   299 	    /**

   300 	    * ID 

   301 	    * @return ID

   302 	    */

   303 		TMceMediaId Id() const;

   304 

   305 	    /**

   306 	    * Initializes 

   307 	    * @param aParent the parent

   308 	    * @param aDiscardUnusedCodecs

   309 	    */

   310 	    virtual void InitializeL( CMceSession& aParent, TBool aDiscardUnusedCodecs );

   311 	    

   312 	    /**

   313 	    * Initializes 

   314 	    * @param aManager the manager. Ownership is NOT transferred

   315 	    * @param aSession the Session.

   316 	    */

   317 	    virtual void InitializeL( CMceManager* aManager, CMceSession& aSession );

   318 	    

   319 	    /**

   320 	    * Called when stream is added to session

   321 	    */

   322 	    virtual void AddedL();

   323 	    

   324 	    /**

   325 	    * Called file source wants to synchronized with stream

   326 	    * @param aFile the file source

   327 	    */

   328         virtual void SynchronizeWithFileL( CMceFileSource& aFile ) = 0;

   329         

   330         /**

   331         * Searches for codec matching with input codec instance or sdp name

   332         * @param aCodec the search term

   333         * @return matching codec or NULL if not found

   334         */

   335         virtual CMceCodec* FindCodec( CMceCodec& aCodec ) = 0;

   336         

   337       /**

   338 	    * Arranges codec priority order based on codecs preference values.

   339 	    * @param aDiscardUnusedCodecs ETrue if all disabled codecs should

   340 	    *        be removed from the stream

   341 	    */

   342         virtual void ReorderCodecsByPreferenceL( TBool aDiscardUnusedCodecs ) = 0;

   343         

   344         /**

   345         * Return codecs of stream.

   346         * @return list of codecs in the stream.

   347         */

   348         virtual const RPointerArray<CMceCodec>& BaseCodecs() = 0;

   349         

   350         /**

   351         * Returns pointer to the bound stream and NULL if no bound

   352         * stream exists.

   353         * @return bound stream

   354         */

   355 	    CMceMediaStream* Bound() const;

   356 	    

   357 	    /**

   358 	    * Gets the flat data

   359 	    * @return flat data

   360 	    */

   361 	    CMceComMediaStream* FlatData();

   362 	    

   363 	public://event handling & update

   364 

   365 	    /**

   366 	    * Traversal event handler

   367 	    * @param aEvent the event

   368 	    * @return status, if event was consumed or not or object needs update

   369 	    */

   370 	    virtual TInt EventReceivedL( TMceEvent& aEvent );

   371 	    

   372 	    /**

   373 	    * Called after update

   374 	    */

   375 	    virtual void Updated();

   376 	    

   377 	    /**

   378 	    * Handles possible media errors.

   379 	    * @return ETrue, if media error occured and was handled.

   380 	    */

   381 	    TBool HandleMediaError( TState aState, TBool aIsEnabled, TInt aError );

   382 	    

   383 	    

   384 	protected:

   385 

   386 	    /**

   387 	    * C++ default constructor.

   388 	    */

   389 		CMceMediaStream();

   390 

   391 	    /**

   392 	    * Second-phase constructor

   393 	    * @param aFlatData flat data container

   394 	    */

   395 		void ConstructL( CMceComMediaStream* aFlatData );

   396 		

   397 		/**

   398 		* Search for codec inside given codec array

   399 		* @param aCodecs array of codecs

   400 		* @param aCodec search term

   401 		* @return matching codec or NULL if not found

   402 		*/

   403 		CMceCodec* FindCodec( const RPointerArray<CMceCodec>& aCodecs, 

   404                               CMceCodec& aCodec );

   405 

   406 

   407 	private:

   408 

   409 	    /**

   410 	    * Handles event

   411 	    * @param aEvent the event

   412 	    * @return status, if event was consumed or not or object needs update

   413 	    */

   414 	    TInt HandleEvent( TMceEvent& aEvent );

   415 

   416 	    /**

   417 	    * one-way bind

   418 	    * @param aStream another stream to be bind to the stream.

   419 	    */

   420 	    void DoBindL( CMceMediaStream* aStream );

   421 	    

   422 	    /**

   423 	    * Deletes sink

   424 	    * @param aIndex index of sink in the array

   425 	    */

   426         void DeleteSink( TInt aIndex );

   427         

   428 	    /**

   429 	    * Deletes source

   430 	    */

   431     	void DeleteSource();

   432 	    

   433 

   434 	protected: // NOT owned data

   435 				

   436 	    /**

   437 	     * session

   438 	     */

   439 		CMceSession* iSession;

   440 		

   441 	protected: // owned data

   442 

   443 	    /**

   444 	     * flat data container

   445 	     */

   446 		CMceComMediaStream* iFlatData;

   447 

   448 	    /**

   449 	     * linked stream. Owned if iLinkOwner is ETrue

   450 	     */

   451 	    CMceMediaStream* iLinkedStream;

   452 	        

   453 	    /**

   454 	     * source

   455 	     */

   456 		CMceMediaSource* iSource;

   457 		

   458 	    /**

   459 	     * sinks

   460 	     */

   461 		RPointerArray<CMceMediaSink> iSinks;

   462 		

   463     private: // Reserved for future use

   464     

   465         TAny* iReserved;       

   466 

   467 		//for testing

   468 

   469 	    MCE_UNIT_TEST_DEFS	

   470 

   471 	};

   472 

   473 

   474 #endif