1 /*

     2  * Copyright (c) 2009 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: Telephony Multimedia Service

    15  *

    16  */

    17 

    18 #ifndef TMS_STREAM_H

    19 #define TMS_STREAM_H

    20 

    21 // Include files

    22 #include <glib.h>

    23 

    24 namespace TMS {

    25 

    26 // Forward declarations

    27 class TMSStreamObserver;

    28 class TMSSource;

    29 class TMSSink;

    30 class TMSEffect;

    31 class TMSStreamBody;

    32 class TMSFormat;

    33 class TMSBuffer;

    34 

    35 /**

    36  * TMSStream class

    37  *

    38  * TMSStream class represents either uplink or downlink stream associated with

    39  * a TMSCall.

    40  *

    41  * This class provides means for setting up and controlling telephony

    42  * multimedia streams associated with a Circuit Switching (CS) call or Packet

    43  * Switching (PS) such as IP call.

    44  *

    45  * TMSStream instances are created by TMSCall instance. Multiple TMSStream

    46  * instances (uplink and/or downlink streams) can be created. The TMS engine

    47  * does not limit the number of streams created per TMSCall object. However,

    48  * the combination of device policy and device run-time resources (both

    49  * software and hardware) may limit this use-case.

    50  *

    51  * TMSCall is a container which owns all its TMSStream instances. The client

    52  * has an option of creating and deleting individual streams. However, when a

    53  * TMSCall instance is deleted, all the streams associated with it are

    54  * automatically deleted as well.

    55  *

    56  * TMS ver 1.0.0.0:

    57  *  (1) An initialized stream will have one source, zero or one format,

    58  *  zero or more effects, and one or more sinks.

    59  *

    60  *  (2) In the initial version of the TMS implementation, the CS uplink and

    61  *  downlink streams will not control or communicate with the cellular modem.

    62  *  Also, the PS (IP) uplink and downlink streams will not handle network

    63  *  protocol. It is assumed that the TMS client will handle this functionality.

    64  *

    65  * States:

    66  *  (1) TMS_STREAM_UNINITIALIZED (initial state): The stream is alive but has

    67  *  not allocated all the resources it needs to function.

    68  *

    69  *  (2) TMS_STREAM_INITIALIZED: The stream has all the information required to

    70  *  acquire the media resources. Stream in this state will have most of the

    71  *  resources allocated, except the critical system resources, such as policy

    72  *  and/or hardware resources.

    73  *

    74  *  (3) TMS_STREAM_PAUSED: The stream has all the resources allocated, which may

    75  *  include critical system resources such as policy and/or hardware resources.

    76  *

    77  *  (4) TMS_STREAM_STARTED: The stream has all the resources allocated,

    78  *  including critical system resources such as policy and/or hardware resources

    79  *  and is active.

    80  *

    81  * Usage:

    82  * <code>

    83  * TMSFactory *iFactory;

    84  * TMSCall *iCall;

    85  * TMSStream *iUplink;

    86  * TMSStream *iDownlink;

    87  * gint err;

    88  *

    89  * err = TMSFactory::CreateFactory(iFactory);

    90  * err = iFactory->CreateCall(TMS_CALL_IP, iCall);

    91  * err = iCall->CreateStream(TMS_STREAM_UPLINK, iUplink);

    92  * err = iCall->CreateStream(TMS_STREAM_DOWNLINK, iDownlink);

    93  * // Configure CS uplink stream

    94  * iUplinkStream->AddObserver(*this);

    95  * iUplinkStream->AddSource(iMicSource);

    96  * iUplinkStream->AddSink(iModemSink);

    97  * iUplinkStream->AddEffect(iGainEffect); // To control mic gain

    98  * iUplinkStream->Init();

    99  * // Wait for state change callback

   100  * iUplinkStream->Play();

   101  * // Wait for state change callback

   102  * ...

   103  * // call terminated on the cell modem side, now signal multimedia system

   104  * iUplinkStream->Stop();

   105  * ...

   106  *  err = iCall->DeleteStream(iDownlink);

   107  *  err = iCall->DeleteStream(iUplink);

   108  *  err = iFactory->DeleteCall(iCall);

   109  * delete iFactory;

   110  *

   111  * </code>

   112  *

   113  * @lib tmsapi.lib

   114  *

   115  */

   116 class TMSStream

   117     {

   118 public:

   119 

   120     /**

   121      * Destructor

   122      */

   123     IMPORT_C ~TMSStream();

   124 

   125     /**

   126      * Add stream observer for this stream.

   127      *

   128      * Multiple observers can be added to a stream.

   129      *

   130      * This function can be called at any time. It is recommended to add

   131      * observer before calling Init() on stream. Otherwise, the observer may

   132      * miss a callback.

   133      *

   134      * A reference to the obsrvr is stored in the stream and TMSStreamEvent

   135      * function will be called when a stream event occurs. When stream is

   136      * deleted, all TMSStreamObserver references are automatically released.

   137      * The ownership of the obsrvr is still maintained by the client. Should

   138      * the client need to delete obsrvr before deleting stream, it should

   139      * remove all the obsrvr references from the stream by calling

   140      * RemoveObserver() method.

   141      *

   142      * @param  obsrvr

   143      *      Listener added to the stream.

   144      *

   145      * @param  user_data

   146      *      User data passed to the function.

   147      *

   148      * @return

   149      *      TMS_RESULT_SUCCESS if the obsrvr is added successfully to the list.

   150      *      TMS_RESULT_ALREADY_EXIST if obsrvr is already in the list.

   151      *

   152      */

   153     IMPORT_C gint AddObserver(TMSStreamObserver& obsrvr, gpointer user_data);

   154 

   155     /**

   156      * Remove stream observer from this stream.

   157      *

   158      * This function can be called at any time. It is recommended to remove

   159      * observer after calling Deinit() on stream. Oterwise, the observer may

   160      * receive callback that is alread dispatched.

   161      *

   162      * @param  obsrvr

   163      *      Listener to be removed from the stream.

   164      *

   165      * @return

   166      *      TMS_RESULT_SUCCESS if the obsrvr is removed successfully from the

   167      *      stream.

   168      *      TMS_RESULT_DOES_NOT_EXIST if the obsrvr is not on the list.

   169      *

   170      */

   171     IMPORT_C gint RemoveObserver(TMSStreamObserver& obsrvr);

   172 

   173     /**

   174      * Add source for this stream.

   175      *

   176      * This function can be called only when stream is in

   177      * TMS_STREAM_UNINITIALIZED state.

   178      *

   179      * After source is added to the stream successfully, ownership of the source

   180      * is vested in this stream. If the client wants to reuse the source, it

   181      * should call RemoveSource() to re-claim TMSSource ownership.

   182      *

   183      * @param  source

   184      *      Source object to be added to the stream.

   185      *

   186      * @return

   187      *      TMS_RESULT_SUCCESS if source is added successfully to the stream.

   188      *      TMS_RESULT_NULL_ARGUMENT if source is a NULL.

   189      *      TMS_RESULT_ALREADY_EXIST if source has already been added to the

   190      *      stream.

   191      *      TMS_RESULT_INVALID_STATE if stream is not

   192      *      in the TMS_STREAM_UNINITIALIZED state.

   193      *

   194      */

   195     IMPORT_C gint AddSource(TMSSource* source);

   196 

   197     /**

   198      * Remove source from this stream.

   199      *

   200      * This function can be called only when stream is in

   201      * TMS_STREAM_UNINITIALIZED state.

   202      *

   203      * After source is removed from the stream successfully, ownership of

   204      * source is re-claimed by the client.

   205      *

   206      * @param  source

   207      *      The source to remove.

   208      *

   209      * @return

   210      *      TMS_RESULT_SUCCESS if source is removed successfully from the

   211      *      stream.

   212      *      TMS_RESULT_NULL_ARGUMENT if source is a NULL.

   213      *      TMS_RESULT_DOES_NOT_EXIST if trying to remove the source that has

   214      *      not been added to stream.

   215      *      TMS_RESULT_INVALID_STATE if stream is not

   216      *      in the TMS_STREAM_UNINITIALIZED state.

   217      *

   218      */

   219     IMPORT_C gint RemoveSource(TMSSource* source);

   220 

   221     /**

   222      * Add sink to the stream.

   223      *

   224      * Multiple sinks of different types can be added to a stream.

   225      *

   226      * This function can be called only when stream is in

   227      * TMS_STREAM_UNINITIALIZED state.

   228      *

   229      * After sink is added to the stream successfully, ownership of the sink is

   230      * vested in the stream. If the client wants to reuse sink, it should call

   231      * RemoveSink() to re-claim TMSSink ownership.

   232      *

   233      * @param  sink

   234      *      Data sink to be added to the stream.

   235      *

   236      * @return

   237      *      TMS_RESULT_SUCCESS if sink is added successfully to the stream.

   238      *      TMS_RESULT_NULL_ARGUMENT if sink is a NULL.

   239      *      TMS_RESULT_ALREADY_EXIST if sink type is already added to the

   240      *      stream.

   241      *      TMS_RESULT_INVALID_STATE if stream is not

   242      *      in the TMS_STREAM_UNINITIALIZED state.

   243      *

   244      */

   245     IMPORT_C gint AddSink(TMSSink* sink);

   246 

   247     /**

   248      * Remove sink from the stream.

   249      *

   250      * This function can be called only when stream is in

   251      * TMS_STREAM_UNINITIALIZED state.

   252      *

   253      * After sink is removed from the stream successfully, ownership of the

   254      * sink is re-claimed by the client.

   255      *

   256      * @param  sink

   257      *      Dink to removed from the stream.

   258      *

   259      * @return

   260      *      TMS_RESULT_SUCCESS if sink is removed successfully from the stream.

   261      *      TMS_RESULT_NULL_ARGUMENT if sink is a NULL.

   262      *      TMS_RESULT_DOES_NOT_EXIST if trying to remove sink that has not

   263      *      been added to the stream.

   264      *      TMS_RESULT_INVALID_STATE if stream is not

   265      *      in the TMS_STREAM_UNINITIALIZED state.

   266      *

   267      */

   268     IMPORT_C gint RemoveSink(TMSSink* sink);

   269 

   270     /**

   271      * Set data format for the stream.

   272      *

   273      * This function can be called only when stream is in the

   274      * TMS_STREAM_UNINITIALIZED state.

   275      *

   276      * After format is added to the stream successfully, ownership of the

   277      * format is vested in this stream. If the client wants to reuse format,

   278      * it should call ResetFormat() to re-claim TMSFormat ownership.

   279      *

   280      * Note: In TMS Ver 1.0.0.0, setting data format for CS call is not

   281      * required.

   282      *

   283      * @param  format

   284      *      Data format to be set on the stream.

   285      *

   286      * @return

   287      *      TMS_RESULT_SUCCESS if format is set successfully on the stream.

   288      *      TMS_RESULT_NULL_ARGUMENT if format is a NULL.

   289      *      TMS_RESULT_ALREADY_EXIST if format is already set on the stream.

   290      *      TMS_RESULT_INVALID_STATE if stream is not

   291      *      in the TMS_STREAM_UNINITIALIZED state.

   292      *

   293      */

   294     IMPORT_C gint SetFormat(TMSFormat* format);

   295 

   296     /**

   297      * Remove data format from the stream.

   298      *

   299      * This function can be called only when stream is in the

   300      * TMS_STREAM_UNINITIALIZED state.

   301      *

   302      * After format is removed from the stream successfully, ownership of

   303      * the format object is re-claimed by the client.

   304      *

   305      * @param  format

   306      *      Data format to be removed from the stream.

   307      *

   308      * @return

   309      *      TMS_RESULT_SUCCESS if format is removed successfully from the

   310      *      stream.

   311      *      TMS_RESULT_NULL_ARGUMENT if format is a NULL.

   312      *      TMS_RESULT_DOES_NOT_EXIST if format is not currently set on the

   313      *      stream.

   314      *      TMS_RESULT_INVALID_STATE if stream is not in the

   315      *      TMS_STREAM_UNINITIALIZED state.

   316      *

   317      */

   318     IMPORT_C gint ResetFormat(TMSFormat* format);

   319 

   320     /**

   321      * Add an effect to the stream.

   322      *

   323      * Multiple effect objects of different types can be added to the stream.

   324      *

   325      * This function can be called only when stream is in the

   326      * TMS_STREAM_UNINITIALIZED state.

   327      *

   328      * After effect is added to the stream successfully, ownership of the

   329      * effect is vested in the stream. If the client wants to reuse the effect,

   330      * it shall call RemoveEffect() to re-claim TMSEffect ownership.

   331      *

   332      * @param  effect

   333      *      Stream effect to be added to the stream.

   334      *

   335      * @return

   336      *      TMS_RESULT_SUCCESS if effect is added successfully to the stream.

   337      *      TMS_RESULT_NULL_ARGUMENT if effect is a NULL.

   338      *      TMS_RESULT_ALREADY_EXIST if effect type is already added to the

   339      *      stream.

   340      *      TMS_RESULT_INVALID_STATE if stream is not in the

   341      *      TMS_STREAM_UNINITIALIZED state.

   342      *

   343      */

   344     IMPORT_C gint AddEffect(TMSEffect* effect);

   345 

   346     /**

   347      * Remove effect from the stream.

   348      *

   349      * This function can be called only when stream is in the

   350      * TMS_STREAM_UNINITIALIZED state.

   351      *

   352      * After effect is removed from the stream successfully, ownership of the

   353      * effect is re-claimed by the client.

   354      *

   355      * @param  effect

   356      *      Stream effect to be removed from the stream.

   357      *

   358      * @return

   359      *      TMS_RESULT_SUCCESS if effect is removed successfully from the

   360      *      stream.

   361      *      TMS_RESULT_NULL_ARGUMENT if effect is a NULL.

   362      *      TMS_RESULT_DOES_NOT_EXIST if trying to remove an effect that has

   363      *      not been added to the stream.

   364      *      TMS_RESULT_INVALID_STATE if stream is not in the

   365      *      TMS_STREAM_UNINITIALIZED state.

   366      *

   367      */

   368     IMPORT_C gint RemoveEffect(TMSEffect* effect);

   369 

   370     /**

   371      * Get current state of the stream.

   372      *

   373      * This function can be called at any time.

   374      *

   375      * Possible states are:

   376      *  TMS_STREAM_UNINITIALIZED,

   377      *  TMS_STREAM_INITIALIZED,

   378      *  TMS_STREAM_PAUSED,

   379      *  TMS_STREAM_STARTED.

   380 

   381      * @return

   382      *      Stream's current state.

   383      *

   384      */

   385     IMPORT_C gint GetState();

   386 

   387     /**

   388      * Get stream type.

   389      *

   390      * This function can be called at any time.

   391      *

   392      * The possible types are:

   393      *  TMS_STREAM_UPLINK

   394      *  TMS_STREAM_DOWNLINK

   395      *

   396      * @return

   397      *      Stream type indicating whether it is an uplink or downlink.

   398      *

   399      */

   400     IMPORT_C gint GetStreamId();

   401 

   402     /**

   403      * Get stream ID.

   404      *

   405      * This function can be called at any time.

   406      *

   407      * @return

   408      *      Unique ID of the stream.

   409      *

   410      */

   411     IMPORT_C gint GetStreamType();

   412 

   413     /**

   414      * Trigger stream to transition to the initialized state.

   415      *

   416      * This function can be called only when stream is in the

   417      * TMS_STREAM_UNINITIALIZED state.

   418      *

   419      * If Init() is called when stream is already in initialized state, the

   420      * request will be ignored and the function will return TMS_RESULT_SUCCESS.

   421      *

   422      * Upon stream's successful transition to initialized state, the stream will

   423      * be in the TMS_STREAM_INITIALIZED state.

   424      *

   425      * Before stream can transition to initialized state the following

   426      * objects must be added to the stream:

   427      *      CS call: UPL: mic source and modem sink

   428      *      CS call: DNL: modem source and speaker sink

   429      *      IP call: UPL: mic source, codec format and client sink

   430      *      IP call: DNL: client source, codec format and speaker sink

   431      *

   432      * @return

   433      *      TMS_RESULT_SUCCESS if stream transitioned to the initialized state.

   434      *      TMS_RESULT_INVALID_STATE if stream has not transitioned to the

   435      *      TMS_STREAM_UNINITIALIZED state.

   436      *      TMS_RESULT_FORMAT_TYPE_UNSPECIFIED (IP call only) when stream

   437      *      has no format attached to it.

   438      *      TMS_RESULT_UNINITIALIZED_OBJECT when stream has no sink or source

   439      *      element attached to it.

   440      *

   441      */

   442     IMPORT_C gint Init();

   443 

   444     /**

   445      * Trigger stream to transition to the paused state.

   446      *

   447      * This function can be called only when stream is in the

   448      * TMS_STREAM_UNINITIALIZED or TMS_STREAM_STARTED state.

   449      *

   450      * If Pause() is called when stream is already in paused state, the

   451      * request will be ignored and the function will return TMS_RESULT_SUCCESS.

   452      *

   453      * Upon stream's successful transition to the paused state, the stream will

   454      * be in the TMS_STREAM_PAUSED state.

   455      *

   456      * Note: In TMS Ver 1.0.0.0, pausing stream for CS call is not supported.

   457      *

   458      * @return

   459      *      TMS_RESULT_SUCCESS if stream successfully transitioned to the paused

   460      *      state.

   461      *      TMS_RESULT_INVALID_STATE if stream is not in the

   462      *      TMS_STREAM_INITIALIZED or TMS_STREAM_STARTED state.

   463      *

   464      */

   465     IMPORT_C gint Pause();

   466 

   467     /**

   468      * Trigger stream to transition to the started state.

   469      *

   470      * This function can be called only when stream is in the

   471      * TMS_STREAM_INITIALIZED or TMS_STREAM_PAUSED state.

   472      *

   473      * If Start() is called when stream is already in the started state, the

   474      * request will be ignored and the function will return TMS_RESULT_SUCCESS.

   475      *

   476      * If Start() is called when stream is already in the initialized state, the

   477      * stream will implicitly pause, but the observer will only receive one

   478      * state change callback.

   479      *

   480      * Upon stream's successful transition to the started state, the stream will

   481      * be in the TMS_STREAM_STARTED state.

   482      *

   483      * @return

   484      *      TMS_RESULT_SUCCESS if stream successfully transitioned to the paused

   485      *      state.

   486      *      TMS_RESULT_INVALID_STATE if stream is not in the

   487      *      TMS_STREAM_INITIALIZED or TMS_STREAM_PAUSED state.

   488      *

   489      */

   490     IMPORT_C gint Start();

   491 

   492     /**

   493      * Trigger stream to transition to the initialized state.

   494      *

   495      * This function can be called only when stream is in the

   496      * TMS_STREAM_STARTED or TMS_STREAM_PAUSED state.

   497      *

   498      * If Stop() is called when stream is already in the stopped state, the

   499      * request will be ignored and the function will return TMS_RESULT_SUCCESS.

   500      *

   501      * Upon stream's successful transition to the started state, the stream will

   502      * be in the TMS_STREAM_INITIALIZED state.

   503      *

   504      * @return

   505      *      TMS_RESULT_SUCCESS if stream successfully transitioned to the paused

   506      *      state.

   507      *      TMS_RESULT_INVALID_STATE if stream is not in the

   508      *      TMS_STREAM_STARTED or TMS_STREAM_PAUSED state.

   509      *

   510      */

   511     IMPORT_C gint Stop();

   512 

   513     /**

   514      * Trigger stream to transition to un-initialized state.

   515      *

   516      * This function can be called only when stream is NOT in

   517      * TMS_STREAM_UNINITIALIZED state.

   518      *

   519      * If Deinit() is called when stream is already in un-initialized state, the

   520      * request will be ignored.

   521      *

   522      * Upon stream's successful transition to the un-initialized state, the

   523      * stream will be in the TMS_STREAM_UNINITIALIZED state.

   524      *

   525      */

   526     IMPORT_C void Deinit();

   527 

   528 protected:

   529     /**

   530      * Constructor

   531      */

   532     IMPORT_C TMSStream();

   533 

   534 protected:

   535     TMSStreamBody *iBody;

   536     };

   537 

   538 } //namespace TMS

   539 

   540 #endif // TMS_STREAM_H

   541 

   542 // End of file