sink/include/mm_wfd_sink.h

   1 /*
   2  * libmm-wfd
   3  *
   4  * Copyright (c) 2011 - 2013 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: JongHyuk Choi <jhchoi.choi@samsung.com>, ByungWook Jang <bw.jang@samsung.com>,
   7  * Maksym Ukhanov <m.ukhanov@samsung.com>, Hyunjun Ko <zzoon.ko@samsung.com>
   8  *
   9  * Licensed under the Apache License, Version 2.0 (the "License");
  10  * you may not use this file except in compliance with the License.
  11  * You may obtain a copy of the License at
  12  *
  13  * http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  * Unless required by applicable law or agreed to in writing, software
  16  * distributed under the License is distributed on an "AS IS" BASIS,
  17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  * See the License for the specific language governing permissions and
  19  * limitations under the License.
  20  *
  21  */
  22
  23 #ifndef _MM_WFD_SINK_H_
  24 #define _MM_WFD_SINK_H_
  25
  26 #include <string.h>
  27 #include <glib.h>
  28 #include <mm_message.h>
  29 #include <mm_error.h>
  30 #include <mm_types.h>
  31
  32 /**
  33  *  * Enumerations of wifi-display sink state.
  34  *   */
  35 typedef enum {
  36         MM_WFD_SINK_STATE_NONE,                         /**< wifi-display is not created */
  37         MM_WFD_SINK_STATE_NULL,                         /**< wifi-display is created */
  38         MM_WFD_SINK_STATE_PREPARED,                     /**< wifi-display is prepared */
  39         MM_WFD_SINK_STATE_CONNECTED,             /**< wifi-display is connected */
  40         MM_WFD_SINK_STATE_PLAYING,                      /**< wifi-display is now playing  */
  41         MM_WFD_SINK_STATE_PAUSED,                       /**< wifi-display is now paused  */
  42         MM_WFD_SINK_STATE_DISCONNECTED, /**< wifi-display is disconnected */
  43         MM_WFD_SINK_STATE_NUM,                          /**< Number of wifi-display states */
  44 } MMWFDSinkStateType;
  45
  46 typedef void(*MMWFDMessageCallback)(int error_type, MMWFDSinkStateType state_type, void *user_data);
  47
  48 /**
  49  * This function creates a wi-fi display sink object. \n
  50  * The attributes of wi-fi display sink are created to get/set some values with application. \n
  51  * And, mutex, gstreamer and other resources are initialized at this time. \n
  52  * If wi-fi display sink is created, he state will become MM_WFD_SINK_STATE_NULL.. \n
  53  *
  54  * @param       wfd_sink                [out]   Handle of wi-fi display sink
  55  *
  56  * @return      This function returns zero on success, or negative value with error code. \n
  57  *                      Please refer 'mm_error.h' to know it in detail.
  58  * @pre         None
  59  * @post                MM_WFD_SINK_STATE_NULL
  60  * @see         mm_wfd_sink_destroy
  61  * @remark      You can create multiple handles on a context at the same time. \n
  62  *                      However, wi-fi display sink cannot guarantee proper operation because of limitation of resources, \n
  63  *                      such as audio device or display device.
  64  *
  65  * @par Example
  66  * @code
  67 if (mm_wfd_sink_create(&g_wfd_sink) != MM_ERROR_NONE)
  68 {
  69         wfd_sink_error("failed to create wi-fi display sink\n");
  70 }
  71
  72 mm_wfd_sink_set_message_callback(g_wfd_sink, msg_callback, (void*)g_wfd_sink);
  73  * @endcode
  74  */
  75 int mm_wfd_sink_create(MMHandleType *wfd_sink);
  76
  77 /**
  78  * This function trys to make gstreamer pipeline. \n
  79  * If wi-fi display sink is realized, the state will become MM_WFD_SINK_STATE_READY.. \n
  80  *
  81  * @param       wfd_sink                [out]   Handle of wi-fi display sink
  82  *
  83  * @return      This function returns zero on success, or negative value with error code. \n
  84  *                      Please refer 'mm_error.h' to know it in detail.
  85  * @pre         MM_WFD_SINK_STATE_NULL
  86  * @post                MM_WFD_SINK_STATE_PREPARED
  87  * @see         mm_wfd_sink_unprepare
  88  * @remark      None
  89  * @par Example
  90  * @code
  91 if (mm_wfd_sink_prepare(&g_wfd_sink) != MM_ERROR_NONE)
  92 {
  93         wfd_sink_error("failed to realize wi-fi display sink\n");
  94 }
  95  * @endcode
  96  */
  97 int mm_wfd_sink_prepare(MMHandleType wfd_sink);
  98
  99 /**
 100  * This function connect wi-fi display source using uri. \n
 101  * audio type(AC3 AAC, LPCM) is decided at this time. \n
 102  *
 103  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 104  * @param       uri                     [in]    URI of wi-fi displaysource to be connected
 105  *
 106  * @return      This function returns zero on success, or negative value with error code.
 107  *
 108  * @pre         wi-fi display sink state should be MM_WFD_SINK_STATE_PREPARED
 109  * @post                wi-fi display sink state will be MM_WFD_SINK_STATE_CONNECTED with no preroll.
 110  * @remark      None
 111  * @par Example
 112  * @code
 113 if (mm_wfd_sink_connect(g_wfd_sink, g_uri) != MM_ERROR_NONE)
 114 {
 115         wfd_sink_error("failed to connect to wi-fi display source\n");
 116 }
 117  * @endcode
 118  */
 119 int mm_wfd_sink_connect(MMHandleType wfd_sink, const char *uri);
 120
 121 /**
 122  * This function is to start playing. \n
 123  * Data from wi-fi display source will be received. \n
 124  *
 125  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 126  *
 127  * @return      This function returns zero on success, or negative value with error code.
 128  * @remark
 129  *
 130  * @pre         wi-fi display sink state may be MM_WFD_SINK_STATE_CONNECTED.
 131  * @post                wi-fi display sink state will be MM_WFD_SINK_STATE_PLAYING.
 132  * @see         mm_wfd_sink_disconnect
 133  * @remark      None
 134  * @par Example
 135  * @code
 136 if (mm_wfd_sink_start(g_wfd_sink) != MM_ERROR_NONE)
 137 {
 138         wfd_sink_error("failed to start wi-fi display sink\n");
 139 }
 140  * @endcode
 141  */
 142 int mm_wfd_sink_start(MMHandleType wfd_sink);
 143
 144 /**
 145  * This function is to pause playing. \n
 146  * The wi-fi display sink pause the current stream being received form wi-fi display source. \n
 147  *
 148  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 149  *
 150  * @return      This function returns zero on success, or negative value with error code.
 151  * @remark
 152  *
 153  * @pre         wi-fi display sink state should be MM_WFD_SINK_STATE_PLAYING.
 154  * @post                wi-fi display sink state will be MM_WFD_SINK_STATE_PAUSED.
 155  * @see         mm_wfd_sink_pause
 156  * @remark      None
 157  * @par Example
 158  * @code
 159 if (mm_wfd_sink_pause(g_wfd_sink) != MM_ERROR_NONE)
 160 {
 161         wfd_sink_error("failed to pause wi-fi display sink\n");
 162 }
 163  * @endcode
 164  */
 165 int mm_wfd_sink_pause(MMHandleType wfd_sink);
 166
 167 /**
 168  * This function is to resume playing. \n
 169  * Data from wi-fi display source will be received. \n
 170  *
 171  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 172  *
 173  * @return      This function returns zero  on success, or negative value with error code.
 174  * @remark
 175  *
 176  * @pre         wi-fi display sink state may be MM_WFD_SINK_STATE_PAUSED.
 177  * @post                wi-fi display sink state will be MM_WFD_SINK_STATE_PLAYING.
 178  * @see         mm_wfd_sink_disconnect
 179  * @remark      None
 180  * @par Example
 181  * @code
 182 if (mm_wfd_sink_start(g_wfd_sink) != MM_ERROR_NONE)
 183 {
 184         wfd_sink_error("failed to resume wi-fi display sink\n");
 185 }
 186  * @endcode
 187  */
 188 int mm_wfd_sink_resume(MMHandleType wfd_sink);
 189
 190 /**
 191  * This function is to stop playing wi-fi display. \n
 192  *
 193  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 194  *
 195  * @return      This function returns zero on success, or negative value with error code.
 196  *
 197  * @pre         wi-fi display sink state may be MM_WFD_SINK_STATE_PLAYING.
 198  * @post                wi-fi display sink state will be MM_WFD_SINK_STATE_DISCONNECTED.
 199  * @see         mm_wfd_sink_start
 200  * @remark      None
 201  * @par Example
 202  * @code
 203 if (mm_wfd_sink_disconnect(g_wfd_sink) != MM_ERROR_NONE)
 204 {
 205         wfd_sink_error("failed to stop wi-fi display sink\n");
 206 }
 207  * @endcode
 208  */
 209 int mm_wfd_sink_disconnect(MMHandleType wfd_sink);
 210
 211 /**
 212  * This function trys to destroy gstreamer pipeline. \n
 213  *
 214  * @param       wfd_sink                [out]   Handle of wi-fi display sink
 215  *
 216  * @return      This function returns zero on success, or negative value with error code. \n
 217  *                      Please refer 'mm_error.h' to know it in detail.
 218  * @pre         wi-fi display sink state may be MM_WFD_SINK_STATE_PREPARED or MM_WFD_SINK_STATE_DISCONNECTED.
 219  *                      But, it can be called in any state.
 220  * @post                MM_WFD_SINK_STATE_NULL
 221  * @see         mm_wfd_sink_prepare
 222  * @remark      None
 223  * @par Example
 224  * @code
 225 if (mm_wfd_sink_unprepare(&g_wfd_sink) != MM_ERROR_NONE)
 226 {
 227         wfd_sink_error("failed to unprepare wi-fi display sink\n");
 228 }
 229  * @endcode
 230  */
 231 int mm_wfd_sink_unprepare(MMHandleType wfd_sink);
 232
 233 /**
 234  * This function releases wi-fi display sink object and all resources which were created by mm_wfd_sink_create(). \n
 235  * And, wi-fi display sink handle will also be destroyed. \n
 236  *
 237  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 238  *
 239  * @return      This function returns zero on success, or negative value with error code.
 240  * @pre         wi-fi display state may be MM_WFD_SINK_STATE_NULL. \n
 241  *                      But, it can be called in any state.
 242  * @post                Because handle is released, there is no any state.
 243  * @see         mm_wfd_sink_create
 244  * @remark      This method can be called with a valid wi-fi display sink handle from any state to \n
 245  *                      completely shutdown the wi-fi display sink operation.
 246  *
 247  * @par Example
 248  * @code
 249 if (mm_wfd_sink_destroy(g_wfd_sink) != MM_ERROR_NONE)
 250 {
 251         wfd_sink_error("failed to destroy wi-fi display sink\n");
 252 }
 253  * @endcode
 254  */
 255 int mm_wfd_sink_destroy(MMHandleType wfd_sink);
 256
 257 /**
 258  * This function sets callback function for receiving messages from wi-fi display sink. \n
 259  * So, player can notify warning, error and normal cases to application. \n
 260  *
 261  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 262  * @param       callback        [in]    Message callback function.
 263  * @param       user_param      [in]    User parameter which is passed to callback function.
 264  *
 265  * @return      This function returns zero on success, or negative value with error code.
 266  * @see         MMWFDMessageCallback
 267  * @remark      None
 268  * @par Example
 269  * @code
 270
 271 int msg_callback(int error_type, MMWFDSinkStateType state_type, void *user_data)
 272 {
 273         switch (state_type)
 274         {
 275                 case MM_WFD_SINK_STATE_NULL:
 276                         //do something
 277                         break;
 278
 279                 case MM_WFD_SINK_STATE_PREPARED:
 280                         //do something
 281                         break;
 282
 283                 case MM_WFD_SINK_STATE_CONNECTED:
 284                         //do something
 285                         break;
 286
 287                 case MM_WFD_SINK_STATE_PLAYING:
 288                         //do something
 289                         break;
 290
 291                 case MM_WFD_SINK_STATE_PAUSED:
 292                         //do something
 293                         break;
 294
 295                 case MM_WFD_SINK_DISCONNECTED:
 296                         //do something
 297                         break;
 298
 299                 default:
 300                         break;
 301         }
 302         return TRUE;
 303 }
 304
 305 mm_wfd_sink_set_message_callback(g_wfd_sink, msg_callback, (void*)g_wfd_sink);
 306  * @endcode
 307  */
 308 int mm_wfd_sink_set_message_callback(MMHandleType wfd_sink, MMWFDMessageCallback callback, void *user_param);
 309
 310 int mm_wfd_sink_set_attribute(MMHandleType wfd_sink,  char **err_attr_name, const char *first_attribute_name, ...);
 311
 312 /**
 313  * This function get resources \n
 314  *
 315  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 316  *
 317  * @return      This function returns zero on success, or negative value with error code.
 318  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_READY or MM_WFD_SINK_STATE_PREPARED. \n
 319  * @post                N/A
 320  * @remark      resources are released when mm_wfd_sink_destory is called
 321  *
 322  * @par Example
 323  * @code
 324 if (mm_wfd_sink_get_resource(g_wfd_sink) != MM_ERROR_NONE)
 325 {
 326         wfd_sink_error("failed to get resources for wi-fi display sink\n");
 327 }
 328  * @endcode
 329  */
 330 int mm_wfd_sink_get_resource(MMHandleType wfd_sink);
 331
 332 /**
 333  * This function sets the display surface type for wi-fi display sink\n
 334  *
 335  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 336  * @param       display_surface_type            [in]    Display surface type
 337  *
 338  * @return      This function returns zero on success, or negative value with error code.
 339  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_NULL. \n
 340  *
 341  * @par Example
 342  * @code
 343 if (mm_wfd_sink_set_display_surface_type(g_wfd_sink, g_display_surface_type) != MM_ERROR_NONE)
 344 {
 345         wfd_sink_error("failed to set display surface type for wi-fi display sink\n");
 346 }
 347  * @endcode
 348  */
 349 int mm_wfd_sink_set_display_surface_type(MMHandleType wfd_sink, gint display_surface_type);
 350
 351 /**
 352  * This function sets the display overlay for wi-fi display sink\n
 353  *
 354  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 355  * @param       display_overlay         [in]    Display overlay
 356  *
 357  * @return      This function returns zero on success, or negative value with error code.
 358  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_NULL. \n
 359  *
 360  * @par Example
 361  * @code
 362 if (mm_wfd_sink_set_display_overlay(g_wfd_sink, g_display_overlay) != MM_ERROR_NONE)
 363 {
 364         wfd_sink_error("failed to set display overlay for wi-fi display sink\n");
 365 }
 366  * @endcode
 367  */
 368 int mm_wfd_sink_set_display_overlay(MMHandleType wfd_sink, void *display_overlay);
 369
 370 /**
 371  * This function sets the display method for wi-fi display sink\n
 372  *
 373  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 374  * @param       display_method          [in]    Display method
 375  *
 376  * @return      This function returns zero on success, or negative value with error code.
 377  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_NULL. \n
 378  *
 379  * @par Example
 380  * @code
 381 if (mm_wfd_sink_set_display_method(g_wfd_sink, g_display_method) != MM_ERROR_NONE)
 382 {
 383         wfd_sink_error("failed to set display method for wi-fi display sink\n");
 384 }
 385  * @endcode
 386  */
 387 int mm_wfd_sink_set_display_method(MMHandleType wfd_sink, gint display_method);
 388
 389 /**
 390  * This function sets the display visible for wi-fi display sink\n
 391  *
 392  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 393  * @param       display_visible         [in]    Display visible
 394  *
 395  * @return      This function returns zero on success, or negative value with error code.
 396  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_NULL. \n
 397  *
 398  * @par Example
 399  * @code
 400 if (mm_wfd_sink_set_display_visible(g_wfd_sink, g_display_visible) != MM_ERROR_NONE)
 401 {
 402         wfd_sink_error("failed to set display visible for wi-fi display sink\n");
 403 }
 404  * @endcode
 405  */
 406 int mm_wfd_sink_set_display_visible(MMHandleType wfd_sink, gint display_visible);
 407
 408 /**
 409  * This function gets the width and height of video which is played by wi-fi display sink\n
 410  *
 411  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 412  * @param       width           [in]    Width of video
 413  * @param       height          [in]    Height of video
 414  *
 415  * @return      This function returns zero on success, or negative value with error code.
 416  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_CONNECTED or MM_WFD_SINK_STATE_PLAYING. \n
 417  *
 418  * @par Example
 419  * @code
 420 gint g_width=0, g_height=0;
 421
 422 if (mm_wfd_sink_get_video_resolution(g_wfd_sink, &g_width, &g_height) != MM_ERROR_NONE)
 423 {
 424         wfd_sink_error("failed to get video resolution.\n");
 425 }
 426  * @endcode
 427  */
 428 int mm_wfd_sink_get_video_resolution(MMHandleType wfd_sink, gint *width, gint *height);
 429
 430 /**
 431  * This function gets the width and height of video which is played by wi-fi display sink\n
 432  *
 433  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 434  * @param       framerate               [in]    Framerate of video
 435  *
 436  * @return      This function returns zero on success, or negative value with error code.
 437  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_CONNECTED or MM_WFD_SINK_STATE_PLAYING. \n
 438  *
 439  * @par Example
 440  * @code
 441 gint g_framerate=0;
 442
 443 if (mm_wfd_sink_get_video_framerate(g_wfd_sink, &g_framerate) != MM_ERROR_NONE)
 444 {
 445         wfd_sink_error("failed to get video framerate.\n");
 446 }
 447  * @endcode
 448  */
 449 int mm_wfd_sink_get_video_framerate(MMHandleType wfd_sink,  gint *framerate);
 450
 451 /**
 452  * This function sets the resolutions for wi-fi display sink\n
 453  *
 454  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 455  * @param       resolution              [in]    Resolutions for wi-fi display sink
 456  *
 457  * @return      This function returns zero on success, or negative value with error code.
 458  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_NULL. \n
 459  *
 460  */
 461 int mm_wfd_sink_set_resolution(MMHandleType wfd_sink,  gint resolution);
 462
 463 #endif