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