src/include/mm_player.h

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