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 class TMSStream;

    29 }

    30 

    31 namespace QTMS {

    32 

    33 // Forward declarations

    34 class QTMSSource;

    35 class QTMSSink;

    36 class QTMSEffect;

    37 class QTMSFormat;

    38 class QTMSBuffer;

    39 

    40 /**

    41  * QTMSStream class

    42  *

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

    44  * a QTMSCall.

    45  *

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

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

    48  * Switching (PS) such as IP call.

    49  *

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

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

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

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

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

    55  *

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

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

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

    59  * automatically deleted as well.

    60  *

    61  * QTMS ver 1.0.0.0:

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

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

    64  *

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

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

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

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

    69  *

    70  * States:

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

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

    73  *

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

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

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

    77  *  and/or hardware resources.

    78  *

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

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

    81  *

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

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

    84  *  and is active.

    85  *

    86  * Usage:

    87  * <code>

    88  * QTMSFactory *iFactory;

    89  * QTMSCall *iCall;

    90  * QTMSStream *iUplink;

    91  * QTMSStream *iDownlink;

    92  * gint err;

    93  *

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

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

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

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

    98  * // Configure CS uplink stream

    99  * iUplinkStream->AddObserver(*this);

   100  * iUplinkStream->AddSource(iMicSource);

   101  * iUplinkStream->AddSink(iModemSink);

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

   103  * iUplinkStream->Init();

   104  * // Wait for state change callback

   105  * iUplinkStream->Play();

   106  * // Wait for state change callback

   107  * ...

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

   109  * iUplinkStream->Stop();

   110  * ...

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

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

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

   114  * delete iFactory;

   115  *

   116  * </code>

   117  *

   118  * @lib QTMSapi.lib

   119  *

   120  */

   121 

   122 class QTMS_WRAPPER_DLL_EXPORT QTMSStream : public QObject

   123     {

   124     Q_OBJECT

   125 public:

   126 

   127     /**

   128      * Destructor

   129      */

   130     virtual ~QTMSStream();

   131 

   132     /**

   133      * Add source for this stream.

   134      *

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

   136      * QTMS_STREAM_UNINITIALIZED state.

   137      *

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

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

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

   141      *

   142      * @param  source

   143      *      Source object to be added to the stream.

   144      *

   145      * @return

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

   147      *      QTMS_RESULT_NULL_ARGUMENT if source is a NULL.

   148      *      QTMS_RESULT_ALREADY_EXIST if source has already been added to the

   149      *      stream.

   150      *      QTMS_RESULT_INVALID_STATE if stream is not

   151      *      in the QTMS_STREAM_UNINITIALIZED state.

   152      *

   153      */

   154     gint AddSource(QTMSSource* source);

   155 

   156     /**

   157      * Remove source from this stream.

   158      *

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

   160      * QTMS_STREAM_UNINITIALIZED state.

   161      *

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

   163      * source is re-claimed by the client.

   164      *

   165      * @param  source

   166      *      The source to remove.

   167      *

   168      * @return

   169      *      QTMS_RESULT_SUCCESS if source is removed successfully from the

   170      *      stream.

   171      *      QTMS_RESULT_NULL_ARGUMENT if source is a NULL.

   172      *      QTMS_RESULT_DOES_NOT_EXIST if trying to remove the source that has

   173      *      not been added to stream.

   174      *      QTMS_RESULT_INVALID_STATE if stream is not

   175      *      in the QTMS_STREAM_UNINITIALIZED state.

   176      *

   177      */

   178     gint RemoveSource(QTMSSource* source);

   179 

   180     /**

   181      * Add sink to the stream.

   182      *

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

   184      *

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

   186      * QTMS_STREAM_UNINITIALIZED state.

   187      *

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

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

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

   191      *

   192      * @param  sink

   193      *      Data sink to be added to the stream.

   194      *

   195      * @return

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

   197      *      QTMS_RESULT_NULL_ARGUMENT if sink is a NULL.

   198      *      QTMS_RESULT_ALREADY_EXIST if sink type is already added to the

   199      *      stream.

   200      *      QTMS_RESULT_INVALID_STATE if stream is not

   201      *      in the QTMS_STREAM_UNINITIALIZED state.

   202      *

   203      */

   204     gint AddSink(QTMSSink* sink);

   205 

   206     /**

   207      * Remove sink from the stream.

   208      *

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

   210      * QTMS_STREAM_UNINITIALIZED state.

   211      *

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

   213      * sink is re-claimed by the client.

   214      *

   215      * @param  sink

   216      *      Sink to removed from the stream.

   217      *

   218      * @return

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

   220      *      QTMS_RESULT_NULL_ARGUMENT if sink is a NULL.

   221      *      QTMS_RESULT_DOES_NOT_EXIST if trying to remove sink that has not

   222      *      been added to the stream.

   223      *      QTMS_RESULT_INVALID_STATE if stream is not

   224      *      in the QTMS_STREAM_UNINITIALIZED state.

   225      *

   226      */

   227     gint RemoveSink(QTMSSink* sink);

   228 

   229     /**

   230      * Set data format for the stream.

   231      *

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

   233      * QTMS_STREAM_UNINITIALIZED state.

   234      *

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

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

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

   238      *

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

   240      * required.

   241      *

   242      * @param  format

   243      *      Data format to be set on the stream.

   244      *

   245      * @return

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

   247      *      QTMS_RESULT_NULL_ARGUMENT if format is a NULL.

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

   249      *      QTMS_RESULT_INVALID_STATE if stream is not

   250      *      in the QTMS_STREAM_UNINITIALIZED state.

   251      *

   252      */

   253     gint SetFormat(QTMSFormat* format);

   254 

   255     /**

   256      * Remove data format from the stream.

   257      *

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

   259      * QTMS_STREAM_UNINITIALIZED state.

   260      *

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

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

   263      *

   264      * @param  format

   265      *      Data format to be removed from the stream.

   266      *

   267      * @return

   268      *      QTMS_RESULT_SUCCESS if format is removed successfully from the

   269      *      stream.

   270      *      QTMS_RESULT_NULL_ARGUMENT if format is a NULL.

   271      *      QTMS_RESULT_DOES_NOT_EXIST if format is not currently set on the

   272      *      stream.

   273      *      QTMS_RESULT_INVALID_STATE if stream is not in the

   274      *      QTMS_STREAM_UNINITIALIZED state.

   275      *

   276      */

   277     gint ResetFormat(QTMSFormat* format);

   278 

   279     /**

   280      * Add an effect to the stream.

   281      *

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

   283      *

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

   285      * QTMS_STREAM_UNINITIALIZED state.

   286      *

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

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

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

   290      *

   291      * @param  effect

   292      *      Stream effect to be added to the stream.

   293      *

   294      * @return

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

   296      *      QTMS_RESULT_NULL_ARGUMENT if effect is a NULL.

   297      *      QTMS_RESULT_ALREADY_EXIST if effect type is already added to the

   298      *      stream.

   299      *      QTMS_RESULT_INVALID_STATE if stream is not in the

   300      *      QTMS_STREAM_UNINITIALIZED state.

   301      *

   302      */

   303     gint AddEffect(QTMSEffect* effect);

   304 

   305     /**

   306      * Remove effect from the stream.

   307      *

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

   309      * QTMS_STREAM_UNINITIALIZED state.

   310      *

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

   312      * effect is re-claimed by the client.

   313      *

   314      * @param  effect

   315      *      Stream effect to be removed from the stream.

   316      *

   317      * @return

   318      *      QTMS_RESULT_SUCCESS if effect is removed successfully from the

   319      *      stream.

   320      *      QTMS_RESULT_NULL_ARGUMENT if effect is a NULL.

   321      *      QTMS_RESULT_DOES_NOT_EXIST if trying to remove an effect that has

   322      *      not been added to the stream.

   323      *      QTMS_RESULT_INVALID_STATE if stream is not in the

   324      *      QTMS_STREAM_UNINITIALIZED state.

   325      *

   326      */

   327     gint RemoveEffect(QTMSEffect* effect);

   328 

   329     /**

   330      * Get current state of the stream.

   331      *

   332      * This function can be called at any time.

   333      *

   334      * Possible states are:

   335      *  QTMS_STREAM_UNINITIALIZED,

   336      *  QTMS_STREAM_INITIALIZED,

   337      *  QTMS_STREAM_PAUSED,

   338      *  QTMS_STREAM_STARTED.

   339 

   340      * @return

   341      *      Stream's current state.

   342      *

   343      */

   344     gint GetState();

   345 

   346     /**

   347      * Get stream type.

   348      *

   349      * This function can be called at any time.

   350      *

   351      * The possible types are:

   352      *  QTMS_STREAM_UPLINK

   353      *  QTMS_STREAM_DOWNLINK

   354      *

   355      * @return

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

   357      *

   358      */

   359     gint GetStreamId();

   360 

   361     /**

   362      * Get stream ID.

   363      *

   364      * This function can be called at any time.

   365      *

   366      * @return

   367      *      Unique ID of the stream.

   368      *

   369      */

   370     gint GetStreamType();

   371 

   372     /**

   373      * Trigger stream to transition to the initialized state.

   374      *

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

   376      * QTMS_STREAM_UNINITIALIZED state.

   377      *

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

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

   380      *

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

   382      * be in the QTMS_STREAM_INITIALIZED state.

   383      *

   384      * QUESTION??? Should we do the initial checking here??? (for source,

   385      * sink and other settings)

   386      *

   387      * @return

   388      *      QTMS_RESULT_SUCCESS if stream transitioned to the initialized state.

   389      *      QTMS_RESULT_INVALID_STATE if stream has not transitioned to the

   390      *      QTMS_STREAM_UNINITIALIZED state.

   391      *

   392      */

   393     gint Init();

   394 

   395     /**

   396      * Trigger stream to transition to the paused state.

   397      *

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

   399      * QTMS_STREAM_UNINITIALIZED or QTMS_STREAM_STARTED state.

   400      *

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

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

   403      *

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

   405      * be in the QTMS_STREAM_PAUSED state.

   406      *

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

   408      *

   409      * @return

   410      *      QTMS_RESULT_SUCCESS if stream successfully transitioned to the paused

   411      *      state.

   412      *      QTMS_RESULT_INVALID_STATE if stream is not in the

   413      *      QTMS_STREAM_INITIALIZED or QTMS_STREAM_STARTED state.

   414      *

   415      */

   416     gint Pause();

   417 

   418     /**

   419      * Trigger stream to transition to the started state.

   420      *

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

   422      * QTMS_STREAM_INITIALIZED or QTMS_STREAM_PAUSED state.

   423      *

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

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

   426      *

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

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

   429      * state change callback.

   430      *

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

   432      * be in the QTMS_STREAM_STARTED state.

   433      *

   434      * @return

   435      *      QTMS_RESULT_SUCCESS if stream successfully transitioned to the paused

   436      *      state.

   437      *      QTMS_RESULT_INVALID_STATE if stream is not in the

   438      *      QTMS_STREAM_INITIALIZED or QTMS_STREAM_PAUSED state.

   439      *

   440      */

   441     gint Start();

   442 

   443     /**

   444      * Trigger stream to transition to the initialized state.

   445      *

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

   447      * QTMS_STREAM_STARTED or QTMS_STREAM_PAUSED state.

   448      *

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

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

   451      *

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

   453      * be in the QTMS_STREAM_INITIALIZED state.

   454      *

   455      * @return

   456      *      QTMS_RESULT_SUCCESS if stream successfully transitioned to the paused

   457      *      state.

   458      *      QTMS_RESULT_INVALID_STATE if stream is not in the

   459      *      QTMS_STREAM_STARTED or QTMS_STREAM_PAUSED state.

   460      *

   461      */

   462     gint Stop();

   463 

   464     /**

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

   466      *

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

   468      * QTMS_STREAM_UNINITIALIZED state.

   469      *

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

   471      * request will be ignored.

   472      *

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

   474      * stream will be in the QTMS_STREAM_UNINITIALIZED state.

   475      *

   476      */

   477     void Deinit();

   478 

   479     Q_SIGNALS:

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

   481 

   482 protected:

   483     /**

   484      * Constructor

   485      */

   486     QTMSStream();

   487 

   488 protected:

   489     TMS::TMSStream *iStream;

   490     };

   491 

   492 } //namespace QTMS

   493 

   494 #endif // QTMS_STREAM_H

   495 

   496 // End of file