include/SLP_MultimediaFW_PG.h

   1 /*
   2  * libmm-common
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Jonghyuk Choi <jhchoi.choi@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22
  23 /**
  24  *
  25  * @ingroup   SLP_PG
  26  * @defgroup   MultiMediaPG  MultiMedia Camcorder,Player,Sound and Radio
  27 @{
  28 <h1 class="pg">Introduction</h1>
  29 <h2 class="pg">Purpose</h2>
  30
  31 The purpose of this document is to give the application developer detailed information on creating and configuring Multimedia applications using the Multimedia Framework API's.
  32
  33
  34 <h2 class="pg">Scope</h2>
  35
  36 The scope of this document is limited to Samsung platform Multimedia Framework API usage.
  37
  38 <h2 class="pg">Abbreviations</h2>
  39
  40         <table>
  41                 <tr>
  42                         <td>
  43                         API
  44                         </td>
  45                         <td>
  46                         Application Programming Interface
  47                         </td>
  48                 </tr>
  49                 <tr>
  50                         <td>
  51                           JPEG
  52                         </td>
  53                         <td>
  54                           Joint Photographic Experts Group
  55                         </td>
  56                 </tr>
  57                 <tr>
  58                         <td>
  59                           AAC
  60                         </td>
  61                         <td>
  62                         Advanced Audio Coding
  63                         </td>
  64                 </tr>
  65                 <tr>
  66                         <td>
  67                           RTP
  68                         </td>
  69                         <td>
  70                         Realtime Transport Protocol
  71                         </td>
  72                 </tr>
  73                 <tr>
  74                         <td>
  75                           MMFW
  76                         </td>
  77                         <td>
  78                           Multimedia Framework
  79                         </td>
  80                 </tr>
  81                 <tr>
  82                         <td>
  83                           PCM
  84                         </td>
  85                         <td>
  86                           Pulse Code Modulation
  87                         </td>
  88                 </tr>
  89         </table>
  90 @}
  91 @defgroup MM_Feature 2.Feature
  92 @ingroup MultiMediaPG
  93 @{
  94 <h1 class="pg">Multimedia Framework Feature</h1>
  95
  96 The Multimedia Framework is designed to provide easy to use services for developing multimedia applications based on an embedded Linux platform.
  97
  98
  99 <h2 class="pg">Features</h2>
 100
 101 - Camcorder
 102         - Initialize Camcorder for Image capture
 103         - Initialize Camcorder for Video capture
 104         - Initialize Camcorder for Audio capture
 105         - Uninitialize camcorder
 106         - Capturing Picture
 107         - Record and Save a Audio/Video file or a Audio only file
 108         - Record and Cancel saving of a recording file
 109         - Record, Pause and resume recording
 110         - Get state of camcorder
 111         - Start and Stop focus
 112         - User defined filename for recording file
 113         - Set VideoStream Callback
 114         - Set VideoCapture Callback
 115         - Set Message Callback
 116
 117 - Player
 118         - Play video/audio from local file, network stream, buffer and memory data
 119         - Pause and resume playback
 120         - Seeking the position during playing
 121         - Setting section repeat
 122         - Change volume
 123         - Display subtitle
 124
 125 - Multimedia session
 126         - Determine application's multimedia functional policy.
 127
 128 - Fileinfo
 129         - Extracting Media Property Information
 130         - Extracting Media Meta (Tag) data
 131         - Extracting Stream information
 132
 133 - Sound
 134         - Play audio file with simple API (supports uncompressed wav/mp3 file only).
 135         - Playback or capture PCM with given memory buffer.
 136
 137 - OpenAL
 138         - Cross platform 3D audio API appropriate for gaming applications.
 139         - OpenAL in SLP only supports playback function.
 140
 141 - Radio
 142         - Listening to FM Radio
 143         - Scan the effective frequencies
 144         - Seek the frequency
 145         - Get/Set frequency
 146         - Get/Set relative volume
 147
 148 - Utility
 149         - Image processing (Rotation, Resizing, and Color converting)
 150         - Jpeg encoding and decoding
 151
 152 @}
 153 @defgroup MM_Architecture 1.Architecture
 154 @ingroup MultiMediaPG
 155 @{
 156
 157 <h2 class="pg">Architecture diagram</h2>
 158
 159
 160 <b>Modules</b>
 161
 162 - Camcorder
 163
 164 The Camcorder Library is a module of the Multimedia framework of SLP. It is responsible for capturing various types of media data such as still image, audio frame, and video frame. According to its operating modes, the camcorder is able to 1) capture Still image, 2) record audio/video frame, and 3) record audio frame only. It provides many convenient functions to control itself. Users can select types of encoders, detailed specifications of video/audio data, and various effects that enhance the quality of the resulting file.
 165 (The current release of SDK might not support all of the camcorder library functions because the camera driver in SDK does not support many APIs should be supported.)
 166
 167
 168 - Player
 169
 170 The Player Library provides various functions for a multimedia application to implement playback of media contents. An application can play different formats of audio and audio/video files. The Player Library provides an interface for playing different formats by hiding the creation/construction of various streaming elements from the application, which makes application coding simpler and faster.
 171
 172
 173 - Multimedia Session
 174
 175 Session means timeline of multimedia resources are used.
 176 Application developer can determine applications' session type as "shared", "exclusive" or "replace".
 177 "Shared" type means the multimedia session is shared with other applications, if possible. The multimedia resources can be used by other applications.
 178 "Exclusive" type means using the multimedia session exclusively. Other applications are not allowed to use multimedia resources during this time.
 179 "Replace" type means this will make stop previous session but allows sharing session with following application.
 180
 181
 182 - Fileinfo
 183
 184 The Fileinfo library provides APIs to extract media property information and meta data from media content. These values can be used to display detailed information of the media content without playing it.
 185
 186
 187
 188 - Sound
 189
 190 The Sound library provides fuctions to play audio files (uncompressed wav and mp3) with a very simple API and to control sound volume of predefined type.
 191 Also provides functions to playback raw PCM from a memory buffer and capture raw PCM to a memory buffer.
 192
 193
 194
 195
 196 - OpenAL
 197
 198 OpenAL is a cross-platform 3D audio API appropriate for use with gaming applications and many other types of audio applications. OpenAL in SLP only supports playback function.
 199 For further information, see official website : http://connect.creativelabs.com/openal/default.aspx
 200
 201
 202
 203 - Radio
 204
 205 The Radio Library provides various functions for implementing radio application. It supports the radio operations for HW radio chipset. This library can be only used when HW radio chipset is exist. Radio APIs provides the functionality for playing/stopping radio, changing the frequency, scanning and changing radio sound volumes.
 206
 207
 208 - Utility
 209
 210 The Utility library provides simple functions for a multimedia application to process YUV image data and to handle jpeg data. The Utility library for processing image data supports the conversion of color format from YUV to RGB, rotation of images, and resizing the width and height of the picture. The library also saves and loads the image in the Jpeg format. This library includes simple utility features which are related to multimedia.
 211
 212
 213 @image html SLP_MultimediaFW_PG_image001.png
 214
 215 @}
 216 @defgroup MM_Camcorder Camcorder
 217 @ingroup MultiMediaPG
 218 @{
 219
 220         @brief <sub class="ref">Also see</sub> Use Cases of @ref Camcorder_UC
 221 <h2 class="pg">Camcorder</h2>
 222
 223 This part describes the APIs of the Multimedia Camcorder Library. Camcorder Library is used for recording video from video/audio input devices, capturing still images from the video input device, and audio recording from the audio input device.
 224
 225 Camcorder states can be changed by calling the functions shown in the following figure, "State of Camcorder".
 226 Between each state there is intermediate state, and whilst in this state, any function call which attempts to change the camcorder state will fail.
 227 Recording state and paused state exist when the camcorder is in video-capture mode. When in audio-capture mode, CAPTURING state will be replaced with RECORDING state.
 228
 229 All of the functions which change the state of the camcorder are asynchronous. The function returns immediately and a successful confirmation of state change will be notified through the message callback function. If the state is changed successfully, a state message callback function will be received with the new state, if not an error message will be received.
 230
 231 <b>Functions</b>
 232 @image html SLP_MultimediaFW_PG_image002.png
 233
 234 <center>Figure. State of Camcorder</center>
 235
 236
 237
 238 The following table specifies the state changes of the camcorder module.
 239
 240         <table>
 241                 <tr>
 242                         <td>
 243                         <center><b>FUNCTION</b></center>
 244                         </td>
 245                         <td>
 246                         <center><b>PRE-STATE</b></center>
 247                         </td>
 248                         <td>
 249                         <center><b>POST-STATE</b></center>
 250                         </td>
 251                 </tr>
 252                 <tr>
 253                         <td>
 254                         mm_camcorder_create()
 255                         </td>
 256                         <td>
 257                         NONE
 258                         </td>
 259                         <td>
 260                         NULL
 261                         </td>
 262                 </tr>
 263                 <tr>
 264                         <td>
 265                         mm_camcorder_destroy()
 266                         </td>
 267                         <td>
 268                         NULL
 269                         </td>
 270                         <td>
 271                         NONE
 272                         </td>
 273                 </tr>
 274                 <tr>
 275                         <td>
 276                         mm_camcorder_realize()
 277                         </td>
 278                         <td>
 279                         NULL
 280                         </td>
 281                         <td>
 282                         READY
 283                         </td>
 284                 </tr>
 285                 <tr>
 286                         <td>
 287                         mm_camcorder_unrealize()
 288                         </td>
 289                         <td>
 290                         READY
 291                         </td>
 292                         <td>
 293                         NULL
 294                         </td>
 295                 </tr>
 296                 <tr>
 297                         <td>
 298                         mm_camcorder_start()
 299                         </td>
 300                         <td>
 301                         READY
 302                         </td>
 303                         <td>
 304                         PREPARE
 305                         </td>
 306                 </tr>
 307                 <tr>
 308                         <td>
 309                         mm_camcorder_stop()
 310                         </td>
 311                         <td>
 312                         PREPARE
 313                         </td>
 314                         <td>
 315                         READY
 316                         </td>
 317                 </tr>
 318                 <tr>
 319                         <td>
 320                         mm_camcorder_capture_start()
 321                         </td>
 322                         <td>
 323                         PREPARE
 324                         </td>
 325                         <td>
 326                         CAPTURING
 327                         </td>
 328                 </tr>
 329                 <tr>
 330                         <td>
 331                         mm_camcorder_capture_stop()
 332                         </td>
 333                         <td>
 334                         CAPTURING
 335                         </td>
 336                         <td>
 337                         PREPARE
 338                         </td>
 339                 </tr>
 340                 <tr>
 341                         <td>
 342                         mm_camcorder_record()
 343                         </td>
 344                         <td>
 345                         PREPARED/PAUSED
 346                         </td>
 347                         <td>
 348                         RECORDING
 349                         </td>
 350                 </tr>
 351                 <tr>
 352                         <td>
 353                         mm_camcorder_pause()
 354                         </td>
 355                         <td>
 356                         RECORDING
 357                         </td>
 358                         <td>
 359                         PAUSED
 360                         </td>
 361                 </tr>
 362                 <tr>
 363                         <td>
 364                         mm_camcorder_commit()
 365                         </td>
 366                         <td>
 367                         RECORDING/PAUSED
 368                         </td>
 369                         <td>
 370                         PREPARE
 371                         </td>
 372                 </tr>
 373                 <tr>
 374                         <td>
 375                         mm_camcorder_cancel()
 376                         </td>
 377                         <td>
 378                         RECORDING/PAUSED
 379                         </td>
 380                         <td>
 381                         PREPARE
 382                         </td>
 383                 </tr>
 384         </table>
 385
 386
 387 The followings are functions to manage camcorder module.
 388
 389 - mm_camcorder_set_message_callback()
 390         - Set callback for receiving messages from camcorder. Through this callback function, camcorder sends various message including status changes, asynchronous errors, capturing, and limitations.  One thing you have to know is that message callback is working on the main loop of application.  So until releasing the main loop, message callback will not be called.
 391
 392 - mm_camcorder_set_video_stream_callback()
 393         - Set callback for user defined video stream callback function.  Users can retrieve video frame using registered callback.
 394
 395 - mm_camcorder_set_video_capture_callback()
 396         - Set callback for user defined video capture callback function.  (Image mode only)
 397
 398 - mm_camcorder_get_state()
 399         - Get the current state of camcorder.
 400
 401 - mm_camcorder_get_attributes()
 402         - Get attributes of camcorder with given attribute names. This function can get multiple attributes simultaneously. If one of attribute fails, this function will stop at that point. 'err_attr_name' let you know the name of the attribute.
 403
 404 - mm_camcorder_set_attributes()
 405         - Set attributes of camcorder with given attribute names. This function can set multiple attributes simultaneously. If one of attribute fails, this function will stop at that point.  'err_attr_name' let you know the name of the attribute.
 406
 407 - mm_camcorder_get_attribute_info()
 408         - Get detailed information of the attribute.
 409
 410 - mm_camcorder_init_focusing()
 411         - Initialize auto focusing. If auto focusing is in progressing, stop auto focusing and adjust the camera lens to initial position.
 412
 413 - mm_camcorder_start_focusing()
 414         - Start focusing.  This function return immediately. However, focusing operation will continue until it gets results. After finishing operation, you can get 'MM_MESSAGE_CAMCORDER_FOCUS_CHANGED' message.
 415
 416 - mm_camcorder_stop_focusing()
 417         - Stop focusing. This function halts focusing operation.
 418
 419
 420 <br><br>
 421 The followings are full proto types of camcorder functions.
 422
 423 - int mm_camcorder_create( MMHandleType* camcorder, MMCamPreset* info );
 424
 425 - int mm_camcorder_destroy(MMHandleType camcorder);
 426
 427 - int mm_camcorder_realize(MMHandleType camcorder);
 428
 429 - int mm_camcorder_unrealize(MMHandleType camcorder);
 430
 431 - int mm_camcorder_start(MMHandleType camcorder);
 432
 433 - int mm_camcorder_stop(MMHandleType camcorder);
 434
 435 - int mm_camcorder_capture_start(MMHandleType camcorder);
 436
 437 - int mm_camcorder_capture_stop(MMHandleType camcorder);
 438
 439 - int mm_camcorder_record(MMHandleType camcorder);
 440
 441 - int mm_camcorder_pause(MMHandleType camcorder);
 442
 443 - int mm_camcorder_commit(MMHandleType camcorder);
 444
 445 - int mm_camcorder_cancel(MMHandleType camcorder);
 446
 447 - int mm_camcorder_set_message_callback(MMHandleType camcorder, MMMessageCallback callback, void *user_data);
 448
 449 - int mm_camcorder_set_video_stream_callback( MMHandleType camcorder, mm_camcorder_video_stream_callback callback, void* user_data );
 450
 451 - int mm_camcorder_set_video_capture_callback( MMHandleType camcorder, mm_camcorder_video_capture_callback callback, void* user_data );
 452
 453 - int mm_camcorder_get_state(MMHandleType camcorder, MMCamcorderStateType* state);
 454
 455 - int #mm_camcorder_get_attributes(MMHandleType camcorder, char **err_attr_name, const char *attribute_name, ...) G_GNUC_NULL_TERMINATED;
 456
 457 - int #mm_camcorder_set_attributes(MMHandleType camcorder, char **err_attr_name, const char *attribute_name, ...) G_GNUC_NULL_TERMINATED;
 458
 459 - int mm_camcorder_get_attribute_info(MMHandleType camcorder, const char *attribute_name, MMCamAttrsInfo *info);
 460
 461 - int mm_camcorder_init_focusing( MMHandleType camcorder );
 462
 463 - int mm_camcorder_start_focusing( MMHandleType camcorder );
 464
 465 - int mm_camcorder_stop_focusing( MMHandleType camcorder );
 466
 467
 468 <b>Attributes</b>
 469
 470 - Attribute system
 471         - Attribute system is an interface to operate camcorder. Depending on each attribute, camcorder behaves differently. Attribute system provides get/set functions. Setting proper attributes, a user can control camcorder as he wants (mm_camcorder_set_attributes()) Also, a user can retrieve the current status of the camcorder, calling getter function(mm_camcorder_get_attributes()). Beware, arguments of mm_camcorder_set_attributes() and mm_camcorder_get_attributes() should be finished with 'NULL'. This is a rule for the variable argument.
 472         - Besides its value, each Attribute also has 'type' and 'validity type'. 'type' describes variable type that the attribute can have. If you input a value that has wrong type, camcorder will not work properly or will crash. 'validity' describes array or range of values that can be set to the attribute. 'validity type' defines type of the 'validity'.
 473         - A user can retrieve these values using mm_camcorder_get_attribute_info().
 474
 475
 476 Followings are the attributes which should be set before initialization (mm_camcorder_realize):
 477         - For more detail information, please refer the doxygen document of Camcorder FW.
 478
 479
 480
 481 <table>
 482         <tr>
 483                 <td>
 484                 <center><b>Attribute</b></center>
 485                 </td>
 486                 <td>
 487                 <center><b>Description</b></center>
 488                 </td>
 489         </tr>
 490         <tr>
 491                 <td>
 492                 #MMCAM_MODE
 493                 </td>
 494                 <td>
 495                 Mode of camcorder ( still/video/audio )
 496                 </td>
 497         </tr>
 498         <tr>
 499                 <td>
 500                 #MMCAM_AUDIO_DEVICE
 501                 </td>
 502                 <td>
 503                 Audio device ID for capturing audio stream
 504                 </td>
 505         </tr>
 506         <tr>
 507                 <td>
 508                 #MMCAM_CAMERA_DEVICE
 509                 </td>
 510                 <td>
 511                 Video device ID for capturing video stream
 512                 </td>
 513         </tr>
 514         <tr>
 515                 <td>
 516                 #MMCAM_AUDIO_ENCODER
 517                 </td>
 518                 <td>
 519                 Audio codec for encoding audio stream
 520                 </td>
 521         </tr>
 522         <tr>
 523                 <td>
 524                 #MMCAM_VIDEO_ENCODER
 525                 </td>
 526                 <td>
 527                 Video codec for encoding video stream
 528                 </td>
 529         </tr>
 530         <tr>
 531                 <td>
 532                 #MMCAM_IMAGE_ENCODER
 533                 </td>
 534                 <td>
 535                 Image codec for capturing still-image
 536                 </td>
 537         </tr>
 538         <tr>
 539                 <td>
 540                 #MMCAM_FILE_FORMAT
 541                 </td>
 542                 <td>
 543                 File format for recording media stream
 544                 </td>
 545         </tr>
 546         <tr>
 547                 <td>
 548                 #MMCAM_AUDIO_SAMPLERATE
 549                 </td>
 550                 <td>
 551                 Sampling rate of audio stream ( This is an integer field )
 552                 </td>
 553         </tr>
 554         <tr>
 555                 <td>
 556                 #MMCAM_AUDIO_FORMAT
 557                 </td>
 558                 <td>
 559                 Audio format of each sample
 560                 </td>
 561         </tr>
 562         <tr>
 563                 <td>
 564                 #MMCAM_AUDIO_CHANNEL
 565                 </td>
 566                 <td>
 567                 Channels of each sample ( This is an integer field )
 568                 </td>
 569         </tr>
 570         <tr>
 571                 <td>
 572                 #MMCAM_AUDIO_INPUT_ROUTE
 573                 </td>
 574                 <td>
 575                 Set audio input route
 576                 </td>
 577         </tr>
 578         <tr>
 579                 <td>
 580                 #MMCAM_CAMERA_FORMAT
 581                 </td>
 582                 <td>
 583                 Format of video stream. This is an integer field
 584                 </td>
 585         </tr>
 586         <tr>
 587                 <td>
 588                 #MMCAM_CAMERA_FPS
 589                 </td>
 590                 <td>
 591                 Frames per second ( This is an integer field )
 592                 </td>
 593         </tr>
 594         <tr>
 595                 <td>
 596                 #MMCAM_CAMERA_WIDTH
 597                 </td>
 598                 <td>
 599                 Width of input video stream
 600                 </td>
 601         </tr>
 602         <tr>
 603                 <td>
 604                 #MMCAM_CAMERA_HEIGHT
 605                 </td>
 606                 <td>
 607                 Height of input video stream
 608                 </td>
 609         </tr>
 610         <tr>
 611                 <td>
 612                 #MMCAM_CAMERA_FPS_AUTO
 613                 </td>
 614                 <td>
 615                 FPS Auto. When you set true to this attribute, FPS will vary depending on the amount of the light.
 616                 </td>
 617         </tr>
 618         <tr>
 619                 <td>
 620                 #MMCAM_DISPLAY_HANDLE
 621                 </td>
 622                 <td>
 623                 Pointer of display buffer or ID of xwindow
 624                 </td>
 625         </tr>
 626         <tr>
 627                 <td>
 628                 #MMCAM_DISPLAY_DEVICE
 629                 </td>
 630                 <td>
 631                 Device ID of display
 632                 </td>
 633         </tr>
 634         <tr>
 635                 <td>
 636                 #MMCAM_DISPLAY_SOURCE_X
 637                 </td>
 638                 <td>
 639                 X position of source rectangle. When you want to crop the source, you can set the area with this value.
 640                 </td>
 641         </tr>
 642         <tr>
 643                 <td>
 644                 #MMCAM_DISPLAY_SOURCE_Y
 645                 </td>
 646                 <td>
 647                 Y position of source rectangle. When you want to crop the source, you can set the area with this value.
 648                 </td>
 649         </tr>
 650         <tr>
 651                 <td>
 652                 #MMCAM_DISPLAY_SOURCE_WIDTH
 653                 </td>
 654                 <td>
 655                 Width of source rectangle. When you want to crop the source, you can set the area with this value.
 656                 </td>
 657         </tr>
 658         <tr>
 659                 <td>
 660                 #MMCAM_DISPLAY_SOURCE_HEIGHT
 661                 </td>
 662                 <td>
 663                 Height of source rectangle. When you want to crop the source, you can set the area with this value.
 664                 </td>
 665         </tr>
 666         <tr>
 667                 <td>
 668                 #MMCAM_DISPLAY_ROTATION
 669                 </td>
 670                 <td>
 671                 Rotation of display
 672                 </td>
 673         </tr>
 674         <tr>
 675                 <td>
 676                 #MMCAM_DISPLAY_VISIBLE
 677                 </td>
 678                 <td>
 679                 Visible of display
 680                 </td>
 681         </tr>
 682         <tr>
 683                 <td>
 684                 #MMCAM_DISPLAY_SCALE
 685                 </td>
 686                 <td>
 687                 A scale of displayed image
 688                 </td>
 689         </tr>
 690         <tr>
 691                 <td>
 692                 #MMCAM_DISPLAY_GEOMETRY_METHOD
 693                 </td>
 694                 <td>
 695                 A method that describes a form of geometry for display
 696                 </td>
 697         </tr>
 698 </table>
 699 <br>
 700 Followings are the attributes which should be set before recording (mm_camcorder_record()):
 701 <br>
 702
 703 <table>
 704         <tr>
 705                 <td>
 706                 <center><b>Attribute</b></center>
 707                 </td>
 708                 <td>
 709                 <center><b>Description</b></center>
 710                 </td>
 711         </tr>
 712         <tr>
 713                 <td>
 714                 #MMCAM_AUDIO_ENCODER_BITRATE
 715                 </td>
 716                 <td>
 717                 Bitrate of Audio Encoder
 718                 </td>
 719         </tr>
 720         <tr>
 721                 <td>
 722                 #MMCAM_VIDEO_ENCODER_BITRATE
 723                 </td>
 724                 <td>
 725                 Bitrate of Video Encoder
 726                 </td>
 727         </tr>
 728         <tr>
 729                 <td>
 730                 #MMCAM_TARGET_FILENAME
 731                 </td>
 732                 <td>
 733                 Target filename. Only used in Audio/Video recording. This is not used for capturing.
 734                 </td>
 735         </tr>
 736         <tr>
 737                 <td>
 738                 #MMCAM_TARGET_MAX_SIZE
 739                 </td>
 740                 <td>
 741                 Maximum size of recording file(Kbyte). If the size of file reaches this value.
 742                 </td>
 743         </tr>
 744         <tr>
 745                 <td>
 746                 #MMCAM_TARGET_TIME_LIMIT
 747                 </td>
 748                 <td>
 749                 Time limit of recording file. If the elapsed time of recording reaches this value.
 750                 </td>
 751         </tr>
 752 </table>
 753 <br>
 754 Followings are the attributes which should be set before capturing (mm_camcorder_capture_start()):
 755 <br>
 756
 757 <table>
 758         <tr>
 759                 <td>
 760                 <center><b>Attribute</b></center>
 761                 </td>
 762                 <td>
 763                 <center><b>Description</b></center>
 764                 </td>
 765         </tr>
 766         <tr>
 767                 <td>
 768                 #MMCAM_IMAGE_ENCODER_QUALITY
 769                 </td>
 770                 <td>
 771                 Encoding quality of Image codec
 772                 </td>
 773         </tr>
 774         <tr>
 775                 <td>
 776                 #MMCAM_CAPTURE_FORMAT
 777                 </td>
 778                 <td>
 779                 Pixel format that you want to capture
 780                 </td>
 781         </tr>
 782         <tr>
 783                 <td>
 784                 #MMCAM_CAPTURE_WIDTH
 785                 </td>
 786                 <td>
 787                 Width of the image that you want to capture
 788                 </td>
 789         </tr>
 790         <tr>
 791                 <td>
 792                 #MMCAM_CAPTURE_HEIGHT
 793                 </td>
 794                 <td>
 795                 Height of the image that you want to capture
 796                 </td>
 797         </tr>
 798         <tr>
 799                 <td>
 800                 #MMCAM_CAPTURE_COUNT
 801                 </td>
 802                 <td>
 803                 Total count of capturing
 804                 </td>
 805         </tr>
 806         <tr>
 807                 <td>
 808                 #MMCAM_CAPTURE_INTERVAL
 809                 </td>
 810                 <td>
 811                 Interval between each capturing on Multishot ( MMCAM_CAPTURE_COUNT > 1 )
 812                 </td>
 813         </tr>
 814 </table>
 815 <br>
 816 Followings are the attributes which can be set anytime:
 817 <br>
 818
 819 <table>
 820         <tr>
 821                 <td>
 822                 <center><b>Attribute</b></center>
 823                 </td>
 824                 <td>
 825                 <center><b>Description</b></center>
 826                 </td>
 827         </tr>
 828         <tr>
 829                 <td>
 830                 #MMCAM_AUDIO_VOLUME
 831                 </td>
 832                 <td>
 833                 Input volume of audio source ( double value )
 834                 </td>
 835         </tr>
 836         <tr>
 837                 <td>
 838                 #MMCAM_CAMERA_DIGITAL_ZOOM
 839                 </td>
 840                 <td>
 841                 Digital zoom level
 842                 </td>
 843         </tr>
 844         <tr>
 845                 <td>
 846                 #MMCAM_CAMERA_OPTICAL_ZOOM
 847                 </td>
 848                 <td>
 849                 Optical zoom level
 850                 </td>
 851         </tr>
 852         <tr>
 853                 <td>
 854                 #MMCAM_CAMERA_FOCUS_MODE
 855                 </td>
 856                 <td>
 857                 Focus mode
 858                 </td>
 859         </tr>
 860         <tr>
 861                 <td>
 862                 #MMCAM_CAMERA_AF_SCAN_RANGE
 863                 </td>
 864                 <td>
 865                 AF Scan range
 866                 </td>
 867         </tr>
 868         <tr>
 869                 <td>
 870                 #MMCAM_CAMERA_AF_TOUCH_X
 871                 </td>
 872                 <td>
 873                 X coordinate of touching position
 874                 </td>
 875         </tr>
 876         <tr>
 877                 <td>
 878                 #MMCAM_CAMERA_AF_TOUCH_Y
 879                 </td>
 880                 <td>
 881                 Y coordinate of touching position
 882                 </td>
 883         </tr>
 884         <tr>
 885                 <td>
 886                 #MMCAM_CAMERA_AF_TOUCH_WIDTH
 887                 </td>
 888                 <td>
 889                 Width of touching area
 890                 </td>
 891         </tr>
 892         <tr>
 893                 <td>
 894                 #MMCAM_CAMERA_AF_TOUCH_HEIGHT
 895                 </td>
 896                 <td>
 897                 Height of touching area
 898                 </td>
 899         </tr>
 900         <tr>
 901                 <td>
 902                 #MMCAM_CAMERA_EXPOSURE_MODE
 903                 </td>
 904                 <td>
 905                 Exposure mode
 906                 </td>
 907         </tr>
 908         <tr>
 909                 <td>
 910                 #MMCAM_CAMERA_EXPOSURE_VALUE
 911                 </td>
 912                 <td>
 913                 Exposure value
 914                 </td>
 915         </tr>
 916         <tr>
 917                 <td>
 918                 #MMCAM_CAMERA_F_NUMBER
 919                 </td>
 920                 <td>
 921                 f number of camera
 922                 </td>
 923         </tr>
 924         <tr>
 925                 <td>
 926                 #MMCAM_CAMERA_SHUTTER_SPEED
 927                 </td>
 928                 <td>
 929                 Shutter speed
 930                 </td>
 931         </tr>
 932         <tr>
 933                 <td>
 934                 #MMCAM_CAMERA_ISO
 935                 </td>
 936                 <td>
 937                 ISO of capturing image
 938                 </td>
 939         </tr>
 940         <tr>
 941                 <td>
 942                 #MMCAM_CAMERA_WDR
 943                 </td>
 944                 <td>
 945                 Wide dynamic range
 946                 </td>
 947         </tr>
 948         <tr>
 949                 <td>
 950                 #MMCAM_CAMERA_ANTI_HANDSHAKE
 951                 </td>
 952                 <td>
 953                 Anti Handshake
 954                 </td>
 955         </tr>
 956         <tr>
 957                 <td>
 958                 #MMCAM_CAMERA_FOCAL_LENGTH
 959                 </td>
 960                 <td>
 961                 Focal length of camera lens
 962                 </td>
 963         </tr>
 964         <tr>
 965                 <td>
 966                 #MMCAM_FILTER_BRIGHTNESS
 967                 </td>
 968                 <td>
 969                 Brightness level
 970                 </td>
 971         </tr>
 972         <tr>
 973                 <td>
 974                 #MMCAM_FILTER_CONTRAST
 975                 </td>
 976                 <td>
 977                 Contrast level
 978                 </td>
 979         </tr>
 980         <tr>
 981                 <td>
 982                 #MMCAM_FILTER_WB
 983                 </td>
 984                 <td>
 985                 White balance
 986                 </td>
 987         </tr>
 988         <tr>
 989                 <td>
 990                 #MMCAM_FILTER_COLOR_TONE
 991                 </td>
 992                 <td>
 993                 Color tone (Color effect)
 994                 </td>
 995         </tr>
 996         <tr>
 997                 <td>
 998                 #MMCAM_FILTER_SCENE_MODE
 999                 </td>
1000                 <td>
1001                 Scene mode (Program mode)
1002                 </td>
1003         </tr>
1004         <tr>
1005                 <td>
1006                 #MMCAM_FILTER_SATURATION
1007                 </td>
1008                 <td>
1009                 Saturation level
1010                 </td>
1011         </tr>
1012         <tr>
1013                 <td>
1014                 #MMCAM_FILTER_HUE
1015                 </td>
1016                 <td>
1017                 Hue level
1018                 </td>
1019         </tr>
1020         <tr>
1021                 <td>
1022                 #MMCAM_FILTER_SHARPNESS
1023                 </td>
1024                 <td>
1025                 Sharpness level
1026                 </td>
1027         </tr>
1028         <tr>
1029                 <td>
1030                 #MMCAM_CAPTURE_BREAK_CONTINUOUS_SHOT
1031                 </td>
1032                 <td>
1033                 Set this as true when you want to stop multishot immediately
1034                 </td>
1035         </tr>
1036         <tr>
1037                 <td>
1038                 #MMCAM_DISPLAY_RECT_X
1039                 </td>
1040                 <td>
1041                 X position of display rectangle ( This is only available when MMCAM_DISPLAY_GEOMETRY_METHOD is MM_CAMCORDER_CUSTOM_ROI )
1042                 </td>
1043         </tr>
1044         <tr>
1045                 <td>
1046                 #MMCAM_DISPLAY_RECT_Y
1047                 </td>
1048                 <td>
1049                 Y position of display rectangle ( This is only available when MMCAM_DISPLAY_GEOMETRY_METHOD is MM_CAMCORDER_CUSTOM_ROI )
1050                 </td>
1051         </tr>
1052         <tr>
1053                 <td>
1054                 #MMCAM_DISPLAY_RECT_WIDTH
1055                 </td>
1056                 <td>
1057                 Width of display rectangle ( This is only available when MMCAM_DISPLAY_GEOMETRY_METHOD is MM_CAMCORDER_CUSTOM_ROI )
1058                 </td>
1059         </tr>
1060         <tr>
1061                 <td>
1062                 #MMCAM_DISPLAY_RECT_HEIGHT
1063                 </td>
1064                 <td>
1065                 Height of display rectangle ( This is only available when MMCAM_DISPLAY_GEOMETRY_METHOD is MM_CAMCORDER_CUSTOM_ROI )
1066                 </td>
1067         </tr>
1068         <tr>
1069                 <td>
1070                 #MMCAM_TAG_ENABLE
1071                 </td>
1072                 <td>
1073                 Enable to write tags ( If this value is FALSE, none of tag information will be written to captured file )
1074                 </td>
1075         </tr>
1076         <tr>
1077                 <td>
1078                 #MMCAM_TAG_IMAGE_DESCRIPTION
1079                 </td>
1080                 <td>
1081                 Image description
1082                 </td>
1083         </tr>
1084         <tr>
1085                 <td>
1086                 #MMCAM_TAG_ORIENTATION
1087                 </td>
1088                 <td>
1089                 Orientation of captured image
1090                 </td>
1091         </tr>
1092         <tr>
1093                 <td>
1094                 #MMCAM_TAG_SOFTWARE
1095                 </td>
1096                 <td>
1097                 software name and version
1098                 </td>
1099         </tr>
1100         <tr>
1101                 <td>
1102                 #MMCAM_TAG_LATITUDE
1103                 </td>
1104                 <td>
1105                 Latitude of captured postion ( GPS information )
1106                 </td>
1107         </tr>
1108         <tr>
1109                 <td>
1110                 #MMCAM_TAG_LONGITUDE
1111                 </td>
1112                 <td>
1113                 Longitude of captured postion ( GPS information )
1114                 </td>
1115         </tr>
1116         <tr>
1117                 <td>
1118                 #MMCAM_TAG_ALTITUDE
1119                 </td>
1120                 <td>
1121                 Altitude of captured postion ( GPS information )
1122                 </td>
1123         </tr>
1124         <tr>
1125                 <td>
1126                 #MMCAM_STROBE_CONTROL
1127                 </td>
1128                 <td>
1129                 Strobe control
1130                 </td>
1131         </tr>
1132         <tr>
1133                 <td>
1134                 #MMCAM_STROBE_MODE
1135                 </td>
1136                 <td>
1137                 Operation Mode of strobe
1138                 </td>
1139         </tr>
1140         <tr>
1141                 <td>
1142                 #MMCAM_DETECT_MODE
1143                 </td>
1144                 <td>
1145                 Detection mode
1146                 </td>
1147         </tr>
1148         <tr>
1149                 <td>
1150                 #MMCAM_DETECT_NUMBER
1151                 </td>
1152                 <td>
1153                 Total number of detected object
1154                 </td>
1155         </tr>
1156         <tr>
1157                 <td>
1158                 #MMCAM_DETECT_FOCUS_SELECT
1159                 </td>
1160                 <td>
1161                 Select one of detected objects
1162                 </td>
1163         </tr>
1164 </table>
1165 @}
1166 @defgroup Camcorder_uc1 Initialize Camcorder for Image capture
1167 @ingroup Camcorder_UC
1168 @{
1169
1170 <h2 class="pg">Initialize Camcorder for Image capture   </h2>
1171
1172 - Purpose
1173         - Start preview for capturing image
1174
1175
1176
1177 The camcorder module is initialized for Image capture by using the following steps:
1178
1179 -# Create the camcorder handle using mm_camcorder_create().
1180 -# Set message callback. Message callback is a handler for camcorder message. If camcorder is trying to deliever a certain signal that happens on runtime, it uses this method. For more detail information, refer "Set Message Callback"
1181 -# Set video capture callback. Video capture callback is a handler for the captured image. This is the only method to deliever the image. (Do not use 'MMCAM_TARGET_FILENAME' for image capturing. It can't handle multishot.) For more detail information, refer "Set VideoCapture Callback"
1182 -# Set various attributes using mm_camcorder_set_attributes(). You can set as many attributes as you want. If you don't set any attributes, it will operate with the default values. But as a minimum, you have to set 'MMCAM_DISPLAY_HANDLE'. This is the attribute to deliever display pointer or index, such as xid of x window. So if you don't set this, there is no way to display the image.
1183 -# Allocate resources (memory, device node, etc) for camcorder handle using mm_camcorder_realize().
1184 -# Start receiving input video stream (previewing) calling mm_camcorder_start().
1185
1186
1187
1188 The following is a sample code:
1189
1190 @code
1191 MMHandleType hcam = 0;
1192
1193 struct appdata
1194 {
1195         ...
1196         int xid;
1197         ...
1198 };
1199 struct appdata ad;
1200
1201
1202 static gboolean initialize_image_capture()
1203
1204 {
1205
1206       int err;
1207
1208       MMCamPreset cam_info;
1209
1210       char *err_attr_name = NULL;
1211
1212       void * hdisplay = NULL;
1213
1214       int hsize = 0;
1215
1216
1217
1218       cam_info.videodev_type = MM_VIDEO_DEVICE_CAMERA0;
1219
1220       err = mm_camcorder_create(&hcam, &cam_info);
1221
1222
1223
1224       if (err != MM_ERROR_NONE)
1225
1226       {
1227
1228                   printf("Fail to call mm_camcorder_create = %x\n", err);
1229
1230                   return FALSE;
1231
1232       }
1233
1234
1235
1236       mm_camcorder_set_message_callback(hcam,(MMMessageCallback)msg_callback, (void*)hcam);
1237
1238       mm_camcorder_set_video_capture_callback(hcam,(mm_camcorder_video_capture_callback)camcordertest_video_capture_cb, (void*)hcam);
1239
1240
1241
1242       hdisplay = &ad.xid;
1243
1244       hsize = sizeof(ad.xid);
1245
1246
1247
1248       // camcorder attribute setting
1249
1250       err = mm_camcorder_set_attributes((MMHandleType)hcam, &err_attr_name,
1251
1252             MMCAM_MODE, MM_CAMCORDER_MODE_IMAGE,
1253
1254             MMCAM_IMAGE_ENCODER, MM_IMAGE_CODEC_JPEG,
1255
1256             MMCAM_CAMERA_WIDTH, 640,
1257
1258             MMCAM_CAMERA_HEIGHT, 480,
1259
1260             MMCAM_CAMERA_FORMAT, MM_PIXEL_FORMAT_YUYV,
1261
1262             MMCAM_CAMERA_FPS, 30,
1263
1264             MMCAM_DISPLAY_ROTATION, MM_DISPLAY_ROTATION_270,
1265
1266             MMCAM_DISPLAY_HANDLE, (void*) hdisplay,          hsize,
1267
1268             MMCAM_CAPTURE_FORMAT, MM_PIXEL_FORMAT_ENCODED,
1269
1270             MMCAM_CAPTURE_WIDTH, 640,
1271
1272             MMCAM_CAPTURE_HEIGHT, 480,
1273
1274             NULL);
1275
1276
1277
1278       if (err < 0)
1279
1280       {
1281
1282             printf("Set attrs fail. (%s:%x)\n", err_attr_name, err);
1283
1284             if (err_attr_name) {
1285
1286                   free(err_attr_name);
1287
1288                   err_attr_name = NULL;
1289
1290                   return FALSE;
1291
1292             }
1293
1294       }
1295
1296
1297
1298       err =  mm_camcorder_realize(hcam);
1299
1300       if (err < 0)
1301
1302       {
1303
1304             printf("Fail to call mm_camcorder_realize  = %x\n", err);
1305
1306             return FALSE;
1307
1308       }
1309
1310
1311
1312       // start camcorder
1313
1314       err = mm_camcorder_start(hcam);
1315
1316       if (err < 0)
1317
1318       {
1319
1320             printf("Fail to call mm_camcorder_start  = %x\n", err);
1321
1322             return FALSE;
1323
1324       }
1325
1326
1327
1328       return TRUE;
1329
1330 }
1331
1332 @endcode
1333
1334 Basically, you can check the return value to determine whether the function succeeded. But camcorder is composed of several thread context. So you have to check error code delievered by the message callback as well. It will notify you of errors that happened in other asynchronous contexts.
1335
1336 @}
1337 @defgroup Camcorder_uc2 Initialize Camcorder for Video capture
1338 @ingroup Camcorder_UC
1339 @{
1340
1341 <h2 class="pg">Initialize Camcorder for Video capture</h2>
1342 - Purpose
1343         - Start preview for video recording
1344
1345
1346
1347 Everything is the same with "Initialize Camcorder for Image capture" except for two things:
1348
1349 -# You don't need to set 'mm_camcorder_set_video_capture_callback' because the function is for capturing image.
1350 -# Set different attributes. For example, you have to specify types of encoder for audio and video, types of fileformat (this will define muxer). You should also define detail settings of video and audio input. Set proper filename to 'MMCAM_TARGET_FILENAME', too.
1351
1352
1353
1354
1355
1356 The following is a sample code:
1357
1358 @code
1359 MMHandleType hcam = 0;
1360
1361 struct appdata
1362 {
1363         ...
1364         int xid;
1365         ...
1366 };
1367 struct appdata ad;
1368
1369
1370 static gboolean initialize_video_capture()
1371
1372 {
1373
1374       int err;
1375
1376       MMCamPreset cam_info;
1377
1378       char *err_attr_name = NULL;
1379
1380       void * hdisplay = NULL;
1381
1382       int hsize = 0;
1383
1384
1385
1386       cam_info.videodev_type = MM_VIDEO_DEVICE_CAMERA0;
1387
1388       err = mm_camcorder_create(&hcam, &cam_info);
1389
1390       if (err != MM_ERROR_NONE)
1391       {
1392
1393                   printf("Fail to call mm_camcorder_create = %x\n", err);
1394
1395                   return FALSE;
1396
1397       }
1398
1399
1400
1401       mm_camcorder_set_message_callback(hcam,(MMMessageCallback)msg_callback, hcam);
1402
1403
1404
1405       hdisplay = &ad.xid;
1406
1407       hsize = sizeof(ad.xid);
1408
1409
1410
1411       // camcorder attribute setting
1412
1413       err = mm_camcorder_set_attributes((MMHandleType)hcam, &err_attr_name,
1414
1415             MMCAM_MODE, MM_CAMCORDER_MODE_VIDEO,
1416
1417             MMCAM_AUDIO_DEVICE, MM_AUDIO_DEVICE_MIC,
1418
1419             MMCAM_AUDIO_ENCODER, MM_AUDIO_CODEC_AAC,
1420
1421             MMCAM_VIDEO_ENCODER, MM_VIDEO_CODEC_MPEG4,
1422
1423             MMCAM_FILE_FORMAT, MM_FILE_FORMAT_3GP,
1424
1425             MMCAM_CAMERA_WIDTH, 1280,
1426
1427             MMCAM_CAMERA_HEIGHT, 720,
1428
1429             MMCAM_CAMERA_FORMAT, MM_PIXEL_FORMAT_NV12,
1430
1431             MMCAM_CAMERA_FPS, 30,
1432
1433             MMCAM_AUDIO_SAMPLERATE, 44100,
1434
1435             MMCAM_AUDIO_FORMAT, MM_CAMCORDER_AUDIO_FORMAT_PCM_S16_LE,
1436
1437             MMCAM_AUDIO_CHANNEL, 2,
1438
1439             MMCAM_AUDIO_INPUT_ROUTE, MM_AUDIOROUTE_CAPTURE_NORMAL,
1440
1441             MMCAM_DISPLAY_ROTATION, MM_DISPLAY_ROTATION_270,
1442
1443             MMCAM_DISPLAY_HANDLE, (void*) hdisplay,        hsize,
1444
1445             MMCAM_TARGET_FILENAME, TARGET_FILENAME, strlen(TARGET_FILENAME),
1446
1447             NULL);
1448
1449
1450
1451       if (err < 0)
1452
1453       {
1454
1455             printf("Set attrs fail. (%s:%x)\n", err_attr_name, err);
1456
1457             if (err_attr_name) {
1458
1459                   free(err_attr_name);
1460
1461                   err_attr_name = NULL;
1462
1463                   return FALSE;
1464
1465             }
1466
1467       }
1468
1469
1470
1471       err =  mm_camcorder_realize(hcam);
1472
1473       if (err < 0)
1474
1475       {
1476
1477             printf("Fail to call mm_camcorder_realize  = %x\n", err);
1478
1479             return FALSE;
1480
1481       }
1482
1483
1484
1485       // start camcorder
1486
1487       err = mm_camcorder_start(hcam);
1488
1489       if (err < 0)
1490
1491       {
1492
1493             printf("Fail to call mm_camcorder_start  = %x\n", err);
1494
1495             return FALSE;
1496
1497       }
1498
1499
1500
1501       return TRUE;
1502
1503 }
1504 @endcode
1505
1506 @}
1507 @defgroup Camcorder_uc3 Initialize Camcorder for Audio capture
1508 @ingroup Camcorder_UC
1509 @{
1510
1511 <h2 class="pg">Initialize Camcorder for Audio capture</h2>
1512 - Purpose
1513         - Prepare for audio recording
1514
1515 Everything is the same with "Initialize Camcorder for Video capture" except for attributes settings:
1516 -# In this case, you don't need to set video information.
1517
1518
1519
1520 The following is a sample code:
1521
1522 @code
1523 MMHandleType hcam = 0;
1524
1525 struct appdata
1526 {
1527         ...
1528         int xid;
1529         ...
1530 };
1531 struct appdata ad;
1532
1533
1534 static gboolean initialize_audio_capture()
1535
1536 {
1537
1538       int err;
1539
1540       MMCamPreset cam_info;
1541
1542       char *err_attr_name = NULL;
1543
1544       void * hdisplay = NULL;
1545
1546       int hsize = 0;
1547
1548
1549
1550       cam_info.videodev_type = MM_VIDEO_DEVICE_NONE;
1551
1552
1553
1554       err = mm_camcorder_create(&hcam, &cam_info);
1555
1556
1557
1558       if (err != MM_ERROR_NONE)
1559
1560       {
1561
1562             printf("Fail to call mm_camcorder_create = %x\n", err);
1563
1564             return FALSE;
1565
1566       }
1567
1568
1569
1570       mm_camcorder_set_message_callback(hcam,(MMMessageCallback)msg_callback, (void*)hcam);
1571
1572
1573
1574       hdisplay = &ad.xid;
1575
1576       hsize = sizeof(ad.xid);
1577
1578
1579
1580      // camcorder attribute setting
1581
1582       err = mm_camcorder_set_attributes((MMHandleType)hcam, &err_attr_name,
1583
1584             MMCAM_MODE, MM_CAMCORDER_MODE_AUDIO,
1585
1586             MMCAM_AUDIO_DEVICE, MM_AUDIO_DEVICE_MIC,
1587
1588             MMCAM_AUDIO_ENCODER, MM_AUDIO_CODEC_AAC,
1589
1590             MMCAM_FILE_FORMAT, MM_FILE_FORMAT_3GP,
1591
1592             MMCAM_AUDIO_SAMPLERATE, 44100,
1593
1594             MMCAM_AUDIO_FORMAT, MM_CAMCORDER_AUDIO_FORMAT_PCM_S16_LE,
1595
1596             MMCAM_AUDIO_CHANNEL, 2,
1597
1598             MMCAM_AUDIO_INPUT_ROUTE, MM_AUDIOROUTE_CAPTURE_NORMAL,
1599
1600             MMCAM_TARGET_FILENAME, TARGET_FILENAME, strlen(TARGET_FILENAME),
1601
1602             MMCAM_TARGET_TIME_LIMIT, 360000,
1603
1604             NULL);
1605
1606
1607
1608       if (err < 0)
1609
1610       {
1611
1612             printf("Set attrs fail. (%s:%x)\n", err_attr_name, err);
1613
1614             if (err_attr_name) {
1615
1616                   free(err_attr_name);
1617
1618                   err_attr_name = NULL;
1619
1620                   return FALSE;
1621
1622             }
1623
1624       }
1625
1626
1627
1628       err =  mm_camcorder_realize(hcam);
1629
1630       if (err < 0)
1631
1632       {
1633
1634             printf("Fail to call mm_camcorder_realize  = %x\n", err);
1635
1636             return FALSE;
1637
1638       }
1639
1640
1641
1642       // start camcorder
1643
1644       err = mm_camcorder_start(hcam);
1645
1646       if (err < 0)
1647
1648       {
1649
1650             printf("Fail to call mm_camcorder_start  = %x\n", err);
1651
1652             return FALSE;
1653
1654       }
1655
1656
1657
1658       return TRUE;
1659
1660 }
1661 @endcode
1662
1663 @}
1664 @defgroup Camcorder_uc4 Uninitialize camcorder
1665 @ingroup Camcorder_UC
1666 @{
1667
1668 <h2 class="pg">Uninitialize camcorder</h2>
1669 - Purpose
1670         - Destory camcorder handle and resources
1671
1672 - Preliminary condition
1673         - Camcorder is lauched for Image capture, Video capture, or Audio capture.
1674
1675
1676
1677 The initialized camcorder is uninitialized by using the following steps:
1678 -# Stop receiving the video input stream using mm_camcorder_stop(). In audio capture mode, it will stop pipeline itself.
1679 -# Free the allocated memory and release devices calling mm_camcorder_unrealize().
1680 -# Destroy the camcorder handle instance using mm_camcorder_destroy().
1681
1682
1683
1684 The following is a sample code:
1685
1686 @code
1687 static gboolean uninitialize_camcorder()
1688
1689 {
1690
1691       int err;
1692
1693
1694
1695       err =  mm_camcorder_stop(hcam);
1696
1697       if (err < 0)
1698
1699       {
1700
1701             printf("Fail to call mm_camcorder_stop  = %x\n", err);
1702
1703             return FALSE;
1704
1705       }
1706
1707
1708
1709       err =  mm_camcorder_unrealize(hcam);
1710
1711       if (err < 0)
1712
1713       {
1714
1715             printf("Fail to call mm_camcorder_unrealize  = %x\n", err);
1716
1717             return FALSE;
1718
1719       }
1720
1721
1722
1723       err = mm_camcorder_destroy(hcam);
1724
1725       if (err < 0)
1726
1727       {
1728
1729             printf("Fail to call mm_camcorder_destroy  = %x\n", err);
1730
1731             return FALSE;
1732
1733       }
1734
1735
1736
1737       return TRUE;
1738
1739 }
1740 @endcode
1741 @}
1742 @defgroup Camcorder_uc5 Capturing Picture
1743 @ingroup Camcorder_UC
1744 @{
1745
1746 <h2 class="pg">Capturing Picture</h2>
1747 - Purpose
1748         - Capturing still image
1749
1750 - Preliminary condition
1751         - Camcorder is launched for Image capture mode. Refer to "Initialize Camcorder for Image capture".
1752
1753 Steps:
1754 -# Initialize camcorder for image capture as explained in "Initialize Camcorder for Image capture".
1755 -# Start capturing the still image using mm_camcorder_capture_start().  The status of the camcorder is changed to 'MM_CAMCORDER_STATE_CAPTURING' after success.
1756 -# You can stop capturing the still image using mm_camcorder_capture_stop(). But do not call mm_camcorder_capture_stop(), just after calling mm_camcorder_capture_start(). Because captured image is retrieved asynchronously, you can call mm_camcorder_capture_stop() after receiving the 'MM_MESSAGE_CAMCORDER_CAPTURE' message.
1757 -# Beware! Since message callback of camcorder is operated on main loop of the application, you shouldn't hold main loop when you are waiting for the message 'MM_MESSAGE_CAMCORDER_CAPTURED'.
1758 -# Recommended implementation is
1759         -# Just call mm_camcorder_capture_start() and return
1760         -# Wait for capture callback that you registered (the callback function that you set to 'mm_camcorder_set_video_capture_callback')
1761         -# Wait for 'MM_MESSAGE_CAMCORDER_CAPTURED' message
1762         -# Then call mm_camcorder_capture_stop() in the context of the message or another idle callback.
1763 -# Uninitialize camcorder as explained in "Uninitialize camcorder"
1764
1765
1766
1767 The following is a sample code:
1768
1769 @code
1770 static gboolean capturing_picture()
1771
1772 {
1773
1774       int err;
1775
1776
1777
1778       err =  mm_camcorder_capture_start(hcam);
1779
1780       if (err < 0)
1781
1782       {
1783
1784             printf("Fail to call mm_camcorder_capture_start  = %x\n", err);
1785
1786             return FALSE;
1787
1788       }
1789
1790
1791
1792       // mm_camcorder_capture_stop should be called after getting the message
1793       // - MM_MESSAGE_CAMCORDER_CAPTURED message
1794
1795
1796       return TRUE;
1797
1798 }
1799 @endcode
1800
1801
1802 Handling for captured message, please refer to the callback function of "Set Message Callback".
1803
1804 @}
1805 @defgroup Camcorder_uc6 Record and Save a Audio/Video file or a Audio only file
1806 @ingroup Camcorder_UC
1807 @{
1808
1809 <h2 class="pg">Record and Save a Audio/Video file or a Audio only file</h2>
1810 - Purpose
1811         - Start recording and save the file
1812
1813 - Preliminary condition
1814         - Camcorder is launched for Video capture mode. (Refer "Initialize Camcorder for Video capture".)
1815         - Or Camcorder is launched for Audio capture mode. (Refer "Initialize Camcorder for Video capture".)
1816
1817
1818
1819 A video is recorded and saved by camcorder by using the following steps:
1820 -# Initialize camcorder for video capture or audio capture
1821 -# Start audio/video recording using mm_camcorder_record().
1822 -# Save the recorded Video file using mm_camcorder_commit().
1823 -# Uninitialize camcorder. Refer "Uninitialize camcorder".
1824
1825 The procedure of "Audio recording" and "Audio/Video recording" is just same except for settings for video related attributes.
1826
1827
1828
1829 The following is a sample code:
1830
1831 @code
1832 static gboolean record_and_save_video_file()
1833
1834 {
1835
1836       int err;
1837
1838
1839
1840       // Start recording
1841
1842       err =  mm_camcorder_record(hcam);
1843
1844       if (err < 0)
1845
1846       {
1847
1848             printf("Fail to call mm_camcorder_record  = %x\n", err);
1849
1850             return FALSE;
1851
1852       }
1853
1854
1855       // Wait while recording
1856       // ...
1857
1858
1859       // Save file /
1860
1861       err =  mm_camcorder_commit(hcam);
1862
1863       if (err < 0)
1864
1865       {
1866
1867             printf("Fail to call mm_camcorder_commit  = %x\n", err);
1868
1869             return FALSE;
1870
1871       }
1872
1873
1874
1875       return TRUE;
1876
1877 }
1878 @endcode
1879
1880 In the above example code, MMCamcorderRecord and MMCamcorderCommit will return immediately, but whether the video is captured and saved successfully or not is known through a callback function which is set using the API MMCamcorderSetMessageCallback.
1881
1882 @}
1883
1884 @defgroup Camcorder_uc7 Record and Cancel saving of a recording file
1885 @ingroup Camcorder_UC
1886 @{
1887 <h2 class="pg">Record and Cancel saving of a recording file</h2>
1888 - Purpose
1889         - Cancel the operation while recording.
1890
1891 - Preliminary condition
1892         - Camcorder is launched for Video capture mode. (Refer "Initialize Camcorder for Video capture".)
1893         - Or Camcorder is launched for Audio capture mode. (Refer "Initialize Camcorder for Video capture".)
1894
1895
1896
1897 A video is recorded and not saved by camcorder by using the following steps:
1898 -# Initialize camcorder for video capture or audio capture
1899 -# Start audio/video recording using mm_camcorder_record().
1900 -# Cancel saving the recorded Video file using mm_camcorder_cancel().
1901 -# Uninitialize camcorder. Refer "Uninitialize camcorder".
1902
1903
1904
1905 The following is a sample code:
1906
1907 @code
1908
1909 static gboolean record_and_cancel_video_file()
1910
1911 {
1912
1913       int err;
1914
1915
1916
1917       // Start recording
1918
1919       err =  mm_camcorder_record(hcam);
1920
1921       if (err < 0)
1922
1923       {
1924
1925             printf("Fail to call mm_camcorder_record  = %x\n", err);
1926
1927             return FALSE;
1928
1929       }
1930
1931
1932       // Wait while recording
1933       // ...
1934
1935
1936       // Cancel recording
1937
1938       err =  mm_camcorder_cancel(hcam);
1939
1940       if (err < 0)
1941
1942       {
1943
1944             printf("Fail to call mm_camcorder_cancel = %x\n", err);
1945
1946             return FALSE;
1947
1948       }
1949
1950
1951
1952       return TRUE;
1953
1954 }
1955 @endcode
1956 @}
1957
1958 @defgroup Camcorder_uc8 Record, Pause and resume recording
1959 @ingroup Camcorder_UC
1960 @{
1961
1962 <h2 class="pg">Record, Pause and resume recording</h2>
1963 - Purpose
1964         - Pause and Resume operation while recording
1965
1966 - Preliminary condition
1967         - Camcorder is launched for Video capture mode. (Refer "Initialize Camcorder for Video capture".)
1968         - Or Camcorder is launched for Audio capture mode. (Refer "Initialize Camcorder for Video capture".)
1969
1970
1971 Recording, pausing and resuming recording of a video file is accomplished by using the following steps:
1972 -# Initialize camcorder for video capture or audio capture
1973 -# Start recording calling mm_camcorder_record().
1974 -# Pause recording. mm_camcorder_pause().
1975 -# When you want to resume recording, call mm_camcorder_record again.
1976 -# Save the recorded file. mm_camcorder_commit().
1977 -# Uninitialize camcorder. Refer "Uninitialize camcorde".
1978
1979
1980 The following is a sample code:
1981
1982 @code
1983 static gboolean record_pause_and_resume_recording()
1984
1985 {
1986
1987       int err;
1988
1989
1990
1991       // Start recording
1992
1993       err =  mm_camcorder_record(hcam);
1994
1995       if (err < 0)
1996
1997       {
1998
1999             printf("Fail to call mm_camcorder_record  = %x\n", err);
2000
2001             return FALSE;
2002
2003       }
2004
2005
2006       // Wait while recording
2007       // ...
2008
2009
2010       // Pause
2011
2012       err =  mm_camcorder_pause(hcam);
2013
2014       if (err < 0)
2015
2016       {
2017
2018             printf("Fail to call mm_camcorder_pause  = %x\n", err);
2019
2020             return FALSE;
2021
2022       }
2023
2024
2025       // Pausing...
2026
2027
2028       // Resume
2029
2030       err =  mm_camcorder_record(hcam);
2031
2032       if (err < 0)
2033
2034       {
2035
2036             printf("Fail to call mm_camcorder_record  = %x\n", err);
2037
2038             return FALSE;
2039
2040       }
2041
2042
2043       // Wait while recording
2044       // ...
2045
2046
2047       // Save file
2048
2049       err =  mm_camcorder_commit(hcam);
2050
2051       if (err < 0)
2052
2053       {
2054
2055             printf("Fail to call mm_camcorder_commit  = %x\n", err);
2056
2057             return FALSE;
2058
2059       }
2060
2061
2062
2063       return TRUE;
2064
2065 }
2066 @endcode
2067
2068
2069 Even though recording is paused, preview is continuously displayed.
2070
2071 @}
2072 @defgroup Camcorder_uc9 Get state of camcorder
2073 @ingroup Camcorder_UC
2074 @{
2075
2076 <h2 class="pg">Get state of camcorder</h2>
2077 - Purpose
2078         - Get the current state of camcorder
2079
2080 If handle is available, you can get the current status of camcorder using mm_camcorder_get_state()
2081
2082 The following is a sample code:
2083
2084 @code
2085 static gboolean get_state_of_camcorder()
2086
2087 {
2088
2089       MMCamcorderStateType state;
2090
2091
2092
2093       mm_camcorder_get_state(hcam, &state);
2094
2095       printf("Current status is %d\n", state);
2096
2097
2098
2099       return TRUE;
2100
2101 }
2102 @endcode
2103
2104 @}
2105 @defgroup Camcorder_uc10 Start and Stop focus
2106 @ingroup Camcorder_UC
2107 @{
2108
2109
2110 <h2 class="pg">Start and Stop focus</h2>
2111 - Purpose
2112         - Adjust lens focus
2113
2114 - Preliminary condition
2115         - Camcorder is launched for Image or Video capture mode. Refer "Initialize Camcorder for Image capture" and "Initialize Camcorder for Video capture".
2116
2117
2118
2119 Starting and Stopping focus feature of camcorder:
2120 -# Initialize camcorder for image or video capture as explained in "Initialize Camcorder for Video capture" or "Initialize Camcorder for Image capture".
2121 -# Set proper focusing mode using attribute 'MMCAM_CAMERA_FOCUS_MODE' and 'MMCAM_CAMERA_AF_SCAN_RANGE'.
2122 -# Initialize auto focus mode and adjust the camera lens to initial position using mm_camcorder_init_focusing().
2123 -# Start focusing of camcorder using mm_camcorder_start_focusing().
2124 -# Focusing state will be sent through message callback.  (MM_MESSAGE_CAMCORDER_FOCUS_CHANGED)
2125 -# If you want to stop focusing immediately, call mm_camcorder_stop_focusing().
2126 -# But in general case, you don't need to call this. Just wait the message.
2127 -# Uninitialize camcorder. Refer "Uninitialize camcorder".
2128
2129
2130 The following is a samsple code
2131
2132 @code
2133 static gboolean start_autofocus()
2134
2135 {
2136
2137       int err;
2138
2139       char * err_attr_name = NULL;
2140
2141
2142
2143       // Set focus mode to 'AUTO' and scan range to 'AF Normal'
2144
2145       err = mm_camcorder_set_attributes((MMHandleType)hcam, &err_attr_name,
2146
2147             MMCAM_CAMERA_FOCUS_MODE, MM_CAMCORDER_FOCUS_MODE_AUTO,
2148
2149             MMCAM_CAMERA_AF_SCAN_RANGE, MM_CAMCORDER_AUTO_FOCUS_NORMAL,
2150
2151             NULL);
2152
2153
2154
2155       if (err < 0)
2156
2157       {
2158
2159             printf("Set attrs fail. (%s:%x)\n", err_attr_name, err);
2160
2161             if (err_attr_name) {
2162
2163                   free(err_attr_name);
2164
2165                   err_attr_name = NULL;
2166
2167                   return FALSE;
2168
2169             }
2170
2171       }
2172
2173       mm_camcorder_init_focusing(hcam);
2174
2175       mm_camcorder_start_focusing(hcam);
2176
2177       printf("Waiting for adjusting focus\n");
2178
2179
2180
2181       // Waiting for 'MM_MESSAGE_CAMCORDER_FOCUS_CHANGED'
2182       // ...
2183
2184
2185       return TRUE;
2186
2187 }
2188 @endcode
2189
2190 @}
2191 @defgroup Camcorder_uc11 User defined filename for recording file
2192 @ingroup Camcorder_UC
2193 @{
2194
2195 <h2 class="pg">User defined filename for recording file</h2>
2196
2197 To Save an video or audio captured file with user defined name, you have to set an attribute named 'MMCAM_TARGET_FILENAM'.
2198
2199 In image capture mode, there is no interface to set the name of captured file because camcorder gives you a captured buffer directly. You can create an image file with proper name in the application.
2200
2201
2202 The following is a samsple code
2203
2204 @code
2205 static gboolean filename_setting()
2206
2207 {
2208
2209       int err;
2210
2211       char * new_filename =  "new_name.mp4";
2212
2213
2214
2215       // camcorder attribute setting
2216
2217       err = mm_camcorder_set_attributes((MMHandleType)hcam, NULL,
2218
2219                              MMCAM_TARGET_FILENAME, new_filename, strlen(new_filename),
2220
2221                              NULL);
2222
2223
2224
2225       printf("New file name (%s)\n", new_filename);
2226
2227
2228       return TRUE;
2229
2230 }
2231 @endcode
2232
2233 @}
2234 @defgroup Camcorder_uc12 Set VideoStream Callback
2235 @ingroup Camcorder_UC
2236 @{
2237
2238 <h2 class="pg">Set VideoStream Callback</h2>
2239
2240 MMCamcorderSetVideoStreamCallback API is used to set callback for receiving video stream data (preview) from the camcorder.
2241
2242
2243
2244 The following is a sample code:
2245
2246 @code
2247 static gboolean set_video_stream_callback()
2248
2249 {
2250
2251       mm_camcorder_set_video_stream_callback(hcam, (mm_camcorder_video_stream_callback)camcordertest_video_stream_cb, (void*)hcam);
2252
2253
2254       return TRUE;
2255
2256 }
2257 @endcode
2258 @code
2259 static int
2260
2261 camcordertest_video_stream_cb(MMCamcorderVideoStreamDataType *stream, void *user_param)
2262
2263 {
2264
2265       int nret = 0;
2266
2267
2268
2269       printf("stream cb is called(%p, %d, %d)\n",  stream->data, stream->width, stream->height);
2270
2271
2272
2273       return TRUE;
2274
2275 }
2276 @endcode
2277
2278 @}
2279 @defgroup Camcorder_uc13 Set VideoCapture Callback
2280 @ingroup Camcorder_UC
2281 @{
2282
2283 <h2 class="pg">Set VideoCapture Callback</h2>
2284
2285 mm_camcorder_set_video_capture_callback() is used to set callback for receiving still capture data from the camcorder. In here, you can handle the result data.
2286
2287
2288 The following is a sample code:
2289
2290 @code
2291 mm_camcorder_set_video_capture_callback(hcam,(mm_camcorder_video_capture_callback)
2292
2293 camcordertest_video_capture_cb, (void*)hcam);
2294 @endcode
2295 @code
2296 static int
2297
2298 camcordertest_video_capture_cb(MMCamcorderCaptureDataType *src, MMCamcorderCaptureDataType *thumb, void *preview)
2299
2300 {
2301
2302       int nret = 0;
2303
2304       char m_filename[MAX_STRING_LEN];
2305
2306       FILE* fp=NULL;
2307
2308
2309
2310       sprintf(m_filename, "%s%03d.jpg", "./stillshot_", stillshot_count++);
2311
2312
2313
2314       printf("filename : %s\n",  m_filename);
2315
2316
2317
2318       fp=fopen(m_filename, "w+");
2319
2320       if(fp==NULL)
2321
2322       {
2323
2324             printf("FileOPEN error!!\n");
2325
2326             return FALSE;
2327
2328       }
2329
2330       else
2331
2332       {
2333
2334             printf("open success\n\n");
2335
2336             if(fwrite(src->data, src->length, 1, fp )!=1)
2337
2338             {
2339
2340                   printf("File write error!!\n");
2341
2342                   return FALSE;
2343
2344             }
2345
2346             printf("write success\n");
2347
2348       }
2349
2350       fclose(fp);
2351
2352       printf("Capture done!\n");
2353
2354
2355
2356       return TRUE;
2357
2358 }
2359 @endcode
2360
2361 @}
2362 @defgroup Camcorder_uc14 Set Message Callback
2363 @ingroup Camcorder_UC
2364 @{
2365
2366 <h2 class="pg">Set Message Callback</h2>
2367
2368 The following is a sample code:
2369 @code
2370 mm_camcorder_set_message_callback(hcam,(MMMessageCallback)msg_callback, (void*)hcam);
2371 @endcode
2372
2373 The following code snippet explains the callback function for 'MMMessageCallback':
2374 - First argument gives the index of the message. You can handle each message with the value.
2375 - Second argument has a parameter structure that holds useful values for application. The original parameter type is 'MMMessageParamType'.
2376 - It has several fields for message including union structure. By checking 'union_type' field, you can determine which type of union is used. For the type of union, refer 'MMMessageUnionType' in 'mm_types.h'.
2377 - One message type only has one specific union in anycase. Please refer following table
2378
2379
2380 <table>
2381         <tr>
2382                 <td>
2383                 MM_MESSAGE_CAMCORDER_STATE_CHANGED
2384                 </td>
2385                 <td>
2386                 MM_MSG_UNION_STATE
2387                 </td>
2388         </tr>
2389         <tr>
2390                 <td>
2391                 MM_MESSAGE_CAMCORDER_STATE_CHANGED_BY_ASM
2392                 </td>
2393                 <td>
2394                 MM_MSG_UNION_STATE
2395                 </td>
2396         </tr>
2397         <tr>
2398                 <td>
2399                 MM_MESSAGE_CAMCORDER_RECORDING_STATUS
2400                 </td>
2401                 <td>
2402                 MM_MSG_UNION_RECORDING_STATUS
2403                 </td>
2404         </tr>
2405         <tr>
2406                 <td>
2407                 MM_MESSAGE_CAMCORDER_FIRMWARE_UPDATE
2408                 </td>
2409                 <td>
2410                 MM_MSG_UNION_FIRMWARE
2411                 </td>
2412         </tr>
2413         <tr>
2414                 <td>
2415                 MM_MESSAGE_CAMCORDER_TIME_LIMIT
2416                 </td>
2417                 <td>
2418                 MM_MSG_UNION_CODE
2419                 </td>
2420         </tr>
2421         <tr>
2422                 <td>
2423                 MM_MESSAGE_CAMCORDER_MAX_SIZE
2424                 </td>
2425                 <td>
2426                 MM_MSG_UNION_CODE
2427                 </td>
2428         </tr>
2429         <tr>
2430                 <td>
2431                 MM_MESSAGE_CAMCORDER_NO_FREE_SPACE
2432                 </td>
2433                 <td>
2434                 MM_MSG_UNION_CODE
2435                 </td>
2436         </tr>
2437         <tr>
2438                 <td>
2439                 MM_MESSAGE_CAMCORDER_ERROR
2440                 </td>
2441                 <td>
2442                 MM_MSG_UNION_CODE
2443                 </td>
2444         </tr>
2445         <tr>
2446                 <td>
2447                 MM_MESSAGE_CAMCORDER_FOCUS_CHANGED
2448                 </td>
2449                 <td>
2450                 MM_MSG_UNION_CODE
2451                 </td>
2452         </tr>
2453         <tr>
2454                 <td>
2455                 MM_MESSAGE_CAMCORDER_CURRENT_VOLUME
2456                 </td>
2457                 <td>
2458                 MM_MSG_UNION_CODE
2459                 </td>
2460         </tr>
2461         <tr>
2462                 <td>
2463                 MM_MESSAGE_CAMCORDER_CAPTURED
2464                 </td>
2465                 <td>
2466                 MM_MSG_UNION_CODE
2467                 </td>
2468         </tr>
2469         <tr>
2470                 <td>
2471                 MM_MESSAGE_READY_TO_RESUME
2472                 </td>
2473                 <td>
2474                 MM_MSG_UNION_CODE
2475                 </td>
2476         </tr>
2477 </table>
2478
2479 - 'MM_MESSAGE_READY_TO_RESUME' is a message type that notifies that the camcorder is able to start again after being halting by internal session manager.
2480
2481 @code
2482 static gboolean msg_callback(int message, void *msg_param, void *user_param)
2483
2484 {
2485
2486       MMHandleType hcamcorder = (MMHandleType)user_param;
2487
2488       MMMessageParamType *param = (MMMessageParamType *) msg_param;
2489
2490       int err = 0;
2491
2492
2493
2494       switch (message) {
2495
2496             case MM_MESSAGE_CAMCORDER_ERROR:
2497
2498                   printf("MM_MESSAGE_CAMCORDER_ERROR : code = %x\n", param->code);
2499
2500                   break;
2501
2502             case MM_MESSAGE_CAMCORDER_STATE_CHANGED:
2503
2504                   g_current_state = param->state.current;
2505
2506                   break;
2507
2508
2509
2510             case MM_MESSAGE_CAMCORDER_CAPTURED:
2511
2512             {
2513
2514                   //Get mode of camcorder
2515
2516                   int mode = 0;
2517
2518                   err = mm_camcorder_get_attributes(hcamcorder, NULL,
2519
2520                         MMCAM_MODE,  &mode,
2521
2522                          NULL);
2523
2524
2525
2526                   if (mode == MM_CAMCORDER_MODE_IMAGE)
2527
2528                   {
2529
2530                         printf("Stillshot Captured!!(number=%d)\n", param->code);
2531
2532
2533
2534                         err =  mm_camcorder_capture_stop(hcam);
2535
2536                         if (err < 0)
2537
2538                         {
2539
2540                              printf("Fail to call mm_camcorder_capture_start= %x\n", err);
2541
2542                              return FALSE;
2543
2544                         }
2545
2546                   }
2547
2548                   else
2549
2550                   {
2551
2552                         //Audio/Video recording
2553
2554                         MMCamRecordingReport* report ;
2555
2556
2557
2558                         if (param)
2559
2560                              report = (MMCamRecordingReport*)(param->data);
2561
2562                         else
2563
2564                              return FALSE;
2565
2566
2567
2568                         printf("Recording Complete(filename=%s)\n", report->recording_filename);
2569
2570
2571
2572                         if (report->recording_filename)
2573
2574                              free(report->recording_filename);
2575
2576
2577
2578                         if (report)
2579
2580                              free(report);
2581
2582                   }
2583
2584             }
2585
2586                   break;
2587
2588             case MM_MESSAGE_CAMCORDER_RECORDING_STATUS:
2589
2590             {
2591
2592                   unsigned int elapsed;
2593
2594                   elapsed = param->recording_status.elapsed / 1000;
2595
2596                   if (elapsed_time != elapsed) {
2597
2598                         unsigned int temp_time;
2599
2600                         int hour, minute, second;
2601
2602                         elapsed_time = elapsed;
2603
2604                         temp_time = elapsed;
2605
2606                         hour = temp_time / 3600;
2607
2608                         temp_time = elapsed % 3600;
2609
2610                         minute = temp_time / 60;
2611
2612                         second = temp_time % 60;
2613
2614                         printf("Current Time - %d:%d:%d\n", hour, minute, second);
2615
2616                   }
2617
2618             }
2619
2620                   break;
2621
2622             case MM_MESSAGE_CAMCORDER_MAX_SIZE:
2623
2624             {
2625
2626                   printf("Reach Size limitation.\n");
2627
2628
2629
2630                   // After reaching max size, Camcorder starts to drop all buffers that
2631
2632                   it receives. You have to call mm_camcorder_commit() to finish recording.
2633
2634                   err = mm_camcorder_commit(hcamcorder);
2635
2636
2637
2638                   if (err < 0)
2639
2640                   {
2641
2642                         printf("Save recording mm_camcorder_commit  = %x\n", err);
2643
2644                   }
2645
2646             }
2647
2648                   break;
2649
2650             case MM_MESSAGE_CAMCORDER_NO_FREE_SPACE:
2651
2652             {
2653
2654                   printf("There is no space in storage.\n");
2655
2656
2657
2658                   // If there is no free space to save recording frame, Camcorder starts to
2659
2660                      drop all buffers that it receives.
2661
2662                      You have to call mm_camcorder_commit() to finish recording.
2663
2664                   err = mm_camcorder_commit(hcamcorder);
2665
2666
2667
2668                   if (err < 0)
2669
2670                   {
2671
2672                         printf("Save recording mm_camcorder_commit  = %x\n", err);
2673
2674                   }
2675
2676             }
2677
2678                   break;
2679
2680             case MM_MESSAGE_CAMCORDER_TIME_LIMIT:
2681
2682             {
2683
2684                   printf("Reach time limitation.\n");
2685
2686
2687
2688                   // After reaching time limit, Camcorder starts to drop all buffers that it
2689
2690                      receives. You have to call mm_camcorder_commit() to finish recording.
2691
2692                   err = mm_camcorder_commit(hcamcorder);
2693
2694
2695
2696                   if (err < 0)
2697
2698                   {
2699
2700                         printf("Save recording mm_camcorder_commit  = %x\n", err);
2701
2702                   }
2703
2704             }
2705
2706                   break;
2707
2708             case MM_MESSAGE_CAMCORDER_FOCUS_CHANGED:
2709
2710             {
2711
2712                   printf( "Focus State changed. State:[%d]\n", param->code );
2713
2714             }
2715
2716                   break;
2717
2718             default:
2719
2720                   break;
2721
2722       }
2723
2724
2725
2726       return TRUE;
2727
2728 }
2729 @endcode
2730
2731 @}
2732
2733 @defgroup MM_Player Player
2734 @ingroup MultiMediaPG
2735 @{
2736
2737 <h2 class="pg">Player</h2>
2738         @brief <sub class="ref">Also see</sub> Use Cases of @ref Player_UC
2739
2740 This section describes APIs used for playback of multimedia contents.
2741
2742
2743
2744 Player can have 5 states, and each state can be changed by calling the following functions as described in "State of mm_player" diagram.
2745
2746         <table>
2747
2748                 <tr>
2749                                 <td>
2750             <b>FUNCTION</b>
2751                         <td>
2752             <b>PRE-STATE</b><b></b>
2753                                 <td>
2754             <b>POST-STATE</b><b></b>
2755                         <td>
2756             <b>SYNC TYPE</b>
2757                 <tr>
2758                         <td>
2759             <p>mm_player_create()
2760                                 <td>
2761             NONE
2762                                 <td>
2763             NULL
2764                                 <td>
2765             SYNC
2766                 <tr>
2767                         <td>
2768             <p>mm_player_destroy()
2769                                 <td>
2770             NULL
2771                                 <td>
2772             NONE
2773                                 <td>
2774             SYNC
2775                 <tr>
2776                         <td>
2777             <p>mm_player_realize()
2778                                 <td>
2779             NULL
2780                                 <td>
2781             READY
2782                                 <td>
2783             SYNC
2784                 <tr>
2785                         <td>
2786             <p>mm_player_unrealize()
2787                                 <td>
2788             READY
2789                                 <td>
2790             NULL
2791                                 <td>
2792             SYNC
2793                 <tr>
2794                         <td>
2795             <p>mm_player_start()
2796                                 <td>
2797             READY
2798                                 <td>
2799             PLAYING
2800                                 <td>
2801             ASYNC
2802                 <tr>
2803                         <td>
2804             <p>mm_player_stop()
2805                                 <td>
2806             PLAYING
2807                                 <td>
2808             READY
2809                                 <td>
2810             SYNC
2811                 <tr>
2812                         <td>
2813             <p>mm_player_pause()
2814                                 <td>
2815             PLAYING
2816                                 <td>
2817             PAUSED
2818                                 <td>
2819             ASYNC
2820                 <tr>
2821                         <td>
2822             <p>mm_player_resume()
2823                                 <td>
2824             PAUSED
2825                                 <td>
2826             PLAYING
2827                                 <td>
2828             ASYNC
2829         </table>
2830
2831
2832 @image html SLP_MultimediaFW_PG_image003.png
2833 Figure. State of MMPlayer
2834
2835
2836
2837 Most of functions which change player state work as synchronous . But, mm_player_start() should be used asynchronously. Both  mm_player_pause() and mm_player_resume() should also be used asynchronously in the case of streaming data. So, application has to confirm the result through message callback function.
2838
2839
2840
2841 Note: "None" and "Null" state could be reached from any state by calling mm_player_destroy() and mm_player_unrealize().
2842
2843
2844 The following are supported functions in the player module.
2845                 - int mm_player_set_volume(MMHandleType player, MMPlayerVolumeType *volume)
2846                 - int mm_player_get_volume(MMHandleType player, MMPlayerVolumeType *volume)
2847                 - int mm_player_get_mute(MMHandleType player, int *mute)
2848                 - int mm_player_set_mute(MMHandleType player, int mute)
2849                 - int mm_player_set_position(MMHandleType player, MMPlayerPosFormatType format, int pos)
2850                 - int mm_player_get_position(MMHandleType player, MMPlayerPosFormatType format, int *pos)
2851                 - int mm_player_activate_section_repeat(MMHandleType player)
2852                 - int mm_player_deactivate_section_repeat(MMHandleType player, int start, int end)
2853                 - int mm_player_set_message_callback(MMHandleType player, MMMessageCallback callback, void *user_param)
2854                 - int mm_player_set_subtitle_silent(MMHandleType player, int slient)
2855                 - int mm_player_get_subtitle_silent(MMHandleType player, int *slient)
2856                 - int mm_player_set_attribute(MMHandleType player, char **err_attr_name, const char *first_attribute_name, ...)
2857                 - int mm_player_get_attribute(MMHandleType player, char **err_attr_name, const char *first_attribute_name, ...)
2858                 - int mm_player_get_attribute_info(MMHandleType player, const char *attribute_name, MMPlayerAttrsInfo *info)
2859
2860
2861
2862 Application can set/get some values into player library for applying its properties using attributes.
2863
2864
2865
2866 The following are supported attributes list of player library.
2867
2868                         - For more detail information, please refer the doxygen document of player framework.
2869
2870         <table>
2871
2872                 <tr>
2873         <td><b>Attribute Name</b>
2874                                 <td>
2875 <b>Type</b>
2876                                 <td>
2877 <b>Validity Type</b>
2878                                 <td>
2879 <b>Default Value</b>
2880                 <tr>
2881                                 <td>
2882 "profile_uri"                           <td>
2883 string                          <td>
2884 N/A                             <td>
2885 NULL                    <tr>
2886                                 <td>
2887 "profile_user_param"                            <td>
2888 data                            <td>
2889 N/A                             <td>
2890 NULL                    <tr>
2891                                 <td>
2892 "profile_play_count"                            <td>
2893 int                             <td>
2894 range                           <td>
2895 1               <tr>
2896                                 <td>
2897 "streaming_type"                                <td>
2898 int                             <td>
2899 range                           <td>
2900 STREAMING_SERVICE_NONE                  <tr>
2901                                 <td>
2902 "streaming_udp_timeout"                                 <td>
2903 int                             <td>
2904 range                           <td>
2905 1000msec                <tr>
2906                                 <td>
2907 "streaming_user_agent"                          <td>
2908 string                          <td>
2909 N/A                             <td>
2910 NULL                    <tr>
2911                                 <td>
2912 "streaming_wap_profile"                                 <td>
2913 string                          <td>
2914 N/A                             <td>
2915 NULL                    <tr>
2916                                 <td>
2917 "streaming_network_bandwidth"                           <td>
2918 int                             <td>
2919 range                           <td>
2920 128000Hz                <tr>
2921                                 <td>
2922 "streaming_cookie"                              <td>
2923 string                          <td>
2924 N/A                             <td>
2925 NULL                    <tr>
2926                                 <td>
2927 "streaming_proxy_ip"                            <td>
2928 string                          <td>
2929 N/A                             <td>
2930 NULL                    <tr>
2931                                 <td>
2932 "streaming_proxy_port"                          <td>
2933 int                             <td>
2934 range                           <td>
2935 0               <tr>
2936                                 <td>
2937 "display_overlay"                               <td>
2938 int                             <td>
2939 range                           <td>
2940 0               <tr>
2941                                 <td>
2942 "display_rotation"                              <td>
2943 int                             <td>
2944 range                           <td>
2945 MM_DISPLAY_ROTATION_270                 <tr>
2946                                 <td>
2947 "subtitle_uri"                          <td>
2948 string                          <td>
2949 N/A                             <td>
2950 NULL                    <tr>
2951                                 <td>
2952 "content_duration"                              <td>
2953 int                             <td>
2954 range                           <td>
2955 0               <tr>
2956                                 <td>
2957 "content_video_codec"                           <td>
2958 string                          <td>
2959 N/A                             <td>
2960 NULL                    <tr>
2961                                 <td>
2962 "content_video_bitrate"                                 <td>
2963 int                             <td>
2964 array                           <td>
2965 0               <tr>
2966                                 <td>
2967 "content_video_fps"                             <td>
2968 int                             <td>
2969 array                           <td>
2970 0               <tr>
2971                                 <td>
2972 "content_video_width"                           <td>
2973 int                             <td>
2974 range                           <td>
2975 0               <tr>
2976                                 <td>
2977 "content_video_height"                          <td>
2978 int                             <td>
2979 range                           <td>
2980 0               <tr>
2981                                 <td>
2982 "content_video_track_id"                                <td>
2983 int                             <td>
2984 range                           <td>
2985 0               <tr>
2986                                 <td>
2987 "content_video_track_num"                               <td>
2988 int                             <td>
2989 range                           <td>
2990 0               <tr>
2991                                 <td>
2992 "content_audio_codec"                           <td>
2993 string                          <td>
2994 N/A                             <td>
2995 NULL                    <tr>
2996                                 <td>
2997 "content_audio_bitrate"                                 <td>
2998 int                             <td>
2999 array                           <td>
3000 0               <tr>
3001                                 <td>
3002 "content_audio_channels"                                <td>
3003 int                             <td>
3004 range                           <td>
3005 0               <tr>
3006                                 <td>
3007 "content_audio_samplerate"                              <td>
3008 int                             <td>
3009 array                           <td>
3010 0               <tr>
3011                                 <td>
3012 "content_audio_track_id"                                <td>
3013 int                             <td>
3014 range                           <td>
3015 0               <tr>
3016                                 <td>
3017 "content_audio_track_num"                               <td>
3018 int                             <td>
3019 range                           <td>
3020 0               <tr>
3021                                 <td>
3022 "tag_artist"                            <td>
3023 string                          <td>
3024 N/A                             <td>
3025 NULL                    <tr>
3026                                 <td>
3027 "tag_title"                             <td>
3028 string                          <td>
3029 N/A                             <td>
3030 NULL                    <tr>
3031                                 <td>
3032 "tag_album"                             <td>
3033 string                          <td>
3034 N/A                             <td>
3035 NULL                    <tr>
3036                                 <td>
3037 "tag_genre"                             <td>
3038 string                          <td>
3039 N/A                             <td>
3040 NULL                    <tr>
3041                                 <td>
3042 "tag_author"                            <td>
3043 string                          <td>
3044 N/A                             <td>
3045 NULL                    <tr>
3046                                 <td>
3047 "tag_copyright"                                 <td>
3048 string                          <td>
3049 N/A                             <td>
3050 NULL                    <tr>
3051                                 <td>
3052 "tag_date"                              <td>
3053 string                          <td>
3054 N/A                             <td>
3055 NULL                    <tr>
3056                                 <td>
3057 "tag_description"                               <td>
3058 string                          <td>
3059 N/A                             <td>
3060 NULL                    <tr>
3061                                 <td>
3062 "tag_track_num"                                 <td>
3063 int                             <td>
3064 range                           <td>
3065 0
3066         </table>
3067
3068
3069 @}
3070 @defgroup Player_uc1 Create and initialize Player
3071 @ingroup Player_UC
3072 @{
3073 <h2 class="pg">Create and initialize Player</h2>
3074                 - Applications can create the player handle using mm_player_create().
3075                 - And then, attributes for the player such as the url can be set through mm_player_set_attribute() .
3076                 - Fundamentally, one url should be set to play both audio and video contents.
3077                 - The created window id should be set to display video using the "display_overlay" attribute.
3078                 - All messages are sent through message callback functions to the application from the player.
3079                 - So, callback functions should be set to receive messages like error, BOS(Begin Of Stream) and EOS(End Of Stream)
3080                 - Player is a pipelined architecture and basic pipeline is made when mm_player_realize() is called.
3081                 - The following is a sample code to create, realize player and set the url and display id.
3082
3083 @code
3084 MMHandleType g_player = 0;
3085 char **g_err_attr_name;
3086 struct appdata ad;
3087
3088 int ret = MM_ERROR_NONE;
3089
3090 int initialize_video_player(char *filename)
3091 {
3092         if (mm_player_create(&g_player) != MM_ERROR_NONE)
3093         {
3094                 printf("failed to create player\n");
3095         }
3096
3097         if (mm_player_set_attribute(g_player,
3098                                                         g_err_attr_name,
3099                                                         "profile_uri", filename, strlen(filename),
3100                                                         "display_overlay", (void*)&ad.xid, sizeof(ad.xid),
3101                                                         NULL) != MM_ERROR_NONE)
3102         {
3103                 printf("failed to set %s attribute\n", *g_err_attr_name);
3104                 free(g_err_attr_name);
3105         }
3106
3107         mm_player_set_message_callback(g_player, msg_callback, (void*)g_player);
3108
3109         if (mm_player_realize(g_player) != MM_ERROR_NONE)
3110         {
3111                 printf("failed to realize player\n");
3112         }
3113 }
3114
3115 int msg_callback(int message, MMMessageParamType *param, void *user_param)
3116 {
3117         switch (message)
3118         {
3119                 case MM_MESSAGE_ERROR:
3120          // Do something
3121          break;
3122
3123      case MM_MESSAGE_END_OF_STREAM:
3124          // Do something
3125          break;
3126
3127         case MM_MESSAGE_STATE_CHANGED:
3128                 // Do something
3129                 break;
3130
3131         case MM_MESSAGE_BEGIN_OF_STREAM:
3132                 // Do something
3133             break;
3134
3135         default:
3136         return FALSE;
3137         }
3138         return TRUE;
3139 }
3140 @endcode
3141
3142
3143 Set message callback
3144
3145                 - The application must confirm some information or player status from messages of callback. It must be registered before beginning playback.
3146
3147                 - The Followings messages are typically used
3148
3149         <table>
3150
3151                 <tr>                    <td> MM_MESSAGE_ERROR                   </td>           </tr>
3152                 <tr>                    <td> MM_MESSAGE_STATE_CHANGED                   </td>           </tr>
3153                 <tr>                    <td>MM_MESSAGE_BEGIN_OF_STREAM                  </td>           </tr>
3154                 <tr>                    <td>MM_MESSAGE_END_OF_STREAM                    </td>           </tr>
3155                 <tr>                    <td>MM_MESSAGE_UPDATE_SUBTITLE                  </td>           </tr>
3156                 <tr>                    <td>MM_MESSAGE_BUFFERING                        </td>           </tr>
3157
3158         </table>
3159
3160
3161
3162                 - In the case of MM_MESSAGE_ERROR,  application can determine the specific error case from the code value of message parameter.
3163
3164                         - The Followings error codes are typically used.
3165
3166
3167         <table>
3168
3169                 <tr>                    <td>MM_ERROR_PLAYER_INTERNAL                    </td>           </tr>
3170                 <tr>                    <td>MM_ERROR_PLAYER_CODEC_NOT_FOUND                     </td>           </tr>
3171                 <tr>                    <td>MM_ERROR_PLAYER_NOT_SUPPORTED_FORMAT                        </td>           </tr>
3172                 <tr>                    <td>MM_ERROR_PLAYER_NOT_INITIALIZED                     </td>           </tr>
3173                 <tr>                    <td>MM_ERROR_PLAYER_FILE_NOT_FOUND                      </td>           </tr>
3174
3175         </table>
3176
3177                 - Refer to the appendix for more message and error details
3178
3179                 - The following is a sample code of message callback implementation.
3180
3181 @code
3182 void video_player_message_callback(int message, void *param, void *user_param)
3183 {
3184      struct appdata *ad = (struct appdata *)user_param;
3185      MMMessageParamType* msg_param = (MMMessageParamType*)param;
3186
3187      switch(message)
3188         {
3189                 case MM_MESSAGE_ERROR:
3190                         parse_video_player_error_code(msg_param->code, ad);
3191                         break;
3192
3193                 case MM_MESSAGE_BEGIN_OF_STREAM:
3194                         // can update video player UI
3195                         break;
3196
3197                 case MM_MESSAGE_END_OF_STREAM:
3198                         // can close and destroy the player
3199                         ecore_idler_add(video_player_close_handler, ad);
3200                         break;
3201
3202                         //...
3203                 default:
3204                         break;
3205
3206         }
3207 }
3208
3209 void parse_video_player_error_code(int error_code, struct appdata *app_data)
3210 {
3211      switch(error_code)
3212         {
3213                 case MM_ERROR_PLAYER_CODEC_NOT_FOUND:
3214                         // can show up error popup
3215                         break;
3216
3217                 case MM_ERROR_PLAYER_INTERNAL:
3218                         // can show up error popup and close player
3219                         ecore_idler_add(video_player_close_handler, app_data);
3220                         break;
3221
3222                         //...
3223
3224                 default:
3225                         break;
3226         }
3227 }
3228
3229 int video_player_close_handler (void *data)
3230 {
3231      struct appdata *ad = (struct appdata *)data;
3232
3233      close_video_player (ad);
3234      return 0;
3235 }
3236
3237 bool close_video_player (void *data)
3238 {
3239      struct appdata *ad = (struct appdata *)data;
3240
3241      video_player_mgr_unrealize(ad);
3242         video_player_mgr_destroy(ad);
3243 }
3244
3245 bool video_player_mgr_unrealize (void *data)
3246 {
3247      struct appdata *ad = (struct appdata *)data;
3248
3249      if (mm_player_unrealize(ad->player_handle) != MM_ERROR_NONE)
3250          return FALSE;
3251
3252      return TRUE;
3253 }
3254
3255 bool video_player_mgr_destroy (void *data)
3256 {
3257      struct appdata *ad = (struct appdata *)data;
3258
3259      if (mm_player_destroy(ad-> player_handle) != MM_ERROR_NONE)
3260          return FALSE;
3261
3262      return TRUE;
3263 }
3264 @endcode
3265 @}
3266 @defgroup Player_uc2 Get and set attributes
3267 @ingroup Player_UC
3268 @{
3269
3270 <h2 class="pg">Get and set attributes</h2>
3271
3272                 - There are many useful attributes in the player which the Application can set or get to control the player.
3273                 - Those are constructed when the player is created and handled by string id.
3274                 - Supported types are int, double, string and data. And, there is variable parameter in related APIs.
3275                 - In the case of the int and double types, a name/value pair should be set. For the string and data types, the name/value pair should be followed by the size.
3276                 - Finally, application can get the information of each attribute using mm_player_get_attribute_info().
3277                 - The following is a sample code.
3278
3279 @code
3280 /***********************
3281 // get content duration
3282 /***********************
3283
3284
3285
3286 int duration = 0;
3287 char **g_err_attr_name;
3288
3289 if (mm_player_get_attribute(g_player, &g_err_attr_name, "content_duration", &duration, NULL) != MM_ERROR_NONE)
3290 {
3291         printf("failed to set %s attribute\n", *g_err_attr_name);
3292         free(g_err_attr_name);
3293
3294 }
3295
3296 pirntf("file duration is = %d\n", duration);
3297
3298
3299
3300 /***********************
3301 // set content duration
3302 /***********************
3303
3304 int duration = 0;
3305 char **g_err_attr_name;
3306
3307 if (mm_player_get_attribute(g_player, &g_err_attr_name, "content_duration", &duration, NULL) != MM_ERROR_NONE)
3308 {
3309         printf("failed to set %s attribute\n", g_err_attr_name);
3310         free(g_err_attr_name);
3311 }
3312
3313 pirntf("duration is = %d\n", duration);
3314
3315 /***********************
3316 // get attribute info
3317 /***********************
3318
3319 int method = 0;
3320
3321 MMPlayerAttrsInfo method_info = { 0, };
3322
3323 if (mm_player_get_attribute_info (g_player, "display_method", &method_info, NULL) != MM_ERROR_NONE)
3324 {
3325         printf("failed to get info \n");
3326 }
3327
3328 printf("type:%d \n", method_info.type); // int, double
3329 printf("flag:%d \n", method_info.flag); // readable, writable..
3330 printf("validity type:%d \n", method_info.validity_type);//range, array..
3331
3332 if (method_info. validity_type == MM_PLAYER_ATTRS_VALID_TYPE_INT_RANGE)
3333 {
3334         printf("range min=%d\n", method_info.int_range.min );
3335         printf("range max=%\n", method_info.int_range.max );
3336 }
3337 @endcode
3338
3339 @}
3340 @defgroup Player_uc3 Unrealize and play next file
3341 @ingroup Player_UC
3342 @{
3343
3344 <h2 class="pg">Unrealize and play next file</h2>
3345                 - Player should be unrealized first in order to play another file.
3346                 - If player is unrealized, all the related variables and codecs are removed.
3347                 - So, it is necessary to set new attributes and reconstruct the player.
3348                 - The following is a sample code to play another mp3 file.
3349 @code
3350 void play_next_audio_file(char *next_filename)
3351 {
3352     if (mm_player_unrealize(g_player) != MM_ERROR_NONE)
3353     {
3354          printf("failed to unrealize\n");
3355          exit(1);
3356         }
3357
3358         if (mm_player_set_attribute(g_player,
3359                                         &g_err_attr_name,
3360                            "profile_uri", next_filename, strlen(filename),
3361                           NULL) != MM_ERROR_NONE)
3362         {
3363                 printf("failed to set %s attribute\n", g_err_attr_name);
3364                 free(g_err_attr_name);
3365         }
3366
3367         if (mm_player_realize(g_player) != MM_ERROR_NONE)
3368         {
3369                  printf("failed to destroy\n");
3370                  exit(1);
3371         }
3372
3373         if (mm_player_start(g_player) != MM_ERROR_NONE)
3374         {
3375                  printf("failed to destroy\n");
3376                  exit(1);
3377         }
3378 }
3379 @endcode
3380
3381
3382 @}
3383 @defgroup Player_uc4 Destroy player
3384 @ingroup Player_UC
3385 @{
3386
3387 <h2 class="pg">Destroy player</h2>
3388
3389                 - The created player should be destroyed when application is closed.
3390                 - So, if mm_player_destroy() is called, all allocated resources and the player handle are released.
3391 @}
3392 @defgroup Player_uc5 Play and end of playback
3393 @ingroup Player_UC
3394 @{
3395
3396 <h2 class="pg">Play and end of playback</h2>
3397
3398                 - Applications can play music or video using the mm_player_start() function when player is in the ready state. After starting, the appropriate codecs will be generated internally to play it.
3399                 - The result of the start function is returned asynchronously through the message callback which was previously registered.
3400                 - Playback is confirmed to the application with the MM_BEGIN_OF_STREAM(BOS) message.
3401                 - The MM_MESSAGE_END_OF_STREAM(EOS) is sent at the end of contents playback.
3402 @}
3403 @defgroup Player_uc6 Pause and resume
3404 @ingroup Player_UC
3405 @{
3406
3407 <h2 class="pg">Pause and resume</h2>
3408
3409                 - Player can be paused during playing video or audio contents. It can also be resumed again.
3410                 - The result of the pause or resume functions are returned asynchronously. So the result is confirmed to the application by the MM_MESSAGE_STATE_CHANGED message in the message callback.
3411                 - Both apis may be used synchronously in the case of local playback.
3412                 - The following is a sample code for when the player is paused and the result is checked for streaming data.
3413
3414 @code
3415 void pause_video_player()
3416 {
3417         if (mm_player_pause(g_player) != MM_ERROR_NONE)
3418         {
3419                 printf("failed to pause\n");
3420         }
3421 }
3422
3423 int msg_callback(int message, MMMessageParamType *param, void *user_param)
3424 {
3425         switch (message)
3426         {
3427              case MM_MESSAGE_ERROR:
3428                  // Do something
3429                  break;
3430
3431                 case MM_MESSAGE_STATE_CHANGED:
3432                         if (param->state.current == MM_PLAYER_STATE_PAUSED)
3433                          printf("player is paused. So, application can resume it again.\n");
3434                         break;
3435
3436                 default:
3437                         return FALSE;
3438         }
3439         return TRUE;
3440 }
3441 @endcode
3442 @}
3443 @defgroup Player_uc7 Change the volume during playback
3444 @ingroup Player_UC
3445 @{
3446
3447 <h3 class="pg">Change the volume during playback</h3>
3448
3449                 - The range of volume level is from 0 to 9. Each macro is MM_VOLUME_LEVEL_MIN and MM_VOLUME_LEVEL_MAX. The default volume level is 7.
3450                 - Volume can be controlled during playback but, if volume is set before playing, it can be saved and applied at running time.
3451                 - The following is a sample code to set MM_VOLUME_LEVEL_MAX volume and get it.
3452
3453 @code
3454 int change_video_player_volume()
3455 {
3456         MMPlayerVolumeType volume;
3457         int i = 0;
3458
3459         for (i = 0; i < MM_VOLUME_CHANNEL_NUM; i++)
3460                 volume.level[i] = MM_VOLUME_LEVEL_MAX;
3461
3462     if (mm_player_set_volume(g_player, &volume) != MM_ERROR_NONE)
3463     {
3464         printf("failed to set volume\n");
3465         return FALSE;
3466         }
3467
3468         if (mm_player_get_volume(g_player, format, &pos) != MM_ERROR_NONE)
3469         {
3470                 printf("failed to get volume\n");
3471                 return FALSE;
3472         }
3473
3474         for (i = 0; i < MM_VOLUME_CHANNEL_NUM; i++)
3475                 printf("channel[%d] = %d \n", i, volume.level[i]);
3476 }
3477 @endcode
3478 @}
3479 @defgroup Player_uc8  Seeking position
3480 @ingroup Player_UC
3481 @{
3482
3483 <h3 class="pg">Seeking position</h3>
3484
3485                 - Player supports time and percent format to get or set position of stream.
3486                 - The position unit is in milliseconds.
3487                 - The following is a sample code to get and set the player position.
3488
3489 @code
3490 gboolean change_video_player_position()
3491 {
3492         int format = MM_PLAYER_POS_FORMAT_TIME;
3493         int pos = 15000; // 15sec
3494
3495         if (mm_player_set_position(g_player, format, pos) != MM_ERROR_NONE)
3496         {
3497             return FALSE;
3498         }
3499
3500         if (mm_player_get_position(g_player, format, &pos) != MM_ERROR_NONE)
3501         {
3502                 return FALSE;
3503         }
3504         printf("current pos = %d (msec)\n", pos);
3505
3506         return TRUE;
3507 }
3508 @endcode
3509
3510 @}
3511 @defgroup Player_uc9 Show subtitle
3512 @ingroup Player_UC
3513 @{
3514
3515 <h3 class="pg">Show subtitle</h3>
3516
3517                 - Player framework can support a separate subtitle file. The filepath of subtitle should be sent through mm_player_set_attribute() before realizing the player.
3518
3519 @code
3520
3521 if (mm_player_set_attribute(g_player,
3522                                                         &g_err_name,
3523                                                         "subtitle_uri",subtitle_path,strlen(subtitle_path),
3524                                                         NULL) != MM_ERROR_NONE)
3525 {
3526          printf("failed to set %s\n", *g_err_name);
3527          free(g_err_name);
3528 }
3529 @endcode
3530
3531                 - Application shall select the option of whether to show the subtitle or not.
3532
3533 @code
3534 if (mm_player_set_subtitle_silent(g_player, TRUE) != MM_ERROR_NONE)
3535      printf("failed to set subtitle silent\n");
3536 @endcode
3537
3538
3539                 - Finally, application should get the parsed text data from message of callback function.
3540
3541
3542 @code
3543 void video_player_message_callback(int message, void *param, void *user_param)
3544 {
3545      struct appdata *ad = (struct appdata *)user_param;
3546      MMMessageParamType* msg_param = (MMMessageParamType*)param;
3547
3548      switch(message)
3549         {
3550                 case MM_MESSAGE_SUBTITLE:
3551                         if (msg_param->data != NULL)
3552                         {
3553                                 ad->subtitle_duration = msg_param->subtitle.duration/1000;
3554                                 strcpy(ad->subtitle, msg_param->data);
3555                                 show_video_player_subtitle(ad);
3556                         }
3557                         break;
3558
3559
3560         default:
3561                 break;
3562
3563         }
3564 }
3565 @endcode
3566
3567 @}
3568 @defgroup MMsession Multimedia session
3569 @ingroup MultiMediaPG
3570 @{
3571         @brief <sub class="ref">Also see</sub> Use Cases of @ref MMsession_UC
3572
3573 <h2 class="pg">Multimedia session</h2>
3574
3575 Role of Multimedia Session is to manage "operation policy" between multimedia applications in multi-tasking scenario
3576
3577 Multimedia Session provides functions to determine type of application's policy.
3578
3579 Application developer can define applications' session type as "shared", "exclusive" or "replace".
3580
3581 "Shared" type means the audio session is shared with other applications, if possible. The audio resources can be used by other applications.
3582
3583 "Exclusive" type means using the audio session exclusively. Other applications are not allowed to use multimedia resources during this time.
3584
3585 "Replace" type means this will make stop previous session but allows sharing session with following application.
3586
3587
3588 The following are supported functions :
3589
3590                 - int mm_session_init(int sessiontype)
3591
3592                 - int mm_session_finish(void)
3593
3594 @}
3595 @defgroup MMsession_uc1 Initializing Session
3596 @ingroup MMsession_UC
3597 @{
3598
3599
3600 Initializing Session
3601
3602                 - To define current application's multimedia session policy.
3603
3604                 - Policy can be one of SHARE, EXCLUSIVE or REPLACE.
3605
3606                 - The following is a sample code
3607
3608
3609 @code
3610 int err;
3611
3612
3613
3614 // Init session policy to MEDIA
3615
3616 err = mm_session_init (MM_SESSION_TYPE_MEDIA);
3617
3618
3619
3620 if (err != MM_ERROR_NONE)
3621
3622     return;
3623
3624
3625
3626 // Multimedia API manipulation (player, camcorder, etc.)
3627 @endcode
3628
3629 @}
3630 @defgroup MMsession_uc2 Finisihing Session
3631 @ingroup MMsession_UC
3632 @{
3633
3634 Finisihing Session
3635
3636                 - To finish current application's multimedia session policy
3637
3638                 - This API is not mandatory except internal call application.
3639
3640                 - This API can be also useful when application's multimedia session should be changed at runtime.
3641
3642                 - The following is a sample code
3643
3644 @code
3645 int err;
3646
3647
3648
3649 // Init session policy to MEDIA
3650
3651 err = mm_session_init (MM_SESSION_TYPE_MEDIA);
3652
3653
3654
3655 if (err != MM_ERROR_NONE)
3656
3657     return;
3658
3659
3660
3661 // Do something
3662
3663
3664
3665 // Change policy to EXCLUSIVE
3666
3667 err = mm_session_finish();
3668
3669
3670
3671 // Init session policy to EXCLUSIVE
3672
3673 err = mm_session_init (MM_SESSION_TYPE_EXCLUSIVE);
3674
3675
3676
3677 // Do something else
3678 @endcode
3679
3680 @}
3681 @defgroup MM_Fileinfo Fileinfo
3682 @ingroup MultiMediaPG
3683 @{
3684 <h2 class="pg">Fileinfo</h2>
3685         @brief <sub class="ref">Also see</sub> Use Cases of @ref Fileinfo_UC
3686
3687 Fileinfo module provides APIs to extract media property information and meta data from media content. These values can be used to display detailed information of the media content without playing it.
3688
3689
3690
3691 For convenience, the file module provides an additional two APIs (mm_file_get_content_attr_from_memory, mm_file_get_tag_attr_from_memory) which manipulate the source data from memory instead of the file. They act the same as normal APIs (mm_file_get_content_attr, mm_file_get_tag_attr).
3692
3693
3694
3695 For performance, the file module provides an additional two APIs (mm_file_get_stream_info, mm_file_get_content_attr_simple) which extract the audio/video track count without time consuming operations.
3696
3697
3698
3699 The following are supported functions
3700                 - int mm_file_get_content_attr (MMHandleType *attrs, const char *filename)
3701
3702                 - int mm_file_get_content_attr_from_memory (MMHandleType *attrs, const void *data, unsigned int size, int format)
3703
3704                 - int mm_file_get_content_attr_simple (MMHandleType *attrs, const char *filename)
3705
3706                 - int mm_file_free_content_attr (MMHandleType attrs)
3707
3708                 - int mm_file_get_tag_attr ((MMHandleType *attrs, const char *filename)
3709
3710                 - int mm_file_get_tag_attr_from_memory ((MMHandleType *attrs, const void *data, unsigned int size, int format)
3711
3712                 - int mm_file_free_tag_attr ((MMHandleType attrs)
3713
3714                 - int mm_file_get_stream_info (const char *filename, int *audio_stream_num, int *video_stream_num)
3715
3716
3717
3718 @}
3719 @defgroup Fileinfo_uc1 Extracting Media Property Information
3720 @ingroup Fileinfo_UC
3721 @{
3722
3723 <h3 class="pg">Extracting Media Property Information </h3>
3724
3725 Media property information can be extracted using the following steps:
3726
3727                 - Get attributes handle containing media information using mm_file_get_content_attr API
3728
3729                 - Use attributes functions with handle to get value
3730
3731                 - Free allocated media information using mm_file_free_content_attr API
3732
3733
3734
3735 The following is a sample code
3736
3737 @code
3738 MMHandleType attrs;
3739
3740 int err;
3741
3742
3743
3744 err = mm_file_get_content_attr(&attrs, filename);
3745
3746 if (err != MM_ERROR_NONE)
3747
3748 {
3749
3750       printf("error occurred to extract media information\n");
3751
3752       exit(1);
3753
3754 }
3755
3756
3757
3758 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_DURATION, &val);
3759
3760 if (err == MM_ERROR_NONE)
3761
3762       printf("duration: %d\n", val);
3763
3764
3765
3766 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_VIDEO_CODEC, &val);
3767
3768 if (err == MM_ERROR_NONE)
3769
3770       printf("video codec id: %d\n", val);
3771
3772
3773
3774 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_VIDEO_BITRATE, &val);
3775
3776 if (err == MM_ERROR_NONE)
3777
3778       printf("video bitrate: %d\n", val);
3779
3780
3781
3782 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_VIDEO_FPS, &val);
3783
3784 if (err == MM_ERROR_NONE)
3785
3786       printf("fps: %d\n", val);
3787
3788
3789
3790 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_VIDEO_WIDTH, &val);
3791
3792 if (err == MM_ERROR_NONE)
3793
3794       printf("width: %d\n", val);
3795
3796
3797
3798 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_VIDEO_HEIGHT, &val);
3799
3800 if (err == MM_ERROR_NONE)
3801
3802       printf("height: %d\n", val);
3803
3804
3805
3806 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_VIDEO_THUMBNAIL, &data, &size);
3807
3808 if (err == MM_ERROR_NONE)
3809
3810       printf("thumbnail: %p, %d bytes\n", data, size);
3811
3812
3813
3814 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_VIDEO_TRACK_ID, &val);
3815
3816 if (err == MM_ERROR_NONE)
3817
3818       printf("video track id: %d\n", val);
3819
3820
3821
3822 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_VIDEO_TRACK_NUM, &val);
3823
3824 if (err == MM_ERROR_NONE)
3825
3826       printf("video tracks: %d\n", val);
3827
3828
3829
3830 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_AUDIO_CODEC, &val);
3831
3832 if (err == MM_ERROR_NONE)
3833
3834       printf("audio codec id: %d\n", val);
3835
3836
3837
3838 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_AUDIO_BITRATE, &val);
3839
3840 if (err == MM_ERROR_NONE)
3841
3842       printf("audio bitrate: %d\n", val);
3843
3844
3845
3846 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_AUDIO_CHANNELS, &val);
3847
3848 if (err == MM_ERROR_NONE)
3849
3850       printf("channels: %d\n", val);
3851
3852
3853
3854 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_AUDIO_SAMPLERATE, &val);
3855
3856 if (err == MM_ERROR_NONE)
3857
3858       printf("sampling rate: %d\n", val);
3859
3860
3861
3862 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_AUDIO_TRACK_ID, &val);
3863
3864 if (err == MM_ERROR_NONE)
3865
3866       printf("audio track id: %d\n", val);
3867
3868
3869
3870 err = mm_attrs_get_int(attrs, MM_FILE_CONTENT_AUDIO_TRACK_NUM,   &val);
3871
3872 if (err == MM_ERROR_NONE)
3873
3874       printf("audio tracks: %d\n", val);
3875
3876
3877
3878 err = mm_file_free_content_attr (attr);
3879 @endcode
3880 @}
3881 @defgroup Fileinfo_uc2 Extracting Media Meta(Tag) data
3882 @ingroup Fileinfo_UC
3883 @{
3884
3885 <h3 class="pg">Extracting Media Meta(Tag) data</h3>
3886
3887 Media meta data can be extracted using the following steps:
3888
3889                 - Get attributes handle containing meta data using mm_file_get_tag_attr API
3890
3891                 - Use attributes functions with handle to get value
3892
3893                 - Free allocated meta data using mm_file_free_tag_attr API
3894
3895
3896
3897 The following is a sample code
3898 @code
3899 MMHandleType attrs;
3900
3901 int err, val, size;
3902
3903 char *str;
3904
3905 void *data;
3906
3907 double fval;
3908
3909
3910
3911 err = mm_file_get_tag_attr (&attrs, filename);
3912
3913 if (err != MM_ERROR_NONE)
3914
3915 {
3916
3917       printf("error occurred to extract meta data\n");
3918
3919       exit(1);
3920
3921 }
3922
3923
3924
3925 err = mm_attrs_get_string(attrs, MM_FILE_TAG_ARTIST, &str, &size);
3926
3927 if (err == MM_ERROR_NONE && str)
3928
3929       printf("artist: %s\n", str);
3930
3931
3932
3933 err = mm_attrs_get_string(attrs, MM_FILE_TAG_TITLE, &str, &size);
3934
3935 if (err == MM_ERROR_NONE && str)
3936
3937       printf("title: %s\n", str);
3938
3939
3940
3941 err = mm_attrs_get_string(attrs, MM_FILE_TAG_ALBUM, &str, &size);
3942
3943 if (err == MM_ERROR_NONE && str)
3944
3945       printf("album: %s\n", str);
3946
3947
3948
3949 err = mm_attrs_get_string(attrs, MM_FILE_TAG_COPYRIGHT, &str, &size);
3950
3951 if (err == MM_ERROR_NONE && str)
3952
3953       printf("copyright: %s\n", str);
3954
3955
3956
3957 err = mm_attrs_get_string(attrs, MM_FILE_TAG_DATE, &str, &size);
3958
3959 if (err == MM_ERROR_NONE && str)
3960
3961       printf("date: %s\n", str);
3962
3963
3964
3965 err = mm_attrs_get_string(attrs, MM_FILE_TAG_DESCRIPTION, &str, &size);
3966
3967 if (err == MM_ERROR_NONE && str)
3968
3969       printf("description: %s\n", str);
3970
3971
3972
3973 err = mm_attrs_get_data(attrs, MM_FILE_TAG_ARTWORK, &data, &size);
3974
3975 err |= mm_attrs_get_int(attrs, MM_FILE_TAG_ARTWORK_SIZE, &size);
3976
3977 if (err == MM_ERROR_NONE && data && size > 0)
3978
3979       printf("artwork: %p, %d\n", data, size);
3980
3981
3982
3983 err = mm_attrs_get_string(attrs, MM_FILE_TAG_TRACK_NUM, &str, &size);
3984
3985 if (err == MM_ERROR_NONE && str)
3986
3987       printf("track: %s\n", str);
3988
3989
3990
3991 err = mm_attrs_get_string(attrs, MM_FILE_TAG_CLASSIFICATION, &str, &size);
3992
3993 if (err == MM_ERROR_NONE && str)
3994
3995       printf("classification: %s\n", str);
3996
3997
3998
3999 err = mm_attrs_get_string(attrs, MM_FILE_TAG_RATING, &str, &size);
4000
4001 if (err == MM_ERROR_NONE && str)
4002
4003       printf("rating: %s\n", str);
4004
4005
4006
4007 err = mm_attrs_get_double(attrs, MM_FILE_TAG_LONGITUDE, &fval);
4008
4009 if (err == MM_ERROR_NONE)
4010
4011       printf("longitude: %4.4f\n", fval);
4012
4013
4014
4015 err = mm_attrs_get_double(attrs, MM_FILE_TAG_LATIDUE, &fval);
4016
4017 if (err == MM_ERROR_NONE)
4018
4019       printf("latidue: %4.4f\n", fval);
4020
4021
4022
4023 err = mm_attrs_get_double(attrs, MM_FILE_TAG_ALTIDUE, &fval);
4024
4025 if (err == MM_ERROR_NONE)
4026
4027       printf("altidue: %4.4f\n", fval);
4028
4029
4030
4031 err = mm_file_free_tag_attr (attr);
4032 @endcode
4033
4034 @}
4035 @defgroup Fileinfo_uc3 Extracting Stream information
4036 @ingroup Fileinfo_UC
4037 @{
4038
4039 <h3 class="pg">Extracting Stream information</h3>
4040
4041 Number of streams can be extracted using the following steps:
4042
4043                 - Get the number of streams using mm_file_get_stream_info API
4044
4045                 - Detect as video file if number of video streams is more than one.
4046
4047
4048
4049 The following is a sample code
4050
4051 @code
4052 int err;
4053
4054 int audio_num;
4055
4056 int video_num;
4057
4058
4059
4060 err = mm_file_get_stream_info (filename, &audio_num, &video_num);
4061
4062 if (err != MM_ERROR_NONE)
4063
4064 {
4065
4066       printf("error occurred to extract stream information\n");
4067
4068       exit(1);
4069
4070 }
4071
4072
4073
4074 printf("content has %d audio streams\n", audio_num);
4075
4076 printf("content has %d video streams\n", video_num);
4077 @endcode
4078 @}
4079 @defgroup MM_Sound Sound
4080 @ingroup MultiMediaPG
4081 @{
4082
4083 <h2 class="pg">Sound</h2>
4084         @brief <sub class="ref">Also see</sub> Use Cases of @ref Sound_UC
4085
4086 The Sound module has the following features:
4087
4088 Play or capture PCM data with given memory buffer
4089
4090 Play audio  file with simple API ( uncompressed WAV file only)
4091
4092 Control volume and audio routing information
4093
4094 The following are supported functions :
4095
4096         - int   mm_sound_pcm_capture_close (MMSoundPcmHandle_t handle)
4097
4098         - int   mm_sound_pcm_capture_open (MMSoundPcmHandle_t *handle, const unsigned int rate, MMSoundPcmChannel_t channel, MMSoundPcmFormat_t format)
4099
4100         - int   mm_sound_pcm_capture_read (MMSoundPcmHandle_t handle, void *buffer, const unsigned int length)
4101
4102         - int   mm_sound_pcm_play_close (MMSoundPcmHandle_t handle)
4103
4104         - int   mm_sound_pcm_play_open (MMSoundPcmHandle_t *handle, const unsigned int rate, MMSoundPcmChannel_t channel, MMSoundPcmFormat_t format, const volume_type_t volume)
4105
4106         - int   mm_sound_pcm_play_write (MMSoundPcmHandle_t handle, void *ptr, unsigned int length_byte)
4107
4108         - int   mm_sound_play_dtmf (MMSoundDtmf_t num, const volume_type_t vol_type, const sound_time_msec_t time)
4109
4110         - int   mm_sound_play_sound (const char *filename, const volume_type_t volume, mm_sound_stop_callback_func callback, void *data, int *handle)
4111
4112         - int   mm_sound_stop_sound (int handle)
4113
4114         - int   mm_sound_volume_add_callback (volume_type_t type, volume_callback_fn func, void *user_data)
4115
4116         - int   mm_sound_volume_get_current_playing_type (volume_type_t *type)
4117
4118         - int   mm_sound_volume_get_step (volume_type_t type, int *step)
4119
4120         - int   mm_sound_volume_get_value (volume_type_t type, unsigned int *value)
4121
4122         - int   mm_sound_volume_primary_type_clear ()
4123
4124         - int   mm_sound_volume_primary_type_set (volume_type_t type)
4125
4126         - int   mm_sound_volume_remove_callback (volume_type_t type)
4127
4128         - int   mm_sound_volume_set_value (volume_type_t type, const unsigned int value)
4129
4130         - int   mm_sound_route_add_change_callback (audio_route_policy_changed_callback_fn func, void *user_data)
4131
4132         - int   mm_sound_route_get_system_policy (system_audio_route_t *route)
4133
4134         - int   mm_sound_route_is_a2dp_on (char **bt_name)
4135
4136         - int   mm_sound_route_remove_change_callback (void)
4137
4138         - int   mm_sound_route_set_system_policy (system_audio_route_t route)
4139
4140 @}
4141 @defgroup Sound_uc1 Capture PCM data
4142 @ingroup Sound_UC
4143 @{
4144
4145 <h3 class="pg">Capture PCM data</h3>
4146
4147         - Application can capture PCM data
4148
4149         - The following is a sample code
4150
4151
4152 @code
4153
4154 bool g_stop_pcm_capturing = FALSE;
4155 int capture_pcm_data()
4156 {
4157         char *buffer = NULL;
4158         int ret = 0;
4159         int size = 0;
4160         int count = 0;
4161         MMSoundPcmHandle_t handle;
4162
4163         size = mm_sound_pcm_capture_open(&handle, 44100, MMSOUND_PCM_MONO, MMSOUND_PCM_S16_LE);
4164         if(size < 0)
4165         {
4166                 printf("Can not open capture handle\n");
4167                 return -2;
4168         }
4169
4170         buffer = alloca(size);
4171         while(1)
4172         {
4173                 ret = mm_sound_pcm_capture_read(handle, (void*)buffer, size);
4174                 if(ret < 0)
4175                 {
4176                         printf("read fail\n");
4177                         break;
4178                 }
4179                 if( g_stop_pcm_capturing ) {
4180                         break;
4181                 }
4182         }
4183         mm_sound_pcm_capture_close(handle);
4184
4185         return TRUE;
4186 }
4187
4188 @endcode
4189
4190
4191 @}
4192 @defgroup Sound_uc2 Play sound file
4193 @ingroup Sound_UC
4194 @{
4195
4196 <h3 class="pg">Play sound file</h3>
4197
4198         - Start playing sound file
4199         - Stop playing sound file
4200         - Uncompressed WAV file only
4201
4202 @code
4203
4204
4205 void sound_stop_cb(void* data)
4206 {
4207         struct appdata* ad = (appdata*) data;
4208         printf("Stop callback\n");
4209         ad->snd_handle = -1;
4210 }
4211
4212 int play_file(void* data)
4213 {
4214         struct appdata* ad = (struct appdata*) data;
4215         char filename[] ="/opt/media/Sound/testfile.wav";
4216         volume_type_t volume = VOLUME_TYPE_SYSTEM;
4217         int ret = 0;
4218         int *snd_handle = NULL;
4219
4220         snd_handle = &ad->snd_handle;
4221
4222         ret = mm_sound_play_sound(filename, volume, sound_stop_cb, (void*)ad, snd_handle);
4223         if(ret < 0)
4224         {
4225                 printf("play file failed\n");
4226                 return -1;
4227         }
4228         else
4229         {
4230                 printf("play file success\n");
4231                 return 0;
4232         }
4233 }
4234
4235
4236 int stop_file(void* data)
4237 {
4238         int ret = 0;
4239         struct appdata* ad = (struct appdata*) data;
4240
4241         if(ad->snd_handle != -1)
4242         {
4243                 ret = mm_sound_stop_sound(ad->snd_handle);
4244                 if(ret < 0)
4245                 {
4246                         printf("Stop sound failed\n");
4247                         return -1;
4248                 }
4249                 else
4250                 {
4251                         printf("Stop sound success\n");
4252                         return -1;
4253                 }
4254         }
4255 }
4256 @endcode
4257 @}
4258 @defgroup Sound_uc3 Control Volume
4259 @ingroup Sound_UC
4260 @{
4261
4262
4263 <h3 class="pg">Control Volume</h3>
4264
4265 Basically volume of SLP system is controlled by System process.
4266 But in some case, application should control volume by itself.
4267         - If application does not want to be hidden by System Volume UI.
4268         - If application want to use Volume H/W key for special purpose.
4269
4270 Sample code to control Media type volume
4271
4272
4273 @code
4274
4275 Eina_Bool volume_key_cb(void *data, int type, void *event_info)
4276 {
4277                 struct appdata* ad = (struct appdata*)data;
4278                 Ecore_Event_Key *kd = (Ecore_Event_Key*) event_info;
4279                 int cur_vol = 0;
4280                 int ret = 0;
4281
4282                 if(0 == strcmp(kd->keyname, KEY_VOLUMEUP))
4283                 {
4284                         ret = mm_sound_volume_get_value(ad->vol_type, &cur_vol);
4285                         if(ret < 0)
4286                         {
4287                                 printf("Can not get volume value\n");
4288                         }
4289                         else
4290                         {
4291                                 if(cur_vol == ad->max_vol)
4292                                 {
4293                                         printf("Skip\n");
4294                                 }
4295                                 else
4296                                 {
4297                                         ret = mm_sound_volume_set_value(ad->vol_type, ++cur_vol);
4298                                         if(ret < 0)
4299                                         {
4300                                                 printf("Can not set volume value\n");
4301                                         }
4302                                 }
4303                         }
4304                 }
4305                 else if(0 == strcmp(kd->keyname, KEY_VOLUMEDOWN))
4306                 {
4307                         ret = mm_sound_volume_get_value(ad->vol_type, &cur_vol);
4308                         if(ret < 0)
4309                         {
4310                                 printf("Can not get volume value\n");
4311                         }
4312                         else
4313                         {
4314                                 if(0 == ad->max_vol)
4315                                 {
4316                                         printf("Skip\n");
4317                                 }
4318                                 else
4319                                 {
4320                                         ret = mm_sound_volume_set_value(ad->vol_type, --cur_vol);
4321                                         if(ret < 0)
4322                                         {
4323                                                 printf("Can not set volume value\n");
4324                                         }
4325                                 }
4326                         }
4327                 }
4328                 else
4329                 {
4330                         printf("Skip\n");
4331                 }
4332                 return EINA_FALSE;
4333 }
4334
4335 int do_key_grab(void* data)
4336 {
4337                 struct appdata* ad = (struct appdata*)data;
4338                 int ret = 0;
4339                 int vol_max = 0;
4340
4341                 // grab key and add event handler
4342                 if( utilx_grab_key(ad->disp, ad->win, KEY_VOLUMEUP, TOP_POSITION_GRAB) < 0)
4343                 {
4344                         printf("grab Volume up key fail\n");
4345                         return -1;
4346                 }
4347                 if( utilx_grab_key(ad->disp, ad->win, KEY_VOLUMEDOWN, TOP_POSITION_GRAB) < 0)
4348                 {
4349                         printf("grab Volume down key fail\n");
4350                         return -1;
4351                 }
4352
4353                 ad->key_down = ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, volume_key_cb, ad);
4354
4355                 //get max volume of type
4356                 ad->vol_type = VOLUME_TYPE_MEDIA;
4357                 ret = mm_sound_volume_get_step(ad->vol_type, &vol_max);
4358                 if(ret < 0)
4359                 {
4360                         printf("Volume get step fail\n");
4361                         return -1;
4362                 }
4363
4364                 ad->vol_max = vol_max;
4365
4366                 return 0;
4367 }
4368
4369 @endcode
4370
4371 @}
4372 @defgroup MM_OpenAL OpenAL
4373 @ingroup MultiMediaPG
4374 @{
4375
4376
4377 <h2 class="pg">OpenAL</h2>
4378
4379 OpenAL is a cross-platform 3D audio API appropriate for use with gaming applications and many other types of audio applications. OpenAL in SLP only supports playback fucntion.
4380
4381
4382
4383 OpenAL is opensource and if you need further information, see official website : http://connect.creativelabs.com/openal/default.aspx
4384
4385
4386 Specification and Reference
4387
4388                 - http://connect.creativelabs.com/openal/Documentation/Forms/AllItems.aspx
4389
4390 @}
4391 @defgroup MM_Radio Radio
4392 @ingroup MultiMediaPG
4393 @{
4394
4395 <h2 class="pg">Radio</h2>
4396         @brief <sub class="ref">Also see</sub> Use Cases of @ref Radio_UC
4397
4398 This section describes APIs of the Multimedia FM radio library. Radio library is used for listening to FM radio, scanning all possible frequencies and seeking one frequency from current state, controling relative volume and frequency.
4399
4400
4401
4402 Radio can have 5 states, and each state can be changed by calling the following functions as described.
4403
4404         <table>
4405
4406                 <tr>
4407                                 <td>
4408 <b>FUNCTION</b>
4409                                 <td>
4410 <b>PRE-STATE</b>
4411                                 <td>
4412 <b>POST-STATE</b>
4413                                 <td>
4414 <b>SYNC TYPE</b>
4415                 <tr>
4416                                 <td>
4417 mm_radio_create()                               <td>
4418 NONE                            <td>
4419 NULL                            <td>
4420 SYNC                    <tr>
4421                                 <td>
4422 mm_radio _destroy()                             <td>
4423 NULL                            <td>
4424 NONE                            <td>
4425 SYNC                    <tr>
4426                                 <td>
4427 mm_radio_realize()                              <td>
4428 NULL                            <td>
4429 READY                           <td>
4430 SYNC                    <tr>
4431                                 <td>
4432 mm_radio_unrealize()                            <td>
4433 READY                           <td>
4434 NULL                            <td>
4435 SYNC                    <tr>
4436                                 <td>
4437 mm_radio_start()                                <td>
4438 READY                           <td>
4439 PLAYING                         <td>
4440 SYNC                    <tr>
4441                                 <td>
4442 mm_radio_stop()                         <td>
4443 PLAYING                         <td>
4444 READY                           <td>
4445 SYNC                    <tr>
4446                                 <td>
4447 mm_radio_scan_start()                           <td>
4448 READY                           <td>
4449 SCANNING                                <td>
4450 ASYNC                   <tr>
4451                                 <td>
4452 mm_radio_scan_stop()                            <td>
4453 SCANNING                                <td>
4454 READY                           <td>
4455 ASYNC                   <tr>
4456                                 <td>
4457 Mm_radio_seek()                         <td>
4458 PLAYING                         <td>
4459 PLAYING                         <td>
4460 ASYNC
4461         </table>
4462
4463 @image html SLP_MultimediaFW_PG_image004.png
4464
4465 The following are supported functions in the radio module.
4466
4467                 - int mm_radio_get_state(MMHandleType hradio, MMRadioStateType *state)
4468
4469                 - int mm_radio_set_frequency(MMHandleType hradio, int freq)
4470
4471                 - int mm_radio_get_frequency(MMHandleType hradio, int *pFreq)
4472
4473                 - int mm_radio_set_sound_path(MMHandleType hradio, MMRadioOuputType path)
4474
4475                 - int mm_radio_get_sound_path (MMHandleType hrado, MMRadioOuputType *pPath)
4476
4477                 - int mm_radio_set_message_callback(MMHandleType radio, MMMessageCallback callback, void *user_param)
4478
4479 @}
4480 @defgroup Radio_uc1 Create and initialize radio
4481 @ingroup Radio_UC
4482 @{
4483
4484 <h3 class="pg">Create and initialize radio</h3>
4485
4486                 - Application can create the radio handle using mm_radio_create().
4487
4488                 - And, callback function must be set to get messages from radio engine using mm_radio_set_message_callback().
4489
4490                 - The followings messages are used.
4491         <table>
4492
4493                 <tr>
4494                                 <td> <b>MESSAGE TYPE</b>                        </td>
4495                                 <td> <b>DESCRIPTION</b>                         </td>
4496                 <tr>
4497                                 <td> MM_MESSAGE_RADIO_SCAN_START
4498                                 <td> Radio frequency scanning initiated
4499                 <tr>
4500                                 <td> MM_MESSAGE_RADIO_SCAN_INFO
4501                                 <td> Founded radio frequency report. check message parameters
4502                 <tr>
4503                                 <td> MM_MESSAGE_RADIO_SCAN_FINISH
4504                                 <td> Radio frequency scanning has finished
4505                 <tr>
4506                                 <td> MM_MESSAGE_RADIO_SCAN_STOP
4507                                 <td> Radio frequency scanning has stopped
4508                 <tr>
4509                                 <td> MM_MESSAGE_RADIO_SEEK_START
4510                                 <td> Radio seeking has established
4511                 <tr>
4512                                 <td> MM_MESSAGE_RADIO_SEEK_FINISH
4513                                 <td> Radio seeking has finished
4514
4515         </table>
4516
4517
4518                 - The resources can be allocated by mm_radio_realize(). And, radio device is opened.
4519
4520 @code
4521 MMHandleType g_radio = 0;
4522
4523 static int __msg_callback(int message, void *pParam, void *user_param)
4524 {
4525       MMMessageParamType* param = (MMMessageParamType*)pParam;
4526       MMHandleType radio = (MMHandleType *) user_param;
4527
4528       int ret = 0;
4529
4530       printf("incomming message : %d\n", message);
4531
4532       switch(message)
4533       {
4534               case MM_MESSAGE_STATE_CHANGED:
4535                     printf("MM_MESSAGE_STATE_CHANGED: current : %d    old : %d\n"
4536                                 , param->state.current, param->state.previous);
4537                     break;
4538
4539               case MM_MESSAGE_RADIO_SCAN_START:
4540                     printf("MM_MESSAGE_RADIO_SCAN_START\n");
4541                     break;
4542
4543               case MM_MESSAGE_RADIO_SCAN_INFO:
4544                         printf("MM_MESSAGE_RADIO_SCAN_INFO : freq : %d\n", param->radio_scan.frequency);
4545                     break;
4546
4547               case MM_MESSAGE_RADIO_SCAN_STOP:
4548                     printf("MM_MESSAGE_RADIO_SCAN_STOP\n");
4549                     break;
4550
4551               case MM_MESSAGE_RADIO_SCAN_FINISH:
4552                     printf("MM_MESSAGE_RADIO_SCAN_FINISHED\n");
4553                     break;
4554
4555               case MM_MESSAGE_RADIO_SEEK_START:
4556                   printf("MM_MESSAGE_RADIO_SEEK_START\n");
4557                   break;
4558
4559               case MM_MESSAGE_RADIO_SEEK_FINISH:
4560                         printf("MM_MESSAGE_RADIO_SEEK_FINISHED : freq : %d\n", param->radio_scan.frequency);
4561                     break;
4562
4563               default:
4564                     printf("ERROR : unknown message received!\n");
4565                     break;
4566       }
4567       return true;
4568 }
4569
4570
4571
4572 int init_radio(void)
4573 {
4574       int ret = MM_ERROR_NONE;
4575
4576         mm_radio_create(&g_radio);
4577         mm_radio_set_message_callback( radio, (MMMessageCallback)__msg_callback,(void*) g_radio);
4578         mm_radio_realize(g_radio);
4579         mm_radio_unrealize(g_radio);
4580         mm_radio_destroy(g_radio);
4581
4582       return ret;
4583 }
4584 @endcode
4585 @}
4586 @defgroup Radio_uc2 Destroy and close
4587 @ingroup Radio_UC
4588 @{
4589
4590 <h3 class="pg">Destroy and close</h3>
4591
4592                 - The created radio should be destroyed when application is closed.
4593
4594                 - So, if mm_radio_unrealize() is called, radio device would be closed.
4595
4596                 - And, all allocated resources and the player handle are released by mm_radio_destroy().
4597
4598 @code
4599 gboolean release_radio(void)
4600 {
4601       if (mm_radio_unrealize(g_radio) != MM_ERROR_NONE)
4602         {
4603                 printf("failed to unrealize\n");
4604                 return FALSE;
4605         }
4606
4607         if (mm_radio_ destroy (g_radio) != MM_ERROR_NONE)
4608         {
4609               printf("failed to destroy\n");
4610               return FALSE;
4611         }
4612         return TRUE;
4613 }
4614 @endcode
4615
4616
4617
4618
4619 <b>Start and stop</b>
4620
4621                 - Application can start radio with mm_radio_start() and stop it with mm_radio_stop().
4622
4623                 - And, the frequency should be set before calling start.
4624
4625
4626 @code
4627 gboolean start_radio(void)
4628 {
4629         if (mm_radio_ set_frequency (g_radio, 1077) != MM_ERROR_NONE)
4630         {
4631                 printf("failed to set freq\n");
4632
4633               return FALSE;
4634         }
4635
4636       if (mm_radio_start(g_radio) != MM_ERROR_NONE)
4637         {
4638               printf("failed to start\n");
4639
4640               return FALSE;
4641         }
4642         return TRUE;
4643 }
4644
4645
4646
4647 gboolean stop_radio(void)
4648 {
4649       if (mm_radio_stop(g_radio) != MM_ERROR_NONE)
4650         {
4651                 printf("failed to stop\n");
4652
4653               return FALSE;
4654         }
4655         return TRUE;
4656 }
4657 @endcode
4658 @}
4659 @defgroup Radio_uc3 Seek frequency
4660 @ingroup Radio_UC
4661 @{
4662
4663 <h3 class="pg">Seek frequency</h3>
4664
4665                 - Application can seek the effective frequency of radio in playing state by mm_radio_seek().
4666
4667                 - After calling it, application have to check the state with MM_MESSAGE_RADIO_SEEK_START and MM_MESSAGE_RADIO_SEEK_FINISH which are sent through message callback.
4668
4669                 - And, if seek is finished, the frequency is sent through message parameter of callback function when MM_MESSAGE_RADIO_SEEK_FINISH is posted.
4670
4671
4672 @code
4673 gboolean seek_radio_frequency(void)
4674 {
4675       if (mm_radio_seek (g_radio) != MM_ERROR_NONE)
4676         {
4677                 printf("failed to seek\n");
4678
4679               return FALSE;
4680         }
4681         return TRUE;
4682 }
4683 @endcode
4684 @}
4685 @defgroup Radio_uc4 Scan frequencies
4686 @ingroup Radio_UC
4687 @{
4688
4689 <h3 class="pg">Scan frequencies</h3>
4690
4691                 - Application can scan the effective frequency of radio in playing state by mm_radio_scan_start().
4692
4693                 - After calling it, application have to check the state with MM_MESSAGE_RADIO_SCAN_START , MM_MESSAGE_RADIO_SCAN_INFO, MM_MESSAGE_RADIO_SCAN_FINISH which are sent through message callback.
4694
4695                 - And, if frequency is found, it's sent through message parameter of callback function when . MM_MESSAGE_RADIO_SCAN_INFO is posted.
4696
4697                 - Finally, scanning can be stopped by mm_radio_scan_stop().  So, MM_MESSAGE_RADIO_SCAN_STOP will be sent.
4698
4699
4700
4701
4702
4703
4704 @}
4705 @defgroup Radio_uc5 Set/Get sound path
4706 @ingroup Radio_UC
4707 @{
4708
4709
4710 <h3 class="pg">Set/Get sound path</h3>
4711
4712                 - Applications can set/get sound path by mm_radio_set_sound_path() and mm_radio_get_sound_path().
4713
4714                 - The sound path type is followings .
4715
4716
4717         <table>
4718                 <tr>                    <td>SOUND PATH TYPE                     </td>                   <td>DESCRIPTION                         </td>           </tr>
4719                 <tr>                    <td>MM_RADIO_OUTPUT_AUTO                        </td>                   <td>Automatic output mode, but not used yet                     </td>           </tr>
4720                 <tr>                    <td>MM_RADIO_OUTPUT_SPEAKER                     </td>                   <td>                    </td>           </tr>
4721                 <tr>                    <td>                    </td>                   <td>                    </td>           </tr>
4722         </table>
4723
4724 @}
4725 */
4726 /**
4727  * @defgroup  MultiMediaPG MultiMedia Camcorder,Player,Sound and Radio
4728    @{
4729    *   @defgroup
4730    *   @defgroup MM_UC Use Cases
4731        @{
4732  *   @defgroup Camcorder_UC Camcorder
4733  *   @defgroup Player_UC Player
4734  *   @defgroup Sound_UC Sound
4735  *   @defgroup MMsession_UC  Multimedia session
4736         @brief <sub class="ref">Also see</sub> Feature description of  @ref MMsession
4737  *   @defgroup  Fileinfo_UC Fileinfo
4738         @brief <sub class="ref">Also see</sub> Feature description of  @ref Fileinfo
4739  *   @defgroup Radio_UC Radio
4740         @brief <sub class="ref">Also see</sub> Feature description of  @ref Radio
4741        @}
4742      @}
4743 */