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