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_READY
  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_READY
 109  * @post                wi-fi display sink state will be MM_WFD_SINK_STATE_PAUSED 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_PAUSED.
 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 stop playing wi-fi display. \n
 146  *
 147  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 148  *
 149  * @return      This function returns zero on success, or negative value with error code.
 150  *
 151  * @pre         wi-fi display sink state may be MM_WFD_SINK_STATE_PLAYING.
 152  * @post                wi-fi display sink state will be MM_WFD_SINK_STATE_READY.
 153  * @see         mm_wfd_sink_start
 154  * @remark      None
 155  * @par Example
 156  * @code
 157 if (mm_wfd_sink_disconnect(g_wfd_sink) != MM_ERROR_NONE)
 158 {
 159         wfd_sink_error("failed to stop wi-fi display sink\n");
 160 }
 161  * @endcode
 162  */
 163 int mm_wfd_sink_disconnect(MMHandleType wfd_sink);
 164
 165 /**
 166  * This function trys to destroy gstreamer pipeline. \n
 167  *
 168  * @param       wfd_sink                [out]   Handle of wi-fi display sink
 169  *
 170  * @return      This function returns zero on success, or negative value with error code. \n
 171  *                      Please refer 'mm_error.h' to know it in detail.
 172  * @pre         wi-fi display sink state may be MM_WFD_SINK_STATE_READY.
 173  *                      But, it can be called in any state.
 174  * @post                MM_WFD_SINK_STATE_NULL
 175  * @see         mm_wfd_sink_prepare
 176  * @remark      None
 177  * @par Example
 178  * @code
 179 if (mm_wfd_sink_unprepare(&g_wfd_sink) != MM_ERROR_NONE)
 180 {
 181         wfd_sink_error("failed to unrealize wi-fi display sink\n");
 182 }
 183  * @endcode
 184  */
 185 int mm_wfd_sink_unprepare(MMHandleType wfd_sink);
 186
 187 /**
 188  * This function releases wi-fi display sink object and all resources which were created by mm_wfd_sink_create(). \n
 189  * And, wi-fi display sink handle will also be destroyed. \n
 190  *
 191  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 192  *
 193  * @return      This function returns zero on success, or negative value with error code.
 194  * @pre         wi-fi display state may be MM_WFD_SINK_STATE_NULL. \n
 195  *                      But, it can be called in any state.
 196  * @post                Because handle is released, there is no any state.
 197  * @see         mm_wfd_sink_create
 198  * @remark      This method can be called with a valid wi-fi display sink handle from any state to \n
 199  *                      completely shutdown the wi-fi display sink operation.
 200  *
 201  * @par Example
 202  * @code
 203 if (mm_wfd_sink_destroy(g_wfd_sink) != MM_ERROR_NONE)
 204 {
 205         wfd_sink_error("failed to destroy wi-fi display sink\n");
 206 }
 207  * @endcode
 208  */
 209 int mm_wfd_sink_destroy(MMHandleType wfd_sink);
 210
 211 /**
 212  * This function sets callback function for receiving messages from wi-fi display sink. \n
 213  * So, player can notify warning, error and normal cases to application. \n
 214  *
 215  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 216  * @param       callback        [in]    Message callback function.
 217  * @param       user_param      [in]    User parameter which is passed to callback function.
 218  *
 219  * @return      This function returns zero on success, or negative value with error code.
 220  * @see         MMWFDMessageCallback
 221  * @remark      None
 222  * @par Example
 223  * @code
 224
 225 int msg_callback(int error_type, MMWFDSinkStateType state_type, void *user_data)
 226 {
 227         switch (state_type)
 228         {
 229                 case MM_WFD_SINK_STATE_NULL:
 230                         //do something
 231                         break;
 232
 233                 case MM_WFD_SINK_STATE_READY:
 234                         //do something
 235                         break;
 236
 237                 case MM_WFD_SINK_STATE_PAUSED:
 238                         //do something
 239                         break;
 240
 241                 case MM_WFD_SINK_STATE_PLAYING:
 242                         //do something
 243                         break;
 244
 245                 case MM_WFD_SINK_STATE_TEARDOWN:
 246                         //do something
 247                         break;
 248
 249                 default:
 250                         break;
 251         }
 252         return TRUE;
 253 }
 254
 255 mm_wfd_sink_set_message_callback(g_wfd_sink, msg_callback, (void*)g_wfd_sink);
 256  * @endcode
 257  */
 258 int mm_wfd_sink_set_message_callback(MMHandleType wfd_sink, MMWFDMessageCallback callback, void *user_param);
 259
 260 int mm_wfd_sink_set_attribute(MMHandleType wfd_sink,  char **err_attr_name, const char *first_attribute_name, ...);
 261
 262 /**
 263  * This function get resources \n
 264  *
 265  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 266  *
 267  * @return      This function returns zero on success, or negative value with error code.
 268  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_READY or MM_WFD_SINK_STATE_PAUSED. \n
 269  * @post                N/A
 270  * @remark      resources are released when mm_wfd_sink_destory is called
 271  *
 272  * @par Example
 273  * @code
 274 if (mm_wfd_sink_get_resource(g_wfd_sink) != MM_ERROR_NONE)
 275 {
 276         wfd_sink_error("failed to get resources for wi-fi display sink\n");
 277 }
 278  * @endcode
 279  */
 280 int mm_wfd_sink_get_resource(MMHandleType wfd_sink);
 281
 282 /**
 283  * This function sets the display surface type for wi-fi display sink\n
 284  *
 285  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 286  * @param       display_surface_type            [in]    Display surface type
 287  *
 288  * @return      This function returns zero on success, or negative value with error code.
 289  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_NULL. \n
 290  *
 291  * @par Example
 292  * @code
 293 if (mm_wfd_sink_set_display_surface_type(g_wfd_sink, g_display_surface_type) != MM_ERROR_NONE)
 294 {
 295         wfd_sink_error("failed to set display surface type for wi-fi display sink\n");
 296 }
 297  * @endcode
 298  */
 299 int mm_wfd_sink_set_display_surface_type(MMHandleType wfd_sink, gint display_surface_type);
 300
 301 /**
 302  * This function sets the display overlay for wi-fi display sink\n
 303  *
 304  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 305  * @param       display_overlay         [in]    Display overlay
 306  *
 307  * @return      This function returns zero on success, or negative value with error code.
 308  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_NULL. \n
 309  *
 310  * @par Example
 311  * @code
 312 if (mm_wfd_sink_set_display_overlay(g_wfd_sink, g_display_overlay) != MM_ERROR_NONE)
 313 {
 314         wfd_sink_error("failed to set display overlay for wi-fi display sink\n");
 315 }
 316  * @endcode
 317  */
 318 int mm_wfd_sink_set_display_overlay(MMHandleType wfd_sink, void *display_overlay);
 319
 320 /**
 321  * This function sets the display method for wi-fi display sink\n
 322  *
 323  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 324  * @param       display_method          [in]    Display method
 325  *
 326  * @return      This function returns zero on success, or negative value with error code.
 327  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_NULL. \n
 328  *
 329  * @par Example
 330  * @code
 331 if (mm_wfd_sink_set_display_method(g_wfd_sink, g_display_method) != MM_ERROR_NONE)
 332 {
 333         wfd_sink_error("failed to set display method for wi-fi display sink\n");
 334 }
 335  * @endcode
 336  */
 337 int mm_wfd_sink_set_display_method(MMHandleType wfd_sink, gint display_method);
 338
 339 /**
 340  * This function sets the display visible for wi-fi display sink\n
 341  *
 342  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 343  * @param       display_visible         [in]    Display visible
 344  *
 345  * @return      This function returns zero on success, or negative value with error code.
 346  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_NULL. \n
 347  *
 348  * @par Example
 349  * @code
 350 if (mm_wfd_sink_set_display_visible(g_wfd_sink, g_display_visible) != MM_ERROR_NONE)
 351 {
 352         wfd_sink_error("failed to set display visible for wi-fi display sink\n");
 353 }
 354  * @endcode
 355  */
 356 int mm_wfd_sink_set_display_visible(MMHandleType wfd_sink, gint display_visible);
 357
 358 /**
 359  * This function gets the width and height of video which is played by wi-fi display sink\n
 360  *
 361  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 362  * @param       width           [in]    Width of video
 363  * @param       height          [in]    Height of video
 364  *
 365  * @return      This function returns zero on success, or negative value with error code.
 366  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_PAUSED. \n
 367  *
 368  * @par Example
 369  * @code
 370 gint g_width=0, g_height=0;
 371
 372 if (mm_wfd_sink_get_video_resolution(g_wfd_sink, &g_width, &g_height) != MM_ERROR_NONE)
 373 {
 374         wfd_sink_error("failed to get video resolution.\n");
 375 }
 376  * @endcode
 377  */
 378 int mm_wfd_sink_get_video_resolution(MMHandleType wfd_sink, gint *width, gint *height );
 379
 380 /**
 381  * This function gets the width and height of video which is played by wi-fi display sink\n
 382  *
 383  * @param       wfd_sink                [in]    Handle of wi-fi display sink
 384  * @param       framerate               [in]    Framerate of video
 385  *
 386  * @return      This function returns zero on success, or negative value with error code.
 387  * @pre         wi-fi display state should be MM_WFD_SINK_STATE_PAUSED. \n
 388  *
 389  * @par Example
 390  * @code
 391 gint g_framerate=0;
 392
 393 if (mm_wfd_sink_get_video_framerate(g_wfd_sink, &g_framerate) != MM_ERROR_NONE)
 394 {
 395         wfd_sink_error("failed to get video framerate.\n");
 396 }
 397  * @endcode
 398  */
 399 int mm_wfd_sink_get_video_framerate(MMHandleType wfd_sink,  gint *framerate);
 400
 401 #endif