mm_session.h

   1 /*
   2  * libmm-session
   3  *
   4  * Copyright (c) 2000 - 2013 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Seungbae Shin <seungbae.shin at samsung.com>, Sangchul Lee <sc11.lee at samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22
  23 /**
  24  * This file declares common data structure of multimedia framework.
  25  *
  26  * @file                mm_session.h
  27  * @author
  28  * @version             1.0
  29  * @brief               This file declares multimedia framework session type.
  30  */
  31 #ifndef _MM_SESSION_H_
  32 #define _MM_SESSION_H_
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37 /**
  38         @addtogroup MMSESSION
  39         @{
  40         @par
  41         This part is describes multimedia framework session type and function
  42  */
  43
  44 /**
  45   * This enumeration defines application's session types.
  46   */
  47 enum MMSessionType {
  48         MM_SESSION_TYPE_MEDIA = 0,
  49         MM_SESSION_TYPE_MEDIA_RECORD,
  50         MM_SESSION_TYPE_ALARM,
  51         MM_SESSION_TYPE_NOTIFY,
  52         MM_SESSION_TYPE_EMERGENCY,
  53         MM_SESSION_TYPE_CALL,
  54         MM_SESSION_TYPE_VIDEOCALL,
  55         MM_SESSION_TYPE_VOIP,
  56         MM_SESSION_TYPE_VOICE_RECOGNITION,
  57         MM_SESSION_TYPE_RECORD_AUDIO,
  58         MM_SESSION_TYPE_RECORD_VIDEO,
  59         MM_SESSION_TYPE_NUM
  60 };
  61
  62 /**
  63   * This enumeration defines behavior of update.
  64   */
  65 typedef enum {
  66         MM_SESSION_UPDATE_TYPE_ADD,
  67         MM_SESSION_UPDATE_TYPE_REMOVE,
  68         MM_SESSION_UPDATE_TYPE_NUM
  69 }session_update_type_t;
  70
  71 /**
  72   * This define is for session options
  73   */
  74 #define MM_SESSION_OPTION_PAUSE_OTHERS                      0x0001
  75 #define MM_SESSION_OPTION_UNINTERRUPTIBLE                   0x0002
  76 #define MM_SESSION_OPTION_RESUME_BY_SYSTEM_OR_MEDIA_PAUSED  0x0010
  77
  78 /**
  79   * This enumeration defines session callback message type.
  80   */
  81 typedef enum {
  82         MM_SESSION_MSG_STOP,    /**< Message Stop : this messages means that session of application has interrupted by policy.
  83                                                                                                 So application should stop it's multi-media context when this message has come */
  84         MM_SESSION_MSG_RESUME,  /**< Message Stop : this messages means that session interrupt of application has ended.
  85                                                                                                 So application could resume it's multi-media context when this message has come */
  86         MM_SESSION_MSG_NUM
  87 }session_msg_t;
  88
  89 typedef enum {
  90         MM_SESSION_EVENT_MEDIA = 0,
  91         MM_SESSION_EVENT_CALL,
  92         MM_SESSION_EVENT_ALARM,
  93         MM_SESSION_EVENT_EARJACK_UNPLUG,
  94         MM_SESSION_EVENT_RESOURCE_CONFLICT,
  95         MM_SESSION_EVENT_EMERGENCY,
  96         MM_SESSION_EVENT_NOTIFICATION,
  97 }session_event_t;
  98
  99 typedef enum {
 100         MM_SESSION_WATCH_EVENT_IGNORE = -1,
 101         MM_SESSION_WATCH_EVENT_CALL = 0,
 102         MM_SESSION_WATCH_EVENT_VIDEO_CALL,
 103         MM_SESSION_WATCH_EVENT_ALARM,
 104         MM_SESSION_WATCH_EVENT_NUM
 105 }session_watch_event_t;
 106
 107 typedef enum {
 108         MM_SESSION_WATCH_STATE_STOP = 0,
 109         MM_SESSION_WATCH_STATE_PLAYING,
 110         MM_SESSION_WATCH_STATE_NUM
 111 }session_watch_state_t;
 112
 113 typedef void (*session_callback_fn) (session_msg_t msg, session_event_t event, void *user_param);
 114 typedef void (*watch_callback_fn) (session_watch_event_t event, session_watch_state_t state, void *user_param);
 115
 116 /**
 117  * This function defines application's Multimedia Session policy
 118  *
 119  * @param       sessiontype     [in] Multimedia Session type
 120  *
 121  * @return      This function returns MM_ERROR_NONE on success, or negative value
 122  *                      with error code.
 123  * @remark      Session type is unique for each application (each PID actually).
 124  *                      if application want to change session type, Finish session first and Init again
 125  * @see         MMSessionType mm_session_finish
 126  * @since
 127  * @pre         There should be pre-initialized session type for caller application.
 128  * @post        A session type of caller application will be defined process widely.
 129  * @par Example
 130  * @code
 131 #include <mm_session.h>
 132
 133 static int _create(void *data)
 134 {
 135         int ret = 0;
 136
 137         // Initialize Multimedia Session Type
 138         ret = mm_session_init(MM_SESSION_TYPE_MEDIA);
 139         if(ret < 0)
 140         {
 141                 printf("Can not initialize session \n");
 142         }
 143         ...
 144 }
 145
 146 static int _terminate(void* data)
 147 {
 148         int ret = 0;
 149
 150         // Deinitialize Multimedia Session Type
 151         ret = mm_session_finish();
 152         if(ret < 0)
 153         {
 154                 printf("Can not finish session\n");
 155         }
 156         ...
 157 }
 158
 159 int main()
 160 {
 161         ...
 162         struct appcore_ops ops = {
 163                 .create = _create,
 164                 .terminate = _terminate,
 165                 .pause = _pause,
 166                 .resume = _resume,
 167                 .reset = _reset,
 168         };
 169         ...
 170         return appcore_efl_main(PACKAGE, ..., &ops);
 171 }
 172
 173  * @endcode
 174  */
 175 int mm_session_init(int sessiontype);
 176
 177
 178
 179
 180 /**
 181  * This function defines application's Multimedia Session policy
 182  *
 183  * @param       sessiontype     [in] Multimedia Session type
 184  * @param       session_callback_fn [in] session message callback function pointer
 185  * @param       user_param [in] callback function user parameter
 186  *
 187  * @return      This function returns MM_ERROR_NONE on success, or negative value
 188  *                      with error code.
 189  * @remark      Session type is unique for each application (each PID actually).
 190  *                      if application want to change session type, Finish session first and Init again
 191  * @pre         There should be pre-initialized session type for caller application.
 192  * @post        A session type of caller application will be defined process widely.
 193  *                      And session callback will be registered as given function pointer with given user_param
 194  * @see         MMSessionType mm_session_finish
 195  * @since
 196  * @par Example
 197  * @code
 198 #include <mm_session.h>
 199
 200 session_callback_fn session_cb(session_msg_t msg,  session_event_t event, void *user_param)
 201 {
 202         struct appdata* ad = (struct appdata*) user_param;
 203
 204         switch(msg)
 205         {
 206         case MM_SESSION_MSG_STOP:
 207                 // Stop multi-media context here
 208                 ...
 209                 break;
 210         case MM_SESSION_MSG_RESUME:
 211                 // Resume multi-media context here
 212                 ...
 213                 break;
 214         default:
 215                 break;
 216         }
 217         ...
 218 }
 219
 220 static int _create(void *data)
 221 {
 222         struct appdata* ad = (struct appdata*) data;
 223         int ret = 0;
 224
 225         // Initialize Multimedia Session Type with callback
 226         ret = mm_session_init_ex(MM_SESSION_TYPE_MEDIA, session_cb, (void*)ad);
 227         if(ret < 0)
 228         {
 229                 printf("Can not initialize session \n");
 230         }
 231         ...
 232 }
 233
 234 static int _terminate(void* data)
 235 {
 236         int ret = 0;
 237
 238         // Deinitialize Multimedia Session Type
 239         ret = mm_session_finish();
 240         if(ret < 0)
 241         {
 242                 printf("Can not finish session\n");
 243         }
 244         ...
 245 }
 246
 247
 248 int main()
 249 {
 250         ...
 251         struct appcore_ops ops = {
 252                 .create = _create,
 253                 .terminate = _terminate,
 254                 .pause = _pause,
 255                 .resume = _resume,
 256                 .reset = _reset,
 257         };
 258         ...
 259         return appcore_efl_main(PACKAGE, ..., &ops);
 260 }
 261
 262  * @endcode
 263  */
 264 int mm_session_init_ex(int sessiontype, session_callback_fn callback, void* user_param);
 265
 266
 267
 268 /**
 269  * This function finish application's Multimedia Session.
 270  *
 271  *
 272  * @return      This function returns MM_ERROR_NONE on success, or negative value
 273  *                      with error code.
 274  * @remark      Session type is unique for each application (each PID actually).
 275  *                      if application want to change session type, Finish session first and Init again
 276  * @see         mm_session_init
 277  * @pre         A session type should be initialized for caller application.
 278  * @post        A session type for caller application will be cleared.
 279  * @since
 280  * @par Example
 281  * @code
 282 #include <mm_session.h>
 283
 284 static int _create(void *data)
 285 {
 286         int ret = 0;
 287
 288         // Initialize Multimedia Session Type
 289         ret = mm_session_init(MM_SESSION_TYPE_MEDIA);
 290         if(ret < 0)
 291         {
 292                 printf("Can not initialize session \n");
 293         }
 294         ...
 295 }
 296
 297 static int _terminate(void* data)
 298 {
 299         int ret = 0;
 300
 301         // Deinitialize Multimedia Session Type
 302         ret = mm_session_finish();
 303         if(ret < 0)
 304         {
 305                 printf("Can not finish session\n");
 306         }
 307         ...
 308 }
 309
 310 int main()
 311 {
 312         ...
 313         struct appcore_ops ops = {
 314                 .create = _create,
 315                 .terminate = _terminate,
 316                 .pause = _pause,
 317                 .resume = _resume,
 318                 .reset = _reset,
 319         };
 320         ...
 321         return appcore_efl_main(PACKAGE, ..., &ops);
 322 }
 323  * @endcode
 324  */
 325 int mm_session_finish(void);
 326
 327 /**
 328  * This function get current application's Multimedia Session type
 329  *
 330  * @param       sessiontype     [out] Current Multimedia Session type
 331  * @return      This function returns MM_ERROR_NONE on success, or negative value
 332  *                      with error code.
 333  * @see         mm_session_init
 334  * @since
 335  */
 336 int mm_session_get_current_type(int *sessiontype);
 337
 338 /**
 339  * This function get current application's Multimedia Session information
 340  *
 341  * @param       session_type    [out] Current Multimedia Session type
 342  * @param       session_options [out] Current Multimedia Session options
 343  * @return      This function returns MM_ERROR_NONE on success, or negative value
 344  *                      with error code.
 345  * @see
 346  * @since
 347  */
 348 int mm_session_get_current_information(int *session_type, int *session_options);
 349
 350 /**
 351  * This function update application's Multimedia Session options
 352  *
 353  * @param       update_type     [in] add or remove options
 354  * @param       session_options [in] Multimedia Session options to be updated
 355  * @return      This function returns MM_ERROR_NONE on success, or negative value
 356  *                      with error code.
 357  * @see
 358  * @since
 359  */
 360 int mm_session_update_option(session_update_type_t update_type, int options);
 361
 362 /**
 363  * This function add a watch callback
 364  *
 365  * @param       watchevent      [in]    The session type to be watched
 366  * @param       watchstate      [in]    The session state of the session type of first argument to be watched
 367  * @param       callback        [in]    The callback which will be called when the watched session state was activated
 368  * @param       user_param      [in]    The user param passed from the callback registration function
 369  * @return      This function returns MM_ERROR_NONE on success, or negative value
 370  *                      with error code.
 371  * @see
 372  * @since
 373  */
 374 int mm_session_add_watch_callback(int watchevent, int watchstate, watch_callback_fn callback, void* user_param);
 375
 376 /**
 377  * This function removes a watch callback corresponding with two arguments
 378  *
 379  * @param       watchevent      [in]    The session type to be removed
 380  * @param       watchstate      [in]    The session state to be removed
 381  * @return      This function returns MM_ERROR_NONE on success, or negative value
 382  *                      with error code.
 383  * @see
 384  * @since
 385  */
 386 int mm_session_remove_watch_callback(int watchevent, int watchstate);
 387
 388 /**
 389  * This function initialize resumption of other ASM handles which were paused by this session
 390  * It can be used only when call series or voice recognition session is set
 391  *
 392  * @return      This function returns MM_ERROR_NONE on success, or negative value
 393  *                      with error code.
 394  */
 395 int mm_session_reset_resumption_info(void);
 396
 397 /**
 398         @}
 399  */
 400
 401 #ifdef __cplusplus
 402 }
 403 #endif
 404
 405 #endif