1 /*

     2  * Copyright (c) 2010 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: QT Bindings for TMS

    15  *

    16  */

    17 

    18 #ifndef QTMS_STREAM_H

    19 #define QTMS_STREAM_H

    20 

    21 // Include files

    22 #include <qtms.h>

    23 #include <QObject>

    24 #include "qtmswrapperexport.h"

    25 

    26 // FORWARD DECLARATIONS

    27 namespace TMS

    28 {

    29 class TMSStream;

    30 }

    31 

    32 namespace QTMS

    33 {

    34 

    35 // Forward declarations

    36 class QTMSSource;

    37 class QTMSSink;

    38 class QTMSEffect;

    39 class QTMSFormat;

    40 class QTMSBuffer;

    41 

    42 /**

    43  * QTMSStream class

    44  *

    45  * QTMSStream class represents either uplink or downlink stream associated with

    46  * a QTMSCall.

    47  *

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

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

    50  * Switching (PS) such as IP call.

    51  *

    52  * QTMSStream instances are created by QTMSCall instance. Multiple QTMSStream

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

    54  * does not limit the number of streams created per QTMSCall object. However,

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

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

    57  *

    58  * QTMSCall is a container which owns all its QTMSStream instances. The client

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

    60  * QTMSCall instance is deleted, all the streams associated with it are

    61  * automatically deleted as well.

    62  *

    63  * QTMS ver 1.0.0.0:

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

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

    66  *

    67  *  (2) In the initial version of the QTMS implementation, the CS uplink and

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

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

    70  *  protocol. It is assumed that the QTMS client will handle this functionality.

    71  *

    72  * States:

    73  *  (1) QTMS_STREAM_UNINITIALIZED (initial state): The stream is alive but has

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

    75  *

    76  *  (2) QTMS_STREAM_INITIALIZED: The stream has all the information required to

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

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

    79  *  and/or hardware resources.

    80  *

    81  *  (3) QTMS_STREAM_PAUSED: The stream has all the resources allocated, which may

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

    83  *

    84  *  (4) QTMS_STREAM_STARTED: The stream has all the resources allocated,

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

    86  *  and is active.

    87  *

    88  * Usage:

    89  * <code>

    90  * QTMSFactory *iFactory;

    91  * QTMSCall *iCall;

    92  * QTMSStream *iUplink;

    93  * QTMSStream *iDownlink;

    94  * gint err;

    95  *

    96  * err = QTMSFactory::CreateFactory(iFactory);

    97  * err = iFactory->CreateCall(QTMS_CALL_IP, iCall);

    98  * err = iCall->CreateStream(QTMS_STREAM_UPLINK, iUplink);

    99  * err = iCall->CreateStream(QTMS_STREAM_DOWNLINK, iDownlink);

   100  * // Configure CS uplink stream

   101  * iUplinkStream->AddObserver(*this);

   102  * iUplinkStream->AddSource(iMicSource);

   103  * iUplinkStream->AddSink(iModemSink);

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

   105  * iUplinkStream->Init();

   106  * // Wait for state change callback

   107  * iUplinkStream->Play();

   108  * // Wait for state change callback

   109  * ...

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

   111  * iUplinkStream->Stop();

   112  * ...

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

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

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

   116  * delete iFactory;

   117  *

   118  * </code>

   119  *

   120  * @lib QTMSapi.lib

   121  *

   122  */

   123 

   124 class QTMS_WRAPPER_DLL_EXPORT QTMSStream : public QObject

   125 {

   126     Q_OBJECT

   127 public:

   128 

   129     /**

   130      * Destructor

   131      */

   132     virtual ~QTMSStream();

   133 

   134     /**

   135      * Add source for this stream.

   136      *

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

   138      * QTMS_STREAM_UNINITIALIZED state.

   139      *

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

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

   142      * should call RemoveSource() to re-claim QTMSSource ownership.

   143      *

   144      * @param  source

   145      *      Source object to be added to the stream.

   146      *

   147      * @return

   148      *      QTMS_RESULT_SUCCESS if source is added successfully to the stream.

   149      *      QTMS_RESULT_NULL_ARGUMENT if source is a NULL.

   150      *      QTMS_RESULT_ALREADY_EXIST if source has already been added to the

   151      *      stream.

   152      *      QTMS_RESULT_INVALID_STATE if stream is not

   153      *      in the QTMS_STREAM_UNINITIALIZED state.

   154      *

   155      */

   156     gint AddSource(QTMSSource* source);

   157 

   158     /**

   159      * Remove source from this stream.

   160      *

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

   162      * QTMS_STREAM_UNINITIALIZED state.

   163      *

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

   165      * source is re-claimed by the client.

   166      *

   167      * @param  source

   168      *      The source to remove.

   169      *

   170      * @return

   171      *      QTMS_RESULT_SUCCESS if source is removed successfully from the

   172      *      stream.

   173      *      QTMS_RESULT_NULL_ARGUMENT if source is a NULL.

   174      *      QTMS_RESULT_DOES_NOT_EXIST if trying to remove the source that has

   175      *      not been added to stream.

   176      *      QTMS_RESULT_INVALID_STATE if stream is not

   177      *      in the QTMS_STREAM_UNINITIALIZED state.

   178      *

   179      */

   180     gint RemoveSource(QTMSSource* source);

   181 

   182     /**

   183      * Add sink to the stream.

   184      *

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

   186      *

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

   188      * QTMS_STREAM_UNINITIALIZED state.

   189      *

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

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

   192      * RemoveSink() to re-claim QTMSSink ownership.

   193      *

   194      * @param  sink

   195      *      Data sink to be added to the stream.

   196      *

   197      * @return

   198      *      QTMS_RESULT_SUCCESS if sink is added successfully to the stream.

   199      *      QTMS_RESULT_NULL_ARGUMENT if sink is a NULL.

   200      *      QTMS_RESULT_ALREADY_EXIST if sink type is already added to the

   201      *      stream.

   202      *      QTMS_RESULT_INVALID_STATE if stream is not

   203      *      in the QTMS_STREAM_UNINITIALIZED state.

   204      *

   205      */

   206     gint AddSink(QTMSSink* sink);

   207 

   208     /**

   209      * Remove sink from the stream.

   210      *

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

   212      * QTMS_STREAM_UNINITIALIZED state.

   213      *

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

   215      * sink is re-claimed by the client.

   216      *

   217      * @param  sink

   218      *      Sink to removed from the stream.

   219      *

   220      * @return

   221      *      QTMS_RESULT_SUCCESS if sink is removed successfully from the stream.

   222      *      QTMS_RESULT_NULL_ARGUMENT if sink is a NULL.

   223      *      QTMS_RESULT_DOES_NOT_EXIST if trying to remove sink that has not

   224      *      been added to the stream.

   225      *      QTMS_RESULT_INVALID_STATE if stream is not

   226      *      in the QTMS_STREAM_UNINITIALIZED state.

   227      *

   228      */

   229     gint RemoveSink(QTMSSink* sink);

   230 

   231     /**

   232      * Set data format for the stream.

   233      *

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

   235      * QTMS_STREAM_UNINITIALIZED state.

   236      *

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

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

   239      * it should call ResetFormat() to re-claim QTMSFormat ownership.

   240      *

   241      * Note: In QTMS Ver 1.0.0.0, setting data format for CS call is not

   242      * required.

   243      *

   244      * @param  format

   245      *      Data format to be set on the stream.

   246      *

   247      * @return

   248      *      QTMS_RESULT_SUCCESS if format is set successfully on the stream.

   249      *      QTMS_RESULT_NULL_ARGUMENT if format is a NULL.

   250      *      QTMS_RESULT_ALREADY_EXIST if format is already set on the stream.

   251      *      QTMS_RESULT_INVALID_STATE if stream is not

   252      *      in the QTMS_STREAM_UNINITIALIZED state.

   253      *

   254      */

   255     gint SetFormat(QTMSFormat* format);

   256 

   257     /**

   258      * Remove data format from the stream.

   259      *

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

   261      * QTMS_STREAM_UNINITIALIZED state.

   262      *

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

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

   265      *

   266      * @param  format

   267      *      Data format to be removed from the stream.

   268      *

   269      * @return

   270      *      QTMS_RESULT_SUCCESS if format is removed successfully from the

   271      *      stream.

   272      *      QTMS_RESULT_NULL_ARGUMENT if format is a NULL.

   273      *      QTMS_RESULT_DOES_NOT_EXIST if format is not currently set on the

   274      *      stream.

   275      *      QTMS_RESULT_INVALID_STATE if stream is not in the

   276      *      QTMS_STREAM_UNINITIALIZED state.

   277      *

   278      */

   279     gint ResetFormat(QTMSFormat* format);

   280 

   281     /**

   282      * Add an effect to the stream.

   283      *

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

   285      *

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

   287      * QTMS_STREAM_UNINITIALIZED state.

   288      *

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

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

   291      * it shall call RemoveEffect() to re-claim QTMSEffect ownership.

   292      *

   293      * @param  effect

   294      *      Stream effect to be added to the stream.

   295      *

   296      * @return

   297      *      QTMS_RESULT_SUCCESS if effect is added successfully to the stream.

   298      *      QTMS_RESULT_NULL_ARGUMENT if effect is a NULL.

   299      *      QTMS_RESULT_ALREADY_EXIST if effect type is already added to the

   300      *      stream.

   301      *      QTMS_RESULT_INVALID_STATE if stream is not in the

   302      *      QTMS_STREAM_UNINITIALIZED state.

   303      *

   304      */

   305     gint AddEffect(QTMSEffect* effect);

   306 

   307     /**

   308      * Remove effect from the stream.

   309      *

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

   311      * QTMS_STREAM_UNINITIALIZED state.

   312      *

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

   314      * effect is re-claimed by the client.

   315      *

   316      * @param  effect

   317      *      Stream effect to be removed from the stream.

   318      *

   319      * @return

   320      *      QTMS_RESULT_SUCCESS if effect is removed successfully from the

   321      *      stream.

   322      *      QTMS_RESULT_NULL_ARGUMENT if effect is a NULL.

   323      *      QTMS_RESULT_DOES_NOT_EXIST if trying to remove an effect that has

   324      *      not been added to the stream.

   325      *      QTMS_RESULT_INVALID_STATE if stream is not in the

   326      *      QTMS_STREAM_UNINITIALIZED state.

   327      *

   328      */

   329     gint RemoveEffect(QTMSEffect* effect);

   330 

   331     /**

   332      * Get current state of the stream.

   333      *

   334      * This function can be called at any time.

   335      *

   336      * Possible states are:

   337      *  QTMS_STREAM_UNINITIALIZED,

   338      *  QTMS_STREAM_INITIALIZED,

   339      *  QTMS_STREAM_PAUSED,

   340      *  QTMS_STREAM_STARTED.

   341 

   342      * @return

   343      *      Stream's current state.

   344      *

   345      */

   346     gint GetState();

   347 

   348     /**

   349      * Get stream ID.

   350      *

   351      * This function can be called at any time.

   352      *

   353      * @return

   354      *      Unique ID of the stream.

   355      *

   356      */

   357     gint GetStreamId();

   358 

   359     /**

   360      * Get stream type.

   361      *

   362      * This function can be called at any time.

   363      *

   364      * The possible types are:

   365      *  TMS_STREAM_UPLINK

   366      *  TMS_STREAM_DOWNLINK

   367      *

   368      * @return

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

   370      *

   371      */

   372     gint GetStreamType();

   373 

   374     /**

   375      * Trigger stream to transition to the initialized state.

   376      *

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

   378      * QTMS_STREAM_UNINITIALIZED state.

   379      *

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

   381      * request will be ignored and the function will return QTMS_RESULT_SUCCESS.

   382      *

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

   384      * be in the QTMS_STREAM_INITIALIZED state.

   385      *

   386      * Before stream can transition to initialized state the following

   387      * objects must be added to the stream:

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

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

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

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

   392      *

   393      * @param  retrytime

   394      *      Indicates (in seconds) for how long TMS should retry stream

   395      *      initialization in case of an error. When stream initialization

   396      *      fails within specified retry time, TMS will return

   397      *      TMS_EVENT_STREAM_STATE_CHANGE_ERROR. If set to 0, TMS will return

   398      *      TMS_EVENT_STREAM_STATE_CHANGE_ERROR immediately without retrying.

   399      *      If set to -1, TMS will keep retrying until user cancels by calling

   400      *      either Stop() or Deinit().

   401      *

   402      * @return

   403      *      Common return codes:

   404      *      QTMS_RESULT_SUCCESS if stream transitioned to the initialized state.

   405      *      QTMS_RESULT_INVALID_STATE if stream has not transitioned to the

   406      *      QTMS_STREAM_INITIALIZED state.

   407      *      QTMS_RESULT_FORMAT_TYPE_UNSPECIFIED (IP call only) when stream

   408      *      has no format attached to it.

   409      *      QTMS_RESULT_UNINITIALIZED_OBJECT when stream has no sink or source

   410      *      element attached to it.

   411      *

   412      */

   413     gint Init(gint retrytime = 0);

   414 

   415     /**

   416      * Trigger stream to transition to the paused state.

   417      *

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

   419      * QTMS_STREAM_UNINITIALIZED or QTMS_STREAM_STARTED state.

   420      *

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

   422      * request will be ignored and the function will return QTMS_RESULT_SUCCESS.

   423      *

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

   425      * be in the QTMS_STREAM_PAUSED state.

   426      *

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

   428      *

   429      * @return

   430      *      Common return codes:

   431      *      QTMS_RESULT_SUCCESS if stream successfully transitioned to the

   432      *      paused state.

   433      *      QTMS_RESULT_INVALID_STATE if stream is not in the

   434      *      QTMS_STREAM_INITIALIZED or QTMS_STREAM_PAUSED state.

   435      *

   436      */

   437     gint Pause();

   438 

   439     /**

   440      * Trigger stream to transition to the started state.

   441      *

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

   443      * QTMS_STREAM_INITIALIZED or QTMS_STREAM_PAUSED state.

   444      *

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

   446      * request will be ignored and the function will return QTMS_RESULT_SUCCESS.

   447      *

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

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

   450      * state change callback.

   451      *

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

   453      * be in the QTMS_STREAM_STARTED state.

   454      *

   455      * @param  retrytime

   456      *      Indicates (in seconds) for how long TMS should attempt to start

   457      *      a stream in case of an error. When stream starting fails within

   458      *      specified retry time, TMS will return

   459      *      QTMS_EVENT_STREAM_STATE_CHANGE_ERROR. If set to 0, TMS will return

   460      *      QTMS_EVENT_STREAM_STATE_CHANGE_ERROR immediately without retrying.

   461      *      If set to -1, TMS will keep retrying until user cancels by calling

   462      *      either Stop() or Deinit().

   463      *

   464      * @return

   465      *      Common return codes:

   466      *      QTMS_RESULT_SUCCESS if stream successfully transitioned to the

   467      *      started state.

   468      *      QTMS_RESULT_INVALID_STATE if stream is not in the

   469      *      QTMS_STREAM_INITIALIZED or QTMS_STREAM_STARTED state.

   470      *

   471      */

   472     gint Start(gint retrytime = 0);

   473 

   474     /**

   475      * Trigger stream to transition to the initialized state.

   476      *

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

   478      * QTMS_STREAM_STARTED or QTMS_STREAM_PAUSED state.

   479      *

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

   481      * request will be ignored and the function will return QTMS_RESULT_SUCCESS.

   482      *

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

   484      * be in the QTMS_STREAM_INITIALIZED state.

   485      *

   486      * @return

   487      *      Common return codes:

   488      *      QTMS_RESULT_SUCCESS if stream successfully transitioned to the

   489      *      stopped state.

   490      *      QTMS_RESULT_INVALID_STATE if stream is not in the

   491      *      QTMS_STREAM_STARTED or QTMS_STREAM_PAUSED state.

   492      *

   493      */

   494     gint Stop();

   495 

   496     /**

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

   498      *

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

   500      * QTMS_STREAM_UNINITIALIZED state.

   501      *

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

   503      * request will be ignored.

   504      *

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

   506      * stream will be in the QTMS_STREAM_UNINITIALIZED state.

   507      *

   508      */

   509     void Deinit();

   510 

   511     Q_SIGNALS:

   512     void TMSStreamEvent(const QTMSStream& stream, QTMSSignalEvent event);

   513 

   514 protected:

   515     /**

   516      * Constructor

   517      */

   518     QTMSStream();

   519 

   520 protected:

   521     TMS::TMSStream *iStream;

   522 };

   523 

   524 } //namespace QTMS

   525 

   526 #endif // QTMS_STREAM_H

   527 // End of file