src/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 /* audio codec : AAC, AC3, LPCM  */
  47 typedef enum {
  48         MM_WFD_SINK_AUDIO_CODEC_NONE,
  49         MM_WFD_SINK_AUDIO_CODEC_AAC = 0x0F,
  50         MM_WFD_SINK_AUDIO_CODEC_AC3 = 0x81,
  51         MM_WFD_SINK_AUDIO_CODEC_LPCM = 0x83
  52 } MMWFDSinkAudioCodec;
  53
  54 typedef enum {
  55         MM_WFD_SINK_HDCP_v2_0 = 1,
  56         MM_WFD_SINK_HDCP_v2_1
  57 } MMWfdSinkHDCPVersion;
  58
  59 /* video codec */
  60 typedef enum {
  61         MM_WFD_SINK_VIDEO_CODEC_NONE,
  62         MM_WFD_SINK_VIDEO_CODEC_H265 = 0x24,
  63         MM_WFD_SINK_VIDEO_CODEC_VP9  = 0x91,
  64         MM_WFD_SINK_VIDEO_CODEC_H264 = 0x1b
  65 } MMWFDSinkVideoCodec;
  66
  67 typedef enum {
  68         MM_WFD_COUPLED_SINK_STATUS_NOT_COUPLED = 0,
  69         MM_WFD_COUPLED_SINK_STATUS_COUPLED,
  70         MM_WFD_COUPLED_SINK_STATUS_TEARDOWN_COUPLING,
  71         MM_WFD_COUPLED_SINK_STATUS_RESERVED
  72 } MMWFDCoupledSinkStatus;
  73
  74 typedef void(*MMWFDMessageCallback)(int error_type, MMWFDSinkStateType state_type, void *user_data);
  75
  76 /**
  77  * This function creates a wi-fi display sink object. \n
  78  * The attributes of wi-fi display sink are created to get/set some values with application. \n
  79  * And, mutex, gstreamer and other resources are initialized at this time. \n
  80  * If wi-fi display sink is created, he state will become MM_WFD_SINK_STATE_NULL.. \n
  81  *
  82  * @param       wfd_sink                [out]   Handle of wi-fi display sink
  83  *
  84  * @return      This function returns zero on success, or negative value with error code. \n
  85  *                      Please refer 'mm_error.h' to know it in detail.
  86  * @pre         None
  87  * @post        MM_WFD_SINK_STATE_NULL
  88  * @see         mm_wfd_sink_destroy
  89  * @remark      You can create multiple handles on a context at the same time. \n
  90  *                      However, wi-fi display sink cannot guarantee proper operation because of limitation of resources, \n
  91  *                      such as audio device or display device.
  92  *
  93  * @par Example
  94  * @code
  95 if (mm_wfd_sink_create(&g_wfd_sink_handle) != MM_ERROR_NONE)
  96 {
  97         wfd_sink_error("failed to create wi-fi display sink\n");
  98 }
  99
 100 mm_wfd_sink_set_message_callback(g_wfd_sink_handle, msg_callback, (void*)g_wfd_sink_handle);
 101  * @endcode
 102  */
 103 int mm_wfd_sink_create(MMHandleType *wfd_sink);
 104
 105 /**
 106  * This function creates a wi-fi display R2 sink object. \n
 107  * Description is same to 'mm_wfd_sink_create' but 'wfd_sink' parameter should be handle of wi-fi display R2(primary/secondary) sink. \n
 108  *
 109  * @param       wfd_sink                [out]   Handle of wi-fi display R2(primary/secondary) sink
 110  */
 111 int mm_wfd_sink_create_r2(MMHandleType *wfd_sink);
 112
 113 /**
 114  * This function trys to make gstreamer pipeline. \n
 115  * If wi-fi display sink is realized, the state will become MM_WFD_SINK_STATE_READY.. \n
 116  *
 117  * @param       wfd_sink                [out]   Handle of wi-fi display sink
 118  *
 119  * @return      This function returns zero on success, or negative value with error code. \n
 120  *                      Please refer 'mm_error.h' to know it in detail.
 121  * @pre         MM_WFD_SINK_STATE_NULL
 122  * @post        MM_WFD_SINK_STATE_PREPARED
 123  * @see         mm_wfd_sink_unprepare
 124  * @remark      None
 125  * @par Example
 126  * @code
 127 if (mm_wfd_sink_prepare(&g_wfd_sink_handle) != MM_ERROR_NONE)
 128 {
 129         wfd_sink_error("failed to realize wi-fi display sink\n");
 130 }
 131  * @endcode
 132  */
 133 int mm_wfd_sink_prepare(MMHandleType wfd_sink_handle);
 134
 135 /**
 136  * This function connect wi-fi display source using uri. \n
 137  * audio type(AC3 AAC, LPCM) is decided at this time. \n
 138  *
 139  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 140  * @param       uri                     [in]    URI of wi-fi displaysource to be connected
 141  *
 142  * @return      This function returns zero on success, or negative value with error code.
 143  *
 144  * @pre         wi-fi display sink state should be MM_WFD_SINK_STATE_PREPARED
 145  * @post        wi-fi display sink state will be MM_WFD_SINK_STATE_CONNECTED with no preroll.
 146  * @remark      None
 147  * @par Example
 148  * @code
 149 if (mm_wfd_sink_connect(g_wfd_sink_handle, g_uri) != MM_ERROR_NONE)
 150 {
 151         wfd_sink_error("failed to connect to wi-fi display source\n");
 152 }
 153  * @endcode
 154  */
 155 int mm_wfd_sink_connect(MMHandleType wfd_sink_handle, const char *uri);
 156
 157 /**
 158  * This function is to start playing. \n
 159  * Data from wi-fi display source will be received. \n
 160  *
 161  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 162  *
 163  * @return      This function returns zero on success, or negative value with error code.
 164  * @remark
 165  *
 166  * @pre         wi-fi display sink state may be MM_WFD_SINK_STATE_CONNECTED.
 167  * @post        wi-fi display sink state will be MM_WFD_SINK_STATE_PLAYING.
 168  * @see         mm_wfd_sink_disconnect
 169  * @remark      None
 170  * @par Example
 171  * @code
 172 if (mm_wfd_sink_start(g_wfd_sink_handle) != MM_ERROR_NONE)
 173 {
 174         wfd_sink_error("failed to start wi-fi display sink\n");
 175 }
 176  * @endcode
 177  */
 178 int mm_wfd_sink_start(MMHandleType wfd_sink_handle);
 179
 180 /**
 181  * This function is to pause playing. \n
 182  * The wi-fi display sink pause the current stream being received form wi-fi display source. \n
 183  *
 184  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 185  *
 186  * @return      This function returns zero on success, or negative value with error code.
 187  * @remark
 188  *
 189  * @pre         wi-fi display sink state should be MM_WFD_SINK_STATE_PLAYING.
 190  * @post        wi-fi display sink state will be MM_WFD_SINK_STATE_PAUSED.
 191  * @see         mm_wfd_sink_pause
 192  * @remark      None
 193  * @par Example
 194  * @code
 195 if (mm_wfd_sink_pause(g_wfd_sink_handle) != MM_ERROR_NONE)
 196 {
 197         wfd_sink_error("failed to pause wi-fi display sink\n");
 198 }
 199  * @endcode
 200  */
 201 int mm_wfd_sink_pause(MMHandleType wfd_sink_handle);
 202
 203 /**
 204  * This function is to resume playing. \n
 205  * Data from wi-fi display source will be received. \n
 206  *
 207  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 208  *
 209  * @return      This function returns zero  on success, or negative value with error code.
 210  * @remark
 211  *
 212  * @pre         wi-fi display sink state may be MM_WFD_SINK_STATE_PAUSED.
 213  * @post        wi-fi display sink state will be MM_WFD_SINK_STATE_PLAYING.
 214  * @see         mm_wfd_sink_disconnect
 215  * @remark      None
 216  * @par Example
 217  * @code
 218 if (mm_wfd_sink_start(g_wfd_sink_handle) != MM_ERROR_NONE)
 219 {
 220         wfd_sink_error("failed to resume wi-fi display sink\n");
 221 }
 222  * @endcode
 223  */
 224 int mm_wfd_sink_resume(MMHandleType wfd_sink_handle);
 225
 226 /**
 227  * This function is to stop playing wi-fi display. \n
 228  *
 229  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 230  *
 231  * @return      This function returns zero on success, or negative value with error code.
 232  *
 233  * @pre         wi-fi display sink state may be MM_WFD_SINK_STATE_PLAYING.
 234  * @post        wi-fi display sink state will be MM_WFD_SINK_STATE_DISCONNECTED.
 235  * @see         mm_wfd_sink_start
 236  * @remark      None
 237  * @par Example
 238  * @code
 239 if (mm_wfd_sink_disconnect(g_wfd_sink_handle) != MM_ERROR_NONE)
 240 {
 241         wfd_sink_error("failed to stop wi-fi display sink\n");
 242 }
 243  * @endcode
 244  */
 245 int mm_wfd_sink_disconnect(MMHandleType wfd_sink_handle);
 246
 247 /**
 248  * This function trys to destroy gstreamer pipeline. \n
 249  *
 250  * @param       wfd_sink_handle         [out]   Handle of wi-fi display sink
 251  *
 252  * @return      This function returns zero on success, or negative value with error code. \n
 253  *                      Please refer 'mm_error.h' to know it in detail.
 254  * @pre         wi-fi display sink state may be MM_WFD_SINK_STATE_PREPARED or MM_WFD_SINK_STATE_DISCONNECTED.
 255  *                      But, it can be called in any state.
 256  * @post        MM_WFD_SINK_STATE_NULL
 257  * @see         mm_wfd_sink_prepare
 258  * @remark      None
 259  * @par Example
 260  * @code
 261 if (mm_wfd_sink_unprepare(&g_wfd_sink_handle) != MM_ERROR_NONE)
 262 {
 263         wfd_sink_error("failed to unprepare wi-fi display sink\n");
 264 }
 265  * @endcode
 266  */
 267 int mm_wfd_sink_unprepare(MMHandleType wfd_sink_handle);
 268
 269 /**
 270  * This function releases wi-fi display sink object and all resources which were created by mm_wfd_sink_create(). \n
 271  * And, wi-fi display sink handle will also be destroyed. \n
 272  *
 273  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 274  *
 275  * @return      This function returns zero on success, or negative value with error code.
 276  * @pre         wi-fi display state may be MM_WFD_SINK_STATE_NULL. \n
 277  *                      But, it can be called in any state.
 278  * @post        Because handle is released, there is no any state.
 279  * @see         mm_wfd_sink_create
 280  * @remark      This method can be called with a valid wi-fi display sink handle from any state to \n
 281  *                      completely shutdown the wi-fi display sink operation.
 282  *
 283  * @par Example
 284  * @code
 285 if (mm_wfd_sink_destroy(g_wfd_sink_handle) != MM_ERROR_NONE)
 286 {
 287         wfd_sink_error("failed to destroy wi-fi display sink\n");
 288 }
 289  * @endcode
 290  */
 291 int mm_wfd_sink_destroy(MMHandleType wfd_sink_handle);
 292
 293 /**
 294  * This function sets callback function for receiving messages from wi-fi display sink. \n
 295  * So, player can notify warning, error and normal cases to application. \n
 296  *
 297  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 298  * @param       callback        [in]    Message callback function.
 299  * @param       user_param      [in]    User parameter which is passed to callback function.
 300  *
 301  * @return      This function returns zero on success, or negative value with error code.
 302  * @see         MMWFDMessageCallback
 303  * @remark      None
 304  * @par Example
 305  * @code
 306
 307 int msg_callback(int error_type, MMWFDSinkStateType state_type, void *user_data)
 308 {
 309         switch (state_type)
 310         {
 311                 case MM_WFD_SINK_STATE_NULL:
 312                         //do something
 313                         break;
 314
 315                 case MM_WFD_SINK_STATE_PREPARED:
 316                         //do something
 317                         break;
 318
 319                 case MM_WFD_SINK_STATE_CONNECTED:
 320                         //do something
 321                         break;
 322
 323                 case MM_WFD_SINK_STATE_PLAYING:
 324                         //do something
 325                         break;
 326
 327                 case MM_WFD_SINK_STATE_PAUSED:
 328                         //do something
 329                         break;
 330
 331                 case MM_WFD_SINK_DISCONNECTED:
 332                         //do something
 333                         break;
 334
 335                 default:
 336                         break;
 337         }
 338         return TRUE;
 339 }
 340
 341 mm_wfd_sink_set_message_callback(g_wfd_sink_handle, msg_callback, (void*)g_wfd_sink_handle);
 342  * @endcode
 343  */
 344 int mm_wfd_sink_set_message_callback(MMHandleType wfd_sink_handle, MMWFDMessageCallback callback, void *user_param);
 345
 346 int mm_wfd_sink_set_attribute(MMHandleType wfd_sink_handle,  char **err_attr_name, const char *first_attribute_name, ...);
 347
 348 /**
 349  * This function gets the width and height of video which is played by wi-fi display sink\n
 350  *
 351  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 352  * @param       width           [in]    Width of video
 353  * @param       height          [in]    Height of video
 354  *
 355  * @return      This function returns zero on success, or negative value with error code.
 356  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_CONNECTED or MM_WFD_SINK_STATE_PLAYING. \n
 357  *
 358  * @par Example
 359  * @code
 360 gint g_width=0, g_height=0;
 361
 362 if (mm_wfd_sink_get_video_resolution(g_wfd_sink_handle, &g_width, &g_height) != MM_ERROR_NONE)
 363 {
 364         wfd_sink_error("failed to get video resolution.\n");
 365 }
 366  * @endcode
 367  */
 368 int mm_wfd_sink_get_video_resolution(MMHandleType wfd_sink_handle, gint *width, gint *height);
 369
 370 /**
 371  * This function gets the width and height of video which is played by wi-fi display sink\n
 372  *
 373  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 374  * @param       framerate               [in]    Framerate of video
 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_CONNECTED or MM_WFD_SINK_STATE_PLAYING. \n
 378  *
 379  * @par Example
 380  * @code
 381 gint g_framerate=0;
 382
 383 if (mm_wfd_sink_get_video_framerate(g_wfd_sink_handle, &g_framerate) != MM_ERROR_NONE)
 384 {
 385         wfd_sink_error("failed to get video framerate.\n");
 386 }
 387  * @endcode
 388  */
 389 int mm_wfd_sink_get_video_framerate(MMHandleType wfd_sink_handle,  gint *framerate);
 390
 391 /**
 392  * This function sets the resolutions for wi-fi display sink\n
 393  *
 394  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 395  * @param       resolution              [in]    Resolutions for wi-fi display sink
 396  *
 397  * @return      This function returns zero on success, or negative value with error code.
 398  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_NULL. \n
 399  *
 400  */
 401 int mm_wfd_sink_set_resolution(MMHandleType wfd_sink_handle,  gint resolution);
 402
 403 /**
 404  * This function gets the negotiated video codec for wi-fi display sink\n
 405  *
 406  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 407  * @param       codec           [in]    video codec for wi-fi display sink
 408  *
 409  * @return      This function returns zero on success, or negative value with error code.
 410  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_CONNECTED, MM_WFD_SINK_STATE_PLAYING or MM_WFD_SINK_STATE_PAUSED. \n
 411  *
 412  */
 413 int mm_wfd_sink_get_negotiated_video_codec(MMHandleType wfd_sink_handle,  gint *codec);
 414
 415 /**
 416  * This function gets the negotiated video resolution for wi-fi display sink\n
 417  *
 418  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 419  * @param       width           [in]    video width for wi-fi display sink
 420  * @param       height          [in]    video height for wi-fi display sink
 421  *
 422  * @return      This function returns zero on success, or negative value with error code.
 423  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_CONNECTED, MM_WFD_SINK_STATE_PLAYING or MM_WFD_SINK_STATE_PAUSED. \n
 424  *
 425  */
 426 int mm_wfd_sink_get_negotiated_video_resolution(MMHandleType wfd_sink_handle,  gint *width, gint *height);
 427
 428 /**
 429  * This function gets the negotiated video framerate for wi-fi display sink\n
 430  *
 431  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 432  * @param       framerate               [in]    video framerate for wi-fi display sink
 433  *
 434  * @return      This function returns zero on success, or negative value with error code.
 435  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_CONNECTED, MM_WFD_SINK_STATE_PLAYING or MM_WFD_SINK_STATE_PAUSED. \n
 436  *
 437  */
 438 int mm_wfd_sink_get_negotiated_video_frame_rate(MMHandleType wfd_sink_handle,  gint *frame_rate);
 439
 440 /**
 441  * This function gets the negotiated audio codec for wi-fi display sink\n
 442  *
 443  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 444  * @param       codec           [in]    audio codec for wi-fi display sink
 445  *
 446  * @return      This function returns zero on success, or negative value with error code.
 447  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_CONNECTED, MM_WFD_SINK_STATE_PLAYING or MM_WFD_SINK_STATE_PAUSED. \n
 448  *
 449  */
 450 int mm_wfd_sink_get_negotiated_audio_codec(MMHandleType wfd_sink_handle,  gint *codec);
 451
 452 /**
 453  * This function gets the negotiated audio channel for wi-fi display sink\n
 454  *
 455  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 456  * @param       channel         [in]    audio channel for wi-fi display sink
 457  *
 458  * @return      This function returns zero on success, or negative value with error code.
 459  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_CONNECTED, MM_WFD_SINK_STATE_PLAYING or MM_WFD_SINK_STATE_PAUSED. \n
 460  *
 461  */
 462 int mm_wfd_sink_get_negotiated_audio_channel(MMHandleType wfd_sink_handle,  gint *channel);
 463
 464 /**
 465  * This function gets the negotiated audio sample rate for wi-fi display sink\n
 466  *
 467  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 468  * @param       sample_rate             [in]    audio sample rate for wi-fi display sink
 469  *
 470  * @return      This function returns zero on success, or negative value with error code.
 471  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_CONNECTED, MM_WFD_SINK_STATE_PLAYING or MM_WFD_SINK_STATE_PAUSED. \n
 472  *
 473  */
 474 int mm_wfd_sink_get_negotiated_audio_sample_rate(MMHandleType wfd_sink_handle,  gint *sample_rate);
 475
 476 /**
 477  * This function gets the negotiated audio bitwidth for wi-fi display sink\n
 478  *
 479  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 480  * @param       bitwidth                [in]    audio bitwidth for wi-fi display sink
 481  *
 482  * @return      This function returns zero on success, or negative value with error code.
 483  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_CONNECTED, MM_WFD_SINK_STATE_PLAYING or MM_WFD_SINK_STATE_PAUSED. \n
 484  *
 485  */
 486 int mm_wfd_sink_get_negotiated_audio_bitwidth(MMHandleType wfd_sink_handle,  gint *bitwidth);
 487
 488 /**
 489  * This function gets the current state for wi-fi display sink\n
 490  *
 491  * @param       wfd_sink_handle         [in]    Handle of wi-fi display sink
 492  * @param       state           [out]   Current state of wi-fi display sink
 493  *
 494  * @return      This function returns zero on success, or negative value with error code.
 495  *
 496  */
 497 int mm_wfd_sink_get_current_state(MMHandleType wfd_sink_handle, gint *state);
 498
 499 /**
 500  * This function sets the MAC(or IP) address of coupled wi-fi display R2 sink. \n
 501  *
 502  * @param   wfd_sink_handle     [in]    Handle of wi-fi display R2 sink
 503  * @param   address             [in]   Mac(or IP) address of coupled wi-fi display R2 sink.
 504  *
 505  * @return  This function returns zero on success, or negative value with error code.
 506  *
 507  */
 508 int mm_wfd_sink_set_coupled_sink(MMHandleType wfd_sink_handle, gchar *address);
 509
 510 /**
 511  * This function sets the coupling status of wi-fi display R2 sink. \n
 512  *
 513  * @param   wfd_sink_handle     [in]    Handle of wi-fi display R2 sink
 514  * @param   status             [in]   Coupling status of wi-fi display R2 sink.
 515  *
 516  * @return  This function returns zero on success, or negative value with error code.
 517  *
 518  */
 519 int mm_wfd_sink_set_coupled_sink_status(MMHandleType wfd_sink_handle, guint status);
 520
 521 #endif