src/include/mm_player.h

   1 /*
   2  * libmm-player
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: JongHyuk Choi <jhchoi.choi@samsung.com>, YeJin Cho <cho.yejin@samsung.com>,
   7  * Seungbae Shin <seungbae.shin@samsung.com>, YoungHwan An <younghwan_.an@samsung.com>
   8  *
   9  * Licensed under the Apache License, Version 2.0 (the "License");
  10  * you may not use this file except in compliance with the License.
  11  * You may obtain a copy of the License at
  12  *
  13  * http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  * Unless required by applicable law or agreed to in writing, software
  16  * distributed under the License is distributed on an "AS IS" BASIS,
  17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  * See the License for the specific language governing permissions and
  19  * limitations under the License.
  20  *
  21  */
  22
  23 #ifndef __MM_PLAYER_H__
  24 #define __MM_PLAYER_H__
  25
  26
  27 /*===========================================================================================
  28 |                                                                                           |
  29 |  INCLUDE FILES                                        |
  30 |                                                                                           |
  31 ========================================================================================== */
  32
  33 #include <glib.h>
  34
  35 #include <mm_types.h>
  36 #include <mm_message.h>
  37
  38 #ifdef __cplusplus
  39         extern "C" {
  40 #endif
  41
  42 /**
  43         @addtogroup PLAYER
  44         @{
  45
  46         @par
  47         This part describes APIs used for playback of multimedia contents.
  48         All multimedia contents are created by a media player through handle of playback.
  49         In creating a player, it displays the player's status or information
  50         by registering callback function.
  51
  52         @par
  53         In case of streaming playback, network has to be opend by using datanetwork API.
  54         If proxy, cookies and the other attributes for streaming playback are needed,
  55         set those attributes using mm_player_set_attribute() before create player.
  56
  57         @par
  58         The subtitle for local video playback is supported. Set "subtitle_uri" attribute
  59         using mm_player_set_attribute() before the application creates the player.
  60         Then the application could receive MMMessageParamType which includes subtitle string and duration.
  61
  62         @par
  63         Player can have 5 states, and each state can be changed by calling
  64         described functions on "Figure1. State of Player".
  65
  66         @par
  67         @image html             player_state.jpg        "Figure1. State of Player"      width=12cm
  68         @image latex    player_state.jpg        "Figure1. State of Player"      width=12cm
  69
  70         @par
  71         Most of functions which change player state work as synchronous. But, mm_player_start() should be used
  72         asynchronously. Both mm_player_pause() and mm_player_resume() should also be used asynchronously
  73         in the case of streaming data.
  74         So, application have to confirm the result of those APIs through message callback function.
  75
  76         @par
  77         Note that "None" and Null" state could be reached from any state
  78         by calling mm_player_destroy() and mm_player_unrealize().
  79
  80         @par
  81         <div><table>
  82         <tr>
  83         <td><B>FUNCTION</B></td>
  84         <td><B>PRE-STATE</B></td>
  85         <td><B>POST-STATE</B></td>
  86         <td><B>SYNC TYPE</B></td>
  87         </tr>
  88         <tr>
  89         <td>mm_player_create()</td>
  90         <td>NONE</td>
  91         <td>NULL</td>
  92         <td>SYNC</td>
  93         </tr>
  94         <tr>
  95         <td>mm_player_destroy()</td>
  96         <td>NULL</td>
  97         <td>NONE</td>
  98         <td>SYNC</td>
  99         </tr>
 100         <tr>
 101         <td>mm_player_realize()</td>
 102         <td>NULL</td>
 103         <td>READY</td>
 104         <td>SYNC</td>
 105         </tr>
 106         <tr>
 107         <td>mm_player_unrealize()</td>
 108         <td>READY</td>
 109         <td>NULL</td>
 110         <td>SYNC</td>
 111         </tr>
 112         <tr>
 113         <td>mm_player_start()</td>
 114         <td>READY</td>
 115         <td>PLAYING</td>
 116         <td>ASYNC</td>
 117         </tr>
 118         <tr>
 119         <td>mm_player_stop()</td>
 120         <td>PLAYING</td>
 121         <td>READY</td>
 122         <td>SYNC</td>
 123         </tr>
 124         <tr>
 125         <td>mm_player_pause()</td>
 126         <td>PLAYING</td>
 127         <td>PAUSED</td>
 128         <td>ASYNC</td>
 129         </tr>
 130         <tr>
 131         <td>mm_player_resume()</td>
 132         <td>PAUSED</td>
 133         <td>PLAYING</td>
 134         <td>ASYNC</td>
 135         </tr>
 136         <tr>
 137         <td>mm_player_set_message_callback()</td>
 138         <td>N/A</td>
 139         <td>N/A</td>
 140         <td>SYNC</td>
 141         </tr>
 142         <tr>
 143         <td>mm_player_get_state()</td>
 144         <td>N/A</td>
 145         <td>N/A</td>
 146         <td>SYNC</td>
 147         </tr>
 148         <tr>
 149         <td>mm_player_set_volume()</td>
 150         <td>N/A</td>
 151         <td>N/A</td>
 152         <td>SYNC</td>
 153         </tr>
 154         <tr>
 155         <td>mm_player_get_volume()</td>
 156         <td>N/A</td>
 157         <td>N/A</td>
 158         <td>SYNC</td>
 159         </tr>
 160         <tr>
 161         <td>mm_player_set_position()</td>
 162         <td>N/A</td>
 163         <td>N/A</td>
 164         <td>SYNC</td>
 165         </tr>
 166         <tr>
 167         <td>mm_player_get_position()</td>
 168         <td>N/A</td>
 169         <td>N/A</td>
 170         <td>SYNC</td>
 171         </tr>
 172         <tr>
 173         <td>mm_player_get_attribute()</td>
 174         <td>N/A</td>
 175         <td>N/A</td>
 176         <td>SYNC</td>
 177         </tr>
 178         <tr>
 179         <td>mm_player_set_attribute()</td>
 180         <td>N/A</td>
 181         <td>N/A</td>
 182         <td>SYNC</td>
 183         </tr>
 184         </table></div>
 185
 186         @par
 187         Following are the attributes supported in player which may be set after initialization. \n
 188         Those are handled as a string.
 189
 190         @par
 191         <div><table>
 192         <tr>
 193         <td>PROPERTY</td>
 194         <td>TYPE</td>
 195         <td>VALID TYPE</td>
 196         </tr>
 197         <tr>
 198         <td>"profile_uri"</td>
 199         <td>string</td>
 200         <td>N/A</td>
 201         </tr>
 202         <tr>
 203         <td>"content_duration"</td>
 204         <td>int</td>
 205         <td>range</td>
 206         </tr>
 207         <tr>
 208         <td>"content_video_width"</td>
 209         <td>int</td>
 210         <td>range</td>
 211         </tr>
 212         <tr>
 213         <td>"content_video_height"</td>
 214         <td>int</td>
 215         <td>range</td>
 216         </tr>
 217         <tr>
 218         <td>"display_evas_do_scaling"</td>
 219         <td>int</td>
 220         <td>range</td>
 221         </tr>
 222         <tr>
 223         <td>"display_evas_surface_sink"</td>
 224         <td>string</td>
 225         <td>N/A</td>
 226         </tr>
 227         <tr>
 228         <td>"profile_user_param"</td>
 229         <td>data</td>
 230         <td>N/A</td>
 231         </tr>
 232         <tr>
 233         <td>"profile_play_count"</td>
 234         <td>int</td>
 235         <td>range</td>
 236         </tr>
 237         <tr>
 238         <td>"streaming_type"</td>
 239         <td>int</td>
 240         <td>range</td>
 241         </tr>
 242         <tr>
 243         <td>"streaming_udp_timeout"</td>
 244         <td>int</td>
 245         <td>range</td>
 246         </tr>
 247         <tr>
 248         <td>"streaming_user_agent"</td>
 249         <td>string</td>
 250         <td>N/A</td>
 251         </tr>
 252         <tr>
 253         <td>"streaming_wap_profile"</td>
 254         <td>string</td>
 255         <td>N/A</td>
 256         </tr>
 257         <tr>
 258         <td>"streaming_network_bandwidth"</td>
 259         <td>int</td>
 260         <td>range</td>
 261         </tr>
 262         <tr>
 263         <td>"streaming_cookie"</td>
 264         <td>string</td>
 265         <td>N/A</td>
 266         </tr>
 267         <tr>
 268         <td>"streaming_proxy_ip"</td>
 269         <td>string</td>
 270         <td>N/A</td>
 271         </tr>
 272         <tr>
 273         <td>"streaming_proxy_port"</td>
 274         <td>int</td>
 275         <td>range</td>
 276         </tr>
 277         <tr>
 278         <td>"streaming_timeout"</td>
 279         <td>int</td>
 280         <td>range</td>
 281         </tr>
 282         <tr>
 283         <td>"display_overlay"</td>
 284         <td>data</td>
 285         <td>N/A</td>
 286         </tr>
 287         <tr>
 288         <td>"display_rotation"</td>
 289         <td>int</td>
 290         <td>range</td>
 291         </tr>
 292         <tr>
 293         <td>"subtitle_uri"</td>
 294         <td>string</td>
 295         <td>N/A</td>
 296         </tr>
 297         </table></div>
 298
 299         @par
 300         Following attributes are supported for playing stream data. Those value can be readable only and valid after starting playback.\n
 301         Please use mm_fileinfo for local playback.
 302
 303         @par
 304         <div><table>
 305         <tr>
 306         <td>PROPERTY</td>
 307         <td>TYPE</td>
 308         <td>VALID TYPE</td>
 309         </tr>
 310         <tr>
 311         <td>"content_video_found"</td>
 312         <td>string</td>
 313         <td>N/A</td>
 314         </tr>
 315         <tr>
 316         <td>"content_video_codec"</td>
 317         <td>string</td>
 318         <td>N/A</td>
 319         </tr>
 320         <tr>
 321         <td>"content_video_track_num"</td>
 322         <td>int</td>
 323         <td>range</td>
 324         </tr>
 325         <tr>
 326         <td>"content_audio_found"</td>
 327         <td>string</td>
 328         <td>N/A</td>
 329         </tr>
 330         <tr>
 331         <td>"content_audio_codec"</td>
 332         <td>string</td>
 333         <td>N/A</td>
 334         </tr>
 335         <tr>
 336         <td>"content_audio_bitrate"</td>
 337         <td>int</td>
 338         <td>array</td>
 339         </tr>
 340         <tr>
 341         <td>"content_audio_channels"</td>
 342         <td>int</td>
 343         <td>range</td>
 344         </tr>
 345         <tr>
 346         <td>"content_audio_samplerate"</td>
 347         <td>int</td>
 348         <td>array</td>
 349         </tr>
 350         <tr>
 351         <td>"content_audio_track_num"</td>
 352         <td>int</td>
 353         <td>range</td>
 354         </tr>
 355         <tr>
 356         <td>"content_text_track_num"</td>
 357         <td>int</td>
 358         <td>range</td>
 359         </tr>
 360         <tr>
 361         <td>"tag_artist"</td>
 362         <td>string</td>
 363         <td>N/A</td>
 364         </tr>
 365         <tr>
 366         <td>"tag_title"</td>
 367         <td>string</td>
 368         <td>N/A</td>
 369         </tr>
 370         <tr>
 371         <td>"tag_album"</td>
 372         <td>string</td>
 373         <td>N/A</td>
 374         </tr>
 375         <tr>
 376         <td>"tag_genre"</td>
 377         <td>string</td>
 378         <td>N/A</td>
 379         </tr>
 380         <tr>
 381         <td>"tag_author"</td>
 382         <td>string</td>
 383         <td>N/A</td>
 384         </tr>
 385         <tr>
 386         <td>"tag_copyright"</td>
 387         <td>string</td>
 388         <td>N/A</td>
 389         </tr>
 390         <tr>
 391         <td>"tag_date"</td>
 392         <td>string</td>
 393         <td>N/A</td>
 394         </tr>
 395         <tr>
 396         <td>"tag_description"</td>
 397         <td>string</td>
 398         <td>N/A</td>
 399         </tr>
 400         <tr>
 401         <td>"tag_track_num"</td>
 402         <td>int</td>
 403         <td>range</td>
 404         </tr>
 405         </table></div>
 406
 407  */
 408
 409
 410 /*===========================================================================================
 411 |                                                                                           |
 412 |  GLOBAL DEFINITIONS AND DECLARATIONS                                        |
 413 |                                                                                           |
 414 ========================================================================================== */
 415
 416 /**
 417  * MM_PLAYER_URI:
 418  *
 419  * uri to play (string)
 420  *
 421  */
 422 #define MM_PLAYER_CONTENT_URI                                   "profile_uri"
 423 /**
 424  * MM_PLAYER_CONTENT_DURATION:
 425  *
 426  * get the duration (int) as millisecond, It's guaranteed after calling mm_player_start() or
 427  * receiving MM_MESSAGE_BEGIN_OF_STREAM.
 428  *
 429  */
 430 #define MM_PLAYER_CONTENT_DURATION                      "content_duration"
 431 /**
 432  * MM_PLAYER_VIDEO_ROTATION
 433  *
 434  * can change video angle (int)
 435  * @see MMDisplayRotationType
 436  */
 437 #define MM_PLAYER_VIDEO_ROTATION                                "display_rotation"
 438 /**
 439  * MM_PLAYER_VIDEO_WIDTH:
 440  *
 441  * get the video width (int), It's guaranteed after calling mm_player_start() or
 442  * receiving MM_MESSAGE_BEGIN_OF_STREAM.
 443  *
 444  */
 445 #define MM_PLAYER_VIDEO_WIDTH                           "content_video_width"
 446 /**
 447  * MM_PLAYER_VIDEO_HEIGHT:
 448  *
 449  * get the video height (int), It's guaranteed after calling mm_player_start() or
 450  * receiving MM_MESSAGE_BEGIN_OF_STREAM.
 451  *
 452  */
 453 #define MM_PLAYER_VIDEO_HEIGHT                          "content_video_height"
 454 /**
 455  * MM_PLAYER_VIDEO_EVAS_SURFACE_DO_SCALING:
 456  *
 457  * set whether or not to scale frames size for evas surface.
 458  * if TRUE, it scales down width, height size of frames with given size.
 459  * if FALSE, it does not scale down any frames.
 460  *
 461  */
 462 #define MM_PLAYER_VIDEO_EVAS_SURFACE_DO_SCALING         "display_evas_do_scaling"
 463 /**
 464  * MM_PLAYER_VIDEO_EVAS_SURFACE_SINK:
 465  *
 466  * get the video evas surface sink plugin name (string), It's guaranteed after calling mm_player_create()
 467  *
 468  */
 469 #define MM_PLAYER_VIDEO_EVAS_SURFACE_SINK               "display_evas_surface_sink"
 470 /**
 471  * MM_PLAYER_MEM_SRC:
 472  *
 473  * set memory pointer to play (data)
 474  *
 475  */
 476 #define MM_PLAYER_MEMORY_SRC                                    "profile_user_param"
 477 /**
 478  * MM_PLAYER_PLAYBACK_COUNT
 479  *
 480  * can set playback count (int), Default value is 1 and -1 is for infinity playing until releasing it.
 481  *
 482  */
 483 #define MM_PLAYER_PLAYBACK_COUNT                                "profile_play_count"
 484 /**
 485  * MM_PLAYER_SUBTITLE_URI
 486  *
 487  * set the subtitle path (string)
 488  */
 489 #define MM_PLAYER_SUBTITLE_URI                                  "subtitle_uri"
 490 /**
 491  * MM_PLAYER_STREAMING_TYPE
 492  *
 493  * set the streaming type (int)
 494  * @see MMStreamingType
 495  */
 496 #define MM_PLAYER_STREAMING_TYPE                                "streaming_type"
 497 /**
 498  * MM_PLAYER_STREAMING_UDP_TIMEOUT
 499  *
 500  * set the streaming udp timeout(int)
 501  */
 502 #define MM_PLAYER_STREAMING_UDP_TIMEOUT         "streaming_udp_timeout"
 503 /**
 504  * MM_PLAYER_STREAMING_USER_AGENT
 505  *
 506  * set the streaming user agent (string)
 507  */
 508 #define MM_PLAYER_STREAMING_USER_AGENT          "streaming_user_agent"
 509 /**
 510  * MM_PLAYER_STREAMING_WAP_PROFILE
 511  *
 512  * set the streaming wap profile (int)
 513  */
 514 #define MM_PLAYER_STREAMING_WAP_PROFILE         "streaming_wap_profile"
 515 /**
 516  * MM_PLAYER_STREAMING_NET_BANDWIDTH
 517  *
 518  * set the streaming network bandwidth (int)
 519  */
 520 #define MM_PLAYER_STREAMING_NET_BANDWIDTH       "streaming_network_bandwidth"
 521 /**
 522  * MM_PLAYER_STREAMING_COOKIE
 523  *
 524  * set the streaming cookie (int)
 525  */
 526 #define MM_PLAYER_STREAMING_COOKIE                      "streaming_cookie"
 527 /**
 528  * MM_PLAYER_STREAMING_PROXY_IP
 529  *
 530  * set the streaming proxy ip (string)
 531  */
 532 #define MM_PLAYER_STREAMING_PROXY_IP                    "streaming_proxy_ip"
 533 /**
 534  * MM_PLAYER_STREAMING_PROXY_PORT
 535  *
 536  * set the streaming proxy port (int)
 537  */
 538 #define MM_PLAYER_STREAMING_PROXY_PORT          "streaming_proxy_port"
 539 /**
 540  * MM_PLAYER_STREAMING_TIMEOUT
 541  *
 542  * set the streaming timeout (int)
 543  */
 544 #define MM_PLAYER_STREAMING_TIMEOUT                     "streaming_timeout"
 545 /**
 546  * MM_PLAYER_VIDEO_CODEC
 547  *
 548  * codec the video data is stored in (string)
 549  */
 550 #define MM_PLAYER_VIDEO_CODEC                           "content_video_codec"
 551 /**
 552  * MM_PLAYER_VIDEO_TRACK_NUM
 553  *
 554  * track number inside a collection  (int)
 555  */
 556 #define MM_PLAYER_VIDEO_TRACK_NUM                       "content_video_track_num"
 557 /**
 558  * MM_PLAYER_AUDIO_CODEC
 559  *
 560  * codec the audio data is stored in (string)
 561  */
 562 #define MM_PLAYER_AUDIO_CODEC                           "content_audio_codec"
 563 /**
 564  * MM_PLAYER_AUDIO_BITRATE
 565  *
 566  * set the streaming proxy port (int)
 567  */
 568 #define MM_PLAYER_AUDIO_BITRATE                         "content_audio_bitrate"
 569 /**
 570  * MM_PLAYER_AUDIO_CHANNEL
 571  *
 572  * the number of audio channel (int)
 573  */
 574 #define MM_PLAYER_AUDIO_CHANNEL                         "content_audio_channels"
 575 /**
 576  * MM_PLAYER_AUDIO_SAMPLERATE
 577  *
 578  * audio samplerate  (int)
 579  */
 580 #define MM_PLAYER_AUDIO_SAMPLERATE                      "content_audio_samplerate"
 581 /**
 582  * MM_PLAYER_AUDIO_TRACK_NUM
 583  *
 584  * track number inside a collection (int)
 585  */
 586 #define MM_PLAYER_AUDIO_TRACK_NUM                       "content_audio_track_num"
 587 /**
 588  * MM_PLAYER_TEXT_TRACK_NUM
 589  *
 590  * track number inside a collection (int)
 591  */
 592 #define MM_PLAYER_TEXT_TRACK_NUM                        "content_text_track_num"
 593 /**
 594  * MM_PLAYER_TAG_ARTIST
 595  *
 596  * person(s) responsible for the recording (string)
 597  */
 598 #define MM_PLAYER_TAG_ARTIST                                    "tag_artist"
 599 /**
 600  * MM_PLAYER_TAG_ARTIST
 601  *
 602  * title (string)
 603  */
 604 #define MM_PLAYER_TAG_TITLE                                     "tag_title"
 605 /**
 606  * MM_PLAYER_TAG_ARTIST
 607  *
 608  * album containing this data (string)
 609  */
 610 #define MM_PLAYER_TAG_ALBUM                                     "tag_album"
 611 /**
 612  * MM_PLAYER_TAG_ARTIST
 613  *
 614  * genre this data belongs to (string)
 615  */
 616 #define MM_PLAYER_TAG_GENRE                                     "tag_genre"
 617 /**
 618  * MM_PLAYER_TAG_ARTIST
 619  *
 620  * author (string)
 621  */
 622 #define MM_PLAYER_TAG_AUTHOUR                           "tag_author"
 623 /**
 624  * MM_PLAYER_TAG_ARTIST
 625  *
 626  * copyright notice of the data (string)
 627  */
 628 #define MM_PLAYER_TAG_COPYRIGHT                         "tag_copyright"
 629 /**
 630  * MM_PLAYER_TAG_ARTIST
 631  *
 632  * date the data was created (string)
 633  */
 634 #define MM_PLAYER_TAG_DATE                                      "tag_date"
 635 /**
 636  * MM_PLAYER_TAG_ARTIST
 637  *
 638  * short text describing the content of the data (string)
 639  */
 640 #define MM_PLAYER_TAG_DESCRIPRION                               "tag_description"
 641 /**
 642  * MM_PLAYER_TAG_ARTIST
 643  *
 644  * track number inside a collection (int)
 645  */
 646 #define MM_PLAYER_TAG_TRACK_NUM                         "tag_track_num"
 647 /**
 648  * MM_PLAYER_PD_MODE
 649  *
 650  * progressive download mode (int)
 651  */
 652 #define MM_PLAYER_PD_MODE                                               "pd_mode"
 653
 654 #define BUFFER_MAX_PLANE_NUM (4)
 655
 656 typedef struct {
 657         MMPixelFormatType format;                       /**< image format */
 658         int width;                                              /**< width of video buffer */
 659         int height;                                             /**< height of video buffer */
 660         unsigned int timestamp;                         /**< timestamp of stream buffer (msec)*/
 661         unsigned int length_total;                      /**< total length of stream buffer (in byte)*/
 662         void *data;
 663         void *bo[BUFFER_MAX_PLANE_NUM];  /**< TBM buffer object */
 664         void *internal_buffer;                          /**< Internal buffer pointer */
 665         int stride[BUFFER_MAX_PLANE_NUM];               /**< stride of plane */
 666         int elevation[BUFFER_MAX_PLANE_NUM];    /**< elevation of plane */
 667 }MMPlayerVideoStreamDataType;
 668
 669 /**
 670  * Enumerations of player state.
 671  */
 672 typedef enum {
 673         MM_PLAYER_STATE_NULL,                           /**< Player is created, but not realized yet */
 674         MM_PLAYER_STATE_READY,                          /**< Player is ready to play media */
 675         MM_PLAYER_STATE_PLAYING,                        /**< Player is now playing media */
 676         MM_PLAYER_STATE_PAUSED,                         /**< Player is paused while playing media */
 677         MM_PLAYER_STATE_NONE,                           /**< Player is not created yet */
 678         MM_PLAYER_STATE_NUM,                            /**< Number of player states */
 679 } MMPlayerStateType;
 680
 681 /**
 682  * Enumerations of position formats.
 683  * Used while invoking mm_player_get_position/mm_player_set_position APIs
 684  */
 685 typedef enum {
 686         MM_PLAYER_POS_FORMAT_TIME,                      /**< Format for time based */
 687         MM_PLAYER_POS_FORMAT_PERCENT,                   /**< Format for percentage */
 688         MM_PLAYER_POS_FORMAT_NUM,                       /**< Number of position formats */
 689 } MMPlayerPosFormatType;
 690
 691 /**
 692  * Enumeration for attribute values types.
 693  */
 694 typedef enum {
 695  MM_PLAYER_ATTRS_TYPE_INVALID = -1,        /**< Type is invalid */
 696  MM_PLAYER_ATTRS_TYPE_INT,                 /**< Integer type */
 697  MM_PLAYER_ATTRS_TYPE_DOUBLE,              /**< Double type */
 698  MM_PLAYER_ATTRS_TYPE_STRING,              /**< UTF-8 String type */
 699  MM_PLAYER_ATTRS_TYPE_DATA,                /**< Pointer type */
 700  MM_PLAYER_ATTRS_TYPE_ARRAY,               /**< Array type */
 701  MM_PLAYER_ATTRS_TYPE_RANGE,               /**< Range type */
 702  MM_PLAYER_ATTRS_TYPE_NUM,                 /**< Number of attribute type */
 703 } MMPlayerAttrsType;
 704
 705 /**
 706  * Enumeration for attribute validation type.
 707  */
 708 typedef enum {
 709  MM_PLAYER_ATTRS_VALID_TYPE_INVALID = -1,               /**< Invalid validation type */
 710  MM_PLAYER_ATTRS_VALID_TYPE_NONE,                               /**< Do not check validity */
 711  MM_PLAYER_ATTRS_VALID_TYPE_INT_ARRAY,          /**< validity checking type of integer array */
 712  MM_PLAYER_ATTRS_VALID_TYPE_INT_RANGE,          /**< validity checking type of integer range */
 713  MM_PLAYER_ATTRS_VALID_TYPE_DOUBLE_ARRAY,               /**< validity checking type of double array */
 714  MM_PLAYER_ATTRS_VALID_TYPE_DOUBLE_RANGE,       /**< validity checking type of double range */
 715 } MMPlayerAttrsValidType;
 716
 717 /**
 718  * Enumeration for attribute access flag.
 719  */
 720 typedef enum {
 721  MM_PLAYER_ATTRS_FLAG_NONE = 0,                                 /**< None flag is set */
 722  MM_PLAYER_ATTRS_FLAG_READABLE = 1 << 0,                        /**< Readable */
 723  MM_PLAYER_ATTRS_FLAG_WRITABLE = 1 << 1,                        /**< Writable */
 724  MM_PLAYER_ATTRS_FLAG_MODIFIED = 1 << 2,                        /**< Modified */
 725
 726  MM_PLAYER_ATTRS_FLAG_RW = MM_PLAYER_ATTRS_FLAG_READABLE | MM_PLAYER_ATTRS_FLAG_WRITABLE, /**< Readable and Writable */
 727 } MMPlayerAttrsFlag;
 728
 729 /**
 730  * Enumeration for progressive download
 731  */
 732 typedef enum {
 733         MM_PLAYER_PD_MODE_NONE,
 734         MM_PLAYER_PD_MODE_URI,
 735         MM_PLAYER_PD_MODE_FILE  // not tested yet, because of no fixed scenario
 736 }MMPlayerPDMode;
 737
 738 /**
 739  * Enumeration of track types
 740  */
 741 typedef enum {
 742         MM_PLAYER_TRACK_TYPE_AUDIO = 0,
 743         MM_PLAYER_TRACK_TYPE_VIDEO,
 744         MM_PLAYER_TRACK_TYPE_TEXT,
 745         MM_PLAYER_TRACK_TYPE_MAX
 746 }MMPlayerTrackType;
 747
 748 /**
 749  * Enumeration of runtime buffering mode
 750  */
 751 typedef enum {
 752         MM_PLAYER_BUFFERING_MODE_ADAPTIVE = 0,  /**< default, If buffering is occurred, player will consider the bandwidth to adjust buffer setting. */
 753         MM_PLAYER_BUFFERING_MODE_FIXED,                 /**< player will set buffer size with this fixed size value. */
 754         MM_PLAYER_BUFFERING_MODE_SLINK,                 /**< If buffering is occurred, player will adjust buffer setting and no more buffering will be occurred again. */
 755         MM_PLAYER_BUFFERING_MODE_MAX = MM_PLAYER_BUFFERING_MODE_SLINK,
 756 }MMPlayerBufferingMode;
 757
 758 /**
 759  * Enumeration of audio channel for video share
 760  */
 761 typedef enum
 762 {
 763         MM_PLAYER_AUDIO_CH_MONO_LEFT = 0,
 764         MM_PLAYER_AUDIO_CH_MONO_RIGHT,
 765         MM_PLAYER_AUDIO_CH_STEREO,
 766 } MMPlayerAudioChannel;
 767
 768 /**
 769  * Edge Properties of the text.
 770  */
 771 typedef enum {
 772         MM_PLAYER_EDGE_NO,
 773         MM_PLAYER_EDGE_RAISED,
 774         MM_PLAYER_EDGE_DEPRESSED,
 775         MM_PLAYER_EDGE_UNIFORM,
 776         MM_PLAYER_EDGE_DROPSHADOW
 777 } MMPlayerSubtitleEdge;
 778
 779
 780 /**
 781  * Attribute validity structure
 782  */
 783 typedef struct {
 784          MMPlayerAttrsType type;
 785          MMPlayerAttrsValidType validity_type;
 786          MMPlayerAttrsFlag flag;
 787         /**
 788           * a union that describes validity of the attribute.
 789           * Only when type is 'MM_ATTRS_TYPE_INT' or 'MM_ATTRS_TYPE_DOUBLE',
 790           * the attribute can have validity.
 791          */
 792          union {
 793                 /**
 794                    * Validity structure for integer array.
 795                  */
 796                 struct {
 797                         int *array;  /**< a pointer of array */
 798                         int count;   /**< size of array */
 799                         int d_val;
 800                 } int_array;
 801                 /**
 802                    * Validity structure for integer range.
 803                  */
 804                 struct {
 805                         int min;   /**< minimum range */
 806                         int max;   /**< maximum range */
 807                         int d_val;
 808                 } int_range;
 809                 /**
 810                 * Validity structure for double array.
 811                 */
 812                 struct {
 813                         double   * array;  /**< a pointer of array */
 814                         int    count;   /**< size of array */
 815                         double d_val;
 816                 } double_array;
 817                 /**
 818                 * Validity structure for double range.
 819                 */
 820                 struct {
 821                         double   min;   /**< minimum range */
 822                         double   max;   /**< maximum range */
 823                         double d_val;
 824                 } double_range;
 825         };
 826 } MMPlayerAttrsInfo;
 827
 828 /**
 829  * Volume type.
 830  *
 831  * @see         mm_player_set_volume, mm_player_get_volume
 832  */
 833 typedef struct {
 834         float   level[MM_VOLUME_CHANNEL_NUM];   /**< Relative volume factor for each channels */
 835 } MMPlayerVolumeType;
 836
 837 /**
 838  * Audio stream callback function type.
 839  *
 840  * @param       stream          [in]    Reference pointer to audio frame data
 841  * @param       stream_size     [in]    Size of audio frame data
 842  * @param       user_param      [in]    User defined parameter which is passed when set
 843  *                                                              audio stream callback
 844  *
 845  * @return      This callback function have to return MM_ERROR_NONE.
 846  */
 847 typedef bool    (*mm_player_audio_stream_callback) (void *stream, int stream_size, void *user_param);
 848
 849
 850 /**
 851  * selected subtitle track number callback function type.
 852  *
 853  * @param       track_num       [in]    Track number of subtitle
 854  * @param       user_param      [in]    User defined parameter
 855  *
 856  *
 857  * @return      This callback function have to return MM_ERROR_NONE.
 858  */
 859 typedef bool            (*mm_player_track_selected_subtitle_language_callback)(int track_num, void *user_param);
 860
 861
 862 /*===========================================================================================
 863 |                                                                                           |
 864 |  GLOBAL FUNCTION PROTOTYPES                                        |
 865 |                                                                                           |
 866 ========================================================================================== */
 867
 868 /**
 869  * This function creates a player object for playing multimedia contents. \n
 870  * The attributes of player are created to get/set some values with application. \n
 871  * And, mutex, gstreamer and other resources are initialized at this time. \n
 872  * If player is created, the state will become MM_PLAYER_STATE_NULL.
 873  *
 874  * @param       player          [out]   Handle of player
 875  *
 876  * @return      This function returns zero on success, or negative value with error code. \n
 877  *                      Please refer 'mm_error.h' to know it in detail.
 878  * @pre         None
 879  * @post        MM_PLAYER_STATE_NULL
 880  * @see         mm_player_destroy
 881  * @remark      You can create multiple handles on a context at the same time. \n
 882  *                      However, player cannot guarantee proper operation because of limitation of resources, \n
 883  *                      such as audio device or display device.
 884  *
 885  * @par Example
 886  * @code
 887 char *g_err_attr_name = NULL;
 888
 889 if (mm_player_create(&g_player) != MM_ERROR_NONE)
 890 {
 891         debug_error("failed to create player\n");
 892 }
 893
 894 if (mm_player_set_attribute(g_player,
 895                                                 &g_err_attr_name,
 896                                                 "profile_uri", filename, strlen(filename),
 897                                                 "display_overlay", (void*)&g_win.xid, sizeof(g_win.xid),
 898                                                 NULL) != MM_ERROR_NONE)
 899 {
 900         debug_error("failed to set %s attribute\n", g_err_attr_name);
 901         free(g_err_attr_name);
 902 }
 903
 904 mm_player_set_message_callback(g_player, msg_callback, (void*)g_player);
 905  * @endcode
 906  */
 907 int mm_player_create(MMHandleType *player);
 908
 909 /**
 910  * This function releases player object and all resources which were created by mm_player_create(). \n
 911  * And, player handle will also be destroyed.
 912  *
 913  * @param       player          [in]    Handle of player
 914  *
 915  * @return      This function returns zero on success, or negative value with error code.
 916  * @pre         Player state may be MM_PLAYER_STATE_NULL. \n
 917  *                      But, it can be called in any state.
 918  * @post                Because handle is released, there is no any state.
 919  * @see         mm_player_create
 920  * @remark      This method can be called with a valid player handle from any state to \n
 921  *                      completely shutdown the player operation.
 922  *
 923  * @par Example
 924  * @code
 925 if (mm_player_destroy(g_player) != MM_ERROR_NONE)
 926 {
 927         debug_error("failed to destroy player\n");
 928 }
 929  * @endcode
 930  */
 931 int mm_player_destroy(MMHandleType player);
 932
 933 /**
 934  * This function parses uri and makes gstreamer pipeline by uri scheme. \n
 935  * So, uri should be set before realizing with mm_player_set_attribute(). \n
 936  *
 937  * @param       player          [in]    Handle of player
 938  *
 939  * @return      This function returns zero on success, or negative value with error code.
 940  *
 941  * @pre         Player state should be MM_PLAYER_STATE_NULL.
 942  * @post                Player state will be MM_PLAYER_STATE_READY.
 943  * @see         mm_player_unrealize
 944  * @remark      None
 945  * @par Example
 946  * @code
 947 if (mm_player_realize(g_player) != MM_ERROR_NONE)
 948 {
 949         debug_error("failed to realize player\n");
 950 }
 951  * @endcode
 952  */
 953 int mm_player_realize(MMHandleType player) ;
 954
 955 /**
 956  * This function uninitializes player object. So, resources and allocated memory \n
 957  * will be freed. And, gstreamer pipeline is also destroyed. So, if you want to play \n
 958  * other contents, player should be created again after destruction or realized with new uri.
 959  *
 960  * @param       player          [in]    Handle of player
 961  *
 962  * @return      This function returns zero on success, or negative value with error code.
 963  * @pre         Player state may be MM_PLAYER_STATE_READY to unrealize. \n
 964  *                      But, it can be called in any state.
 965  * @post                Player state will be MM_PLAYER_STATE_NULL.
 966  * @see         mm_player_realize
 967  * @remark      This method can be called with a valid player handle from any state.
 968  *
 969  * @par Example
 970  * @code
 971 if (mm_player_unrealize(g_player) != MM_ERROR_NONE)
 972 {
 973         debug_error("failed to unrealize player\n");
 974 }
 975  * @endcode
 976  */
 977 int mm_player_unrealize(MMHandleType player);
 978
 979 /**
 980  * This function is to get current state of player. \n
 981  * Application have to check current state before doing some action.
 982  *
 983  * @param       player          [in]    Handle of player
 984  * @param       state       [out] current state of player on success
 985  *
 986  * @return      This function returns zero on success, or negative value with error code.
 987  *
 988  * @see         MMPlayerStateType
 989  * @remark      None
 990  * @par Example
 991  * @code
 992 if (mm_player_get_state(g_player, &state) != MM_ERROR_NONE)
 993 {
 994         debug_error("failed to get state\n");
 995 }
 996  * @endcode
 997  */
 998 int mm_player_get_state(MMHandleType player, MMPlayerStateType *state);
 999
1000 /**
1001  * This function is to set relative volume of player. \n
1002  * So, It controls logical volume value. \n
1003  * But, if developer want to change system volume, mm sound api should be used.
1004  *
1005  * @param       player          [in]    Handle of player
1006  * @param       volume          [in]    Volume factor of each channel
1007  *
1008  * @return      This function returns zero on success, or negative value with error code.
1009  * @see         MMPlayerVolumeType, mm_player_get_volume
1010  * @remark      The range of factor range is from 0 to 1.0. (1.0 = 100%) And, default value is 1.0.
1011  * @par Example
1012  * @code
1013 MMPlayerVolumeType volume;
1014 int i = 0;
1015
1016 for (i = 0; i < MM_VOLUME_CHANNEL_NUM; i++)
1017         volume.level[i] = MM_VOLUME_LEVEL_MAX;
1018
1019 if (mm_player_set_volume(g_player, &volume) != MM_ERROR_NONE)
1020 {
1021     debug_error("failed to set volume\n");
1022 }
1023  * @endcode
1024  */
1025 int mm_player_set_volume(MMHandleType player, MMPlayerVolumeType *volume);
1026
1027 /**
1028  * This function is to get current volume factor of player.
1029  *
1030  * @param       player          [in]    Handle of player.
1031  * @param       volume          [out]   Volume factor of each channel.
1032  *
1033  * @return      This function returns zero on success, or negative value with error code.
1034  *
1035  * @see         MMPlayerVolumeType, mm_player_set_volume
1036  * @remark      None
1037  * @par Example
1038  * @code
1039 MMPlayerVolumeType volume;
1040 int i;
1041
1042 if (mm_player_get_volume(g_player, &volume) != MM_ERROR_NONE)
1043 {
1044         debug_warning("failed to get volume\n");
1045 }
1046
1047 for (i = 0; i < MM_VOLUME_CHANNEL_NUM; i++)
1048         debug_log("channel[%d] = %d \n", i, volume.level[i]);
1049  * @endcode
1050  */
1051 int mm_player_get_volume(MMHandleType player, MMPlayerVolumeType *volume);
1052
1053 /**
1054  * This function is to start playing media contents. Demux(parser), codec and related plugins are decided \n
1055  * at this time. And, MM_MESSAGE_BEGIN_OF_STREAM will be posted through callback function registered \n
1056  * by mm_player_set_message_callback().
1057  *
1058  * @param       player          [in]    Handle of player
1059  *
1060  * @return      This function returns zero on success, or negative value with error code.
1061  * @remark
1062  *
1063  * @pre         Player state may be MM_PLAYER_STATE_READY.
1064  * @post                Player state will be MM_PLAYER_STATE_PLAYING.
1065  * @see         mm_player_stop
1066  * @remark      None
1067  * @par Example
1068  * @code
1069 if (mm_player_start(g_player) != MM_ERROR_NONE)
1070 {
1071         debug_error("failed to start player\n");
1072 }
1073  * @endcode
1074  */
1075 int mm_player_start(MMHandleType player);
1076
1077 /**
1078  * This function is to stop playing media contents and it's different with pause. \n
1079  * If mm_player_start() is called after this, content will be started again from the beginning. \n
1080  * So, it can be used to close current playback.
1081  *
1082  * @param       player          [in]    Handle of player
1083  *
1084  * @return      This function returns zero on success, or negative value with error code.
1085  *
1086  * @pre         Player state may be MM_PLAYER_STATE_PLAYING.
1087  * @post                Player state will be MM_PLAYER_STATE_READY.
1088  * @see         mm_player_start
1089  * @remark      None
1090  * @par Example
1091  * @code
1092 if (mm_player_stop(g_player) != MM_ERROR_NONE)
1093 {
1094         debug_error("failed to stop player\n");
1095 }
1096  * @endcode
1097  */
1098 int mm_player_stop(MMHandleType player);
1099
1100 /**
1101  * This function is to pause playing media contents.
1102  *
1103  * @param       player          [in]    Handle of player.
1104  *
1105  * @return      This function returns zero on success, or negative value with error code.
1106  *
1107  * @pre         Player state may be MM_PLAYER_STATE_PLAYING.
1108  * @post                Player state will be MM_PLAYER_STATE_PAUSED.
1109  * @see         mm_player_resume
1110  * @remark      None
1111  * @par Example
1112  * @code
1113 if (mm_player_pause(g_player) != MM_ERROR_NONE)
1114 {
1115         debug_error("failed to pause player\n");
1116 }
1117  * @endcode
1118  */
1119 int mm_player_pause(MMHandleType player);
1120
1121 /**
1122  * This function is to resume paused media contents.
1123  *
1124  * @param       player          [in]    Handle of player.
1125  *
1126  * @return      This function returns zero on success, or negative value with error code.
1127  *
1128  * @pre         Player state may be MM_PLAYER_STATE_PAUSED.
1129  * @post                Player state will be MM_PLAYER_STATE_PLAYING.
1130  * @see         mm_player_pause
1131  * @remark      None
1132  * @par Example
1133  * @code
1134 if (mm_player_resume(g_player) != MM_ERROR_NONE)
1135 {
1136         debug_error("failed to resume player\n");
1137 }
1138  * @endcode
1139  */
1140 int mm_player_resume(MMHandleType player);
1141
1142 /**
1143  * This function is to set the position for playback. \n
1144  * So, it can be seeked to requested position. \n
1145  *
1146  * @param       player          [in]    Handle of player
1147  * @param       format          [in]    Format of position.
1148  * @param       pos                     [in]    Position for playback
1149  *
1150  * @return      This function returns zero on success, or negative value with error code.
1151  * @see         MMPlayerPosFormatType, mm_player_get_position
1152  * @remark  the unit of time-based format is millisecond and other case is percent.
1153  * @par Example
1154  * @code
1155 int position = 1000; //1sec
1156
1157 if (mm_player_set_position(g_player, MM_PLAYER_POS_FORMAT_TIME, position) != MM_ERROR_NONE)
1158 {
1159         debug_error("failed to set position\n");
1160 }
1161  * @endcode
1162  */
1163 int mm_player_set_position(MMHandleType player, MMPlayerPosFormatType format, int pos);
1164
1165 /**
1166  * This function is to get current position of playback content.
1167  *
1168  * @param       player          [in]    Handle of player.
1169  * @param       format          [in]    Format of position.
1170  * @param    pos        [out] contains current position on success or zero in case of failure.
1171  *
1172  * @return      This function returns zero on success, or negative value with errors
1173  * @see         MMPlayerPosFormatType, mm_player_set_position
1174  * @remark      the unit of time-based format is millisecond and other case is percent.
1175  * @par Example
1176  * @code
1177 int position = 0;
1178 int duration = 0;
1179
1180 mm_player_get_position(g_player, MM_PLAYER_POS_FORMAT_TIME, &position);
1181
1182 mm_player_get_attribute(g_player, &g_err_name, "content_duration", &duration, NULL);
1183
1184 debug_log("pos: [%d/%d] msec\n", position, duration);
1185  * @endcode
1186  */
1187 int mm_player_get_position(MMHandleType player, MMPlayerPosFormatType format, int *pos);
1188
1189 /**
1190  * This function is to get current buffer position of playback content.
1191  *
1192  * @param       player          [in]    Handle of player.
1193  * @param       format          [in]    Format of position.
1194  * @param       start_pos               [out] contains buffer start  position on success or zero in case of failure.
1195  * @param       stop_pos        [out] contains buffer current  position on success or zero in case of failure.
1196  *
1197  * @return      This function returns zero on success, or negative value with errors
1198  * @see         MMPlayerPosFormatType, mm_player_set_position
1199  * @remark      the unit of time-based format is millisecond and other case is percent.
1200  * @par Example
1201  * @code
1202 int start_pos = 0, stop_pos = 0;
1203
1204 mm_player_get_buffer_position(g_player, MM_PLAYER_POS_FORMAT_PERCENT, &start_pos, &stop_pos );
1205
1206 debug_log("buffer position: [%d] ~ [%d] \%\n", start_pos, stop_pos );
1207  * @endcode
1208  */
1209 int mm_player_get_buffer_position(MMHandleType player, MMPlayerPosFormatType format, int *start_pos, int *stop_pos);
1210
1211 /**
1212  * This function is to activate the section repeat. If it's set, selected section will be played \n
1213  * continually before deactivating it by mm_player_deactivate_section_repeat(). \n
1214  * The unit for setting is millisecond.
1215  *
1216  * @param       player          [in]    Handle of player.
1217  * @param       start_pos               [in]    start position.
1218  * @param       end_pos                 [in]    end position.
1219  *
1220  * @return      This function returns zero on success, or negative value with error code.
1221  * @see         mm_player_deactivate_section_repeat
1222  * @remark      None
1223  * @par Example
1224  * @code
1225 int position;
1226 int endtime = 4000; //msec
1227
1228 mm_player_get_position(g_player, MM_PLAYER_POS_FORMAT_TIME, &position);
1229
1230 mm_player_activate_section_repeat(g_player, position, position+endtime);
1231  * @endcode
1232  */
1233 int mm_player_activate_section_repeat(MMHandleType player, int start_pos, int end_pos);
1234
1235 /**
1236  * This function is to deactivate the section repeat.
1237  *
1238  * @param       player          [in]    Handle of player.
1239  *
1240  * @return      This function returns zero on success, or negative value with error code.
1241  * @see         mm_player_activate_section_repeat
1242  * @remark      None
1243  * @par Example
1244  * @code
1245 if ( mm_player_deactivate_section_repeat(g_player) != MM_ERROR_NONE)
1246 {
1247         debug_warning("failed to deactivate section repeat\n");
1248 }
1249  * @endcode
1250  */
1251 int mm_player_deactivate_section_repeat(MMHandleType player);
1252
1253 /**
1254  * This function sets callback function for receiving messages from player.
1255  * So, player can notify warning, error and normal cases to application.
1256  *
1257  * @param       player          [in]    Handle of player.
1258  * @param       callback        [in]    Message callback function.
1259  * @param       user_param      [in]    User parameter which is passed to callback function.
1260  *
1261  * @return      This function returns zero on success, or negative value with error code.
1262  * @see         MMMessageCallback
1263  * @remark      None
1264  * @par Example
1265  * @code
1266 int msg_callback(int message, MMMessageParamType *param, void *user_param)
1267 {
1268         switch (message)
1269         {
1270                 case MM_MESSAGE_ERROR:
1271                         //do something
1272                         break;
1273
1274                 case MM_MESSAGE_END_OF_STREAM:
1275                         //do something
1276                         break;
1277
1278                 case MM_MESSAGE_STATE_CHANGED:
1279                         //do something
1280                         break;
1281
1282                 case MM_MESSAGE_BEGIN_OF_STREAM:
1283                         //do something
1284                         break;
1285
1286                 default:
1287                         break;
1288         }
1289         return TRUE;
1290 }
1291
1292 mm_player_set_message_callback(g_player, msg_callback, (void*)g_player);
1293  * @endcode
1294  */
1295 int mm_player_set_message_callback(MMHandleType player, MMMessageCallback callback, void *user_param);
1296
1297 /**
1298  * This function set callback function for receiving audio stream from player. \n
1299  * So, application can get raw audio data and modify it. \n
1300  * But, if callback don't return or holds it for long time, performance can be deteriorated. \n
1301  * It's only supported when audio stream is included in file. \n
1302  * So, if there is video stream or DRM content, it can't be used.
1303  *
1304  * @param       player          [in]    Handle of player.
1305  * @param       callback                [in]    Audio stream callback function.
1306  * @param       user_param      [in]    User parameter.
1307  *
1308  * @return      This function returns zero on success, or negative value with error
1309  *                      code.
1310  * @see         mm_player_audio_stream_callback
1311  * @remark      It can be used for audio playback only.
1312  * @par Example
1313  * @code
1314 bool audio_callback(void *stream, int stream_size, void *user_param)
1315 {
1316         debug_log("audio stream callback\n");
1317         return TRUE;
1318 }
1319 mm_player_set_audio_stream_callback(g_player, audio_callback, NULL);
1320  * @endcode
1321  */
1322  int mm_player_set_audio_stream_callback(MMHandleType player, mm_player_audio_stream_callback callback, void *user_param);
1323
1324 /**
1325  * This function is to mute volume of player
1326  *
1327  * @param       player  [in]    Handle of player
1328  * @param       mute    [in]    Mute(1) or not mute(0)
1329  *
1330  * @return      This function returns zero on success, or negative value with error code
1331  * @see         mm_player_get_mute
1332  * @remark      None
1333  * @par Example
1334  * @code
1335 if (mm_player_set_mute(g_player, TRUE) != MM_ERROR_NONE)
1336 {
1337         debug_warning("failed to set mute\n");
1338 }
1339  * @endcode
1340  */
1341 int mm_player_set_mute(MMHandleType player, int mute);
1342
1343 /**
1344  * This function is to get mute value of player
1345  *
1346  * @param       player  [in]    Handle of player
1347  * @param       mute    [out]   Sound is muted
1348  *
1349  * @return      This function returns zero on success, or negative value with error code
1350  * @see         mm_player_set_mute
1351  * @remark      None
1352  * @par Example
1353  * @code
1354 int mute;
1355
1356 if (mm_player_get_mute(g_player, &mute) != MM_ERROR_NONE)
1357 {
1358         debug_warning("failed to get mute\n");
1359 }
1360
1361 debug_log("mute status:%d\n", mute);
1362  * @endcode
1363  */
1364 int mm_player_get_mute(MMHandleType player, int *mute);
1365
1366 /**
1367  * This function is to adjust subtitle postion. So, subtitle can show at the adjusted position. \n
1368  * If pos is negative, subtitle will be displayed previous time, the other hand forward time. \n
1369  *
1370  * @param       player  [in]    Handle of player
1371  * @param       pos             [in]    postion to be adjusted
1372  *
1373  * @return      This function returns zero on success, or negative value with error
1374  *                      code
1375  * @see         mm_player_adjust_subtitle_position
1376  * @remark      None
1377  * @par Example
1378  * @code
1379 int pos;
1380
1381 pos = 5000;
1382 if (mm_player_adjust_subtitle_position(g_player, MM_PLAYER_POS_FORMAT_TIME, pos) != MM_ERROR_NONE)
1383 {
1384         debug_warning("failed to adjust subtitle postion.\n");
1385 }
1386  * @endcode
1387  */
1388
1389 int mm_player_adjust_subtitle_position(MMHandleType player, MMPlayerPosFormatType format, int pos);
1390
1391 /**
1392  * This function is to set attributes into player. Multiple attributes can be set simultaneously. \n
1393  * If one of attribute fails, this function will stop at the point and let you know the name which is failed. \n
1394  *
1395  * @param       player                          [in]    Handle of player.
1396  * @param       err_attr_name                   [out]  Name of attribute which is failed to set
1397  * @param       first_attribute_name    [in]    Name of the first attribute to set
1398  * @param   ...                                 [in]    Value for the first attribute, followed optionally by more name/value pairs, terminated by NULL.
1399  *                                                                       But, in the case of data or string type, it should be name/value/size.
1400  *
1401  * @return      This function returns zero on success, or negative value with error code.
1402  *
1403  * @see         mm_player_get_attribute
1404  * @remark      This function must be terminated by NULL argument.
1405  *                      And, if this function is failed, err_attr_name param must be free.
1406  * @par Example
1407  * @code
1408 char *g_err_attr_name = NULL;
1409
1410 if (mm_player_set_attribute(g_player,
1411                                                 &g_err_attr_name,
1412                                                 "profile_uri", filename, strlen(filename),
1413                                                 "profile_play_count", count,
1414                                                 NULL) != MM_ERROR_NONE)
1415 {
1416         debug_warning("failed to set %s attribute\n", g_err_attr_name);
1417         free(g_err_attr_name);
1418 }
1419
1420  * @endcode
1421  */
1422 int mm_player_set_attribute(MMHandleType player,  char **err_attr_name, const char *first_attribute_name, ...)G_GNUC_NULL_TERMINATED;
1423
1424 /**
1425  * This function is to get attributes from player. Multiple attributes can be got simultaneously.
1426  *
1427  * @param       player                          [in]    Handle of player.
1428  * @param       err_attr_name                   [out]  Name of attribute which is failed to get
1429  * @param       first_attribute_name    [in]    Name of the first attribute to get
1430  * @param       ...                                     [out] Value for the first attribute, followed optionally by more name/value pairs, terminated by NULL.
1431  *                                                                       But, in the case of data or string type, it should be name/value/size.
1432  *
1433  * @return      This function returns zero on success, or negative value with error
1434  *                      code.
1435  * @see         mm_player_set_attribute
1436  * @remark      This function must be terminated by NULL argument.
1437  *                      And, if this function is failed, err_attr_name param must be free.
1438  * @par Example
1439  * @code
1440 char *g_err_attr_name = NULL;
1441
1442 if (mm_player_get_attribute(g_player, &g_err_attr_name, "content_duration", &duration, NULL) != MM_ERROR_NONE)
1443 {
1444         debug_warning("failed to set %s attribute\n", g_err_attr_name);
1445         free(g_err_attr_name);
1446 }
1447  * @endcode
1448  */
1449 int mm_player_get_attribute(MMHandleType player,  char **err_attr_name, const char *first_attribute_name, ...)G_GNUC_NULL_TERMINATED;
1450
1451 /**
1452  * This function is to get detail information of attribute.
1453  *
1454  * @param       player                           [in]   Handle of player.
1455  * @param   attribute_name               [in]   Name of the attribute to get
1456  * @param   info                                 [out]  Attribute infomation
1457  *
1458  * @return      This function returns zero on success, or negative value with error
1459  *                      code.
1460  *
1461  * @see         mm_player_set_attribute, mm_player_get_attribute
1462  * @remark      None
1463  * @par Example
1464  * @code
1465 if (mm_player_get_attribute_info (g_player, "display_method", &method_info) != MM_ERROR_NONE)
1466 {
1467         debug_warning("failed to get info\n");
1468 }
1469
1470 debug_log("type:%d \n", method_info.type); //int, double..
1471 debug_log("flag:%d \n", method_info.flag); //readable, writable..
1472 debug_log("validity type:%d \n", method_info.validity_type); //range, array..
1473
1474 if (method_info. validity_type == MM_PLAYER_ATTRS_VALID_TYPE_INT_RANGE)
1475 {
1476         debug_log("range min:%d\n", method_info.int_range.min);
1477         debug_log("range max:%d\n", method_info.int_range.max);
1478 }
1479  * @endcode
1480  */
1481 int mm_player_get_attribute_info(MMHandleType player,  const char *attribute_name, MMPlayerAttrsInfo *info);
1482
1483 /**
1484  * This function is to get download position and total size of progressive download
1485  *
1486  * @param       player          [in]    Handle of player.
1487  * @param       current_pos     [in]    Download position currently (bytes)
1488  * @param       total_size      [in]    Total size of file (bytes)
1489  *
1490  * @return      This function returns zero on success, or negative value with error code.
1491  *
1492  * @see
1493  * @remark
1494  * @par Example
1495  * @code
1496 guint64 current_pos = 0LLU;
1497 guint64 total_size = 0LLU;
1498
1499 if (mm_player_get_pd_status(g_player, &current_pos, &total_size, NULL) != MM_ERROR_NONE)
1500 {
1501         debug_log("current download pos = %llu, total size = %llu\n", current_pos, total_size);
1502 }
1503  * @endcode
1504  */
1505 int mm_player_get_pd_status(MMHandleType player, guint64 *current_pos, guint64 *total_size);
1506
1507 /**
1508  * This function sets callback function for receiving messages of PD downloader.
1509  *
1510  * @param       player          [in]    Handle of player.
1511  * @param       callback                [in]    Message callback function.
1512  * @param       user_param      [in]    User parameter which is passed to callback function.
1513  *
1514  * @return      This function returns zero on success, or negative value with error code.
1515  * @see
1516  * @remark      None
1517  * @par Example
1518  * @code
1519 int msg_callback(int message, MMMessageParamType *param, void *user_param)
1520 {
1521         switch (message)
1522         {
1523                 case MM_MESSAGE_PD_DOWNLOADER_START:
1524                         debug_log("Progressive download is started...\n");
1525                         break;
1526                 case MM_MESSAGE_PD_DOWNLOADER_END:
1527                         debug_log("Progressive download is ended...\n");
1528                         break;
1529                 default:
1530                         break;
1531         }
1532         return TRUE;
1533 }
1534
1535 mm_player_set_pd_message_callback(g_player, msg_callback, NULL);
1536  * @endcode
1537  */
1538 int mm_player_set_pd_message_callback(MMHandleType player, MMMessageCallback callback, void *user_param);
1539
1540 /**
1541  * This function is to set the start position of zoom
1542  *
1543  * @param       player          [in]    handle of player
1544  * @param       level           [in]    level of zoom
1545  * @param       x               [in]    start x position
1546  * @param       y               [in]    start y position
1547  *
1548  * @return      This function returns zero on success, or negative value with error
1549  *                      code.
1550  *
1551  * @see
1552  * @remark      None
1553  */
1554 int mm_player_set_display_zoom(MMHandleType player, float level, int x, int y);
1555
1556 /**
1557  * This function is to get the start position of zoom
1558  *
1559  * @param       player           [in]    handle of player
1560  * @param       type            [out]    current level of zoom
1561  * @param       x               [out]    start x position
1562  * @param       y               [out]    start y position
1563  *
1564  * @return      This function returns zero on success, or negative value with error
1565  *                      code.
1566  *
1567  * @see
1568  * @remark      None
1569  */
1570 int mm_player_get_display_zoom(MMHandleType player, float *level, int *x, int *y);
1571
1572 /**
1573  * This function is to set the subtitle path
1574  *
1575  * @param       player  [in]    handle of player
1576  * @param       path    [in]    subtitle path
1577  *
1578  * @return      This function returns zero on success, or negative value with error code.
1579  *
1580  * @see
1581  * @remark      None
1582  */
1583 int mm_player_set_external_subtitle_path(MMHandleType player, const char* path);
1584
1585 /**
1586  * This function is to set audio channel
1587  *
1588  * @param       player          [in]    handle of player
1589  * @param       ch                      [in]    audio channel
1590  * @return      This function returns zero on success, or negative value with error code.
1591  *
1592  * @see
1593  * @remark      None
1594  */
1595 int mm_player_gst_set_audio_channel(MMHandleType player, MMPlayerAudioChannel ch);
1596
1597 /**
1598  * This function is to set uri.
1599  *
1600  * @param       player          [in]    handle of player
1601  * @param       uri             [in]    uri
1602  * @return      This function returns zero on success, or negative value with error code.
1603  *
1604  * @see
1605  * @remark      None
1606  */
1607 int mm_player_set_uri(MMHandleType player, const char *uri);
1608
1609 /**
1610  * This function is to set next uri.
1611  *
1612  * @param       player          [in]    handle of player
1613  * @param       uri             [in]    uri
1614  * @return      This function returns zero on success, or negative value with error code.
1615  *
1616  * @see
1617  * @remark      None
1618  */
1619 int mm_player_set_next_uri(MMHandleType player, const char *uri);
1620
1621 /**
1622  * This function is to get next uri.
1623  *
1624  * @param       player          [in]    handle of player
1625  * @param       uri             [out]   uri
1626  * @return      This function returns zero on success, or negative value with error code.
1627  *
1628  * @see
1629  * @remark      None
1630  */
1631 int mm_player_get_next_uri(MMHandleType player, char **uri);
1632
1633 int mm_player_enable_media_packet_video_stream(MMHandleType player, bool enable);
1634
1635
1636 /**
1637         @}
1638  */
1639
1640 #ifdef __cplusplus
1641         }
1642 #endif
1643
1644 #endif  /* __MM_PLAYER_H__ */