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