include/mtpr.h

   1 /*
   2  * Copyright (c) 2022 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_MEDIA_TRANSPORTER_H__
  18 #define __TIZEN_MEDIA_TRANSPORTER_H__
  19
  20 #include <tizen.h>
  21 #include <bundle.h>
  22 #include <media_format.h>
  23 #include <media_packet.h>
  24 #include <sound_manager.h>
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif /* __cplusplus */
  29
  30 /**
  31 * @file media_transporter.h
  32 * @brief This file contains the Media Transporter API.
  33 */
  34
  35 /* TEMP Define ***********************************************/
  36 /* FIXME: this definition have to be applied
  37           at core/api/common pkg, include/tizen_error.h file */
  38 #ifndef TIZEN_ERROR_MEDIA_TRANSPORTER
  39 #define TIZEN_ERROR_MEDIA_TRANSPORTER -0x01A30000
  40 #endif
  41 /*************************************************************/
  42
  43 /**
  44 * @addtogroup CAPI_MEDIA_TRANSPORTER_MODULE
  45 * @{
  46 */
  47
  48 /**
  49  * @brief Media Transporter handle type.
  50  * @since_tizen 7.0
  51  */
  52 typedef void *mtpr_h;
  53
  54 /**
  55  * @brief Enumeration for Media Transporter connection type.
  56  * @since_tizen 7.0
  57  */
  58 typedef enum {
  59         MTPR_CONNECTION_TYPE_RIST_SENDER,
  60         MTPR_CONNECTION_TYPE_RIST_RECEIVER,
  61         MTPR_CONNECTION_TYPE_SRT_SENDER,
  62         MTPR_CONNECTION_TYPE_SRT_RECEIVER,
  63         MTPR_CONNECTION_TYPE_RTSP_SENDER,
  64         MTPR_CONNECTION_TYPE_RTSP_SENDER_TO_SERVER
  65 } mtpr_connection_type_e;
  66
  67 /**
  68  * @brief Enumeration for Media Transporter error.
  69  * @since_tizen 7.0
  70  */
  71 typedef enum {
  72         MTPR_ERROR_NONE = TIZEN_ERROR_NONE,                                /**< Successful */
  73         MTPR_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED,              /**< Not supported */
  74         MTPR_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,      /**< Permission denied */
  75         MTPR_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,      /**< Invalid parameter */
  76         MTPR_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION,      /**< Invalid operation */
  77         MTPR_ERROR_INVALID_STATE = TIZEN_ERROR_MEDIA_TRANSPORTER | 0x01,           /**< Invalid state */
  78         MTPR_ERROR_CONNECTION_FAILED = TIZEN_ERROR_MEDIA_TRANSPORTER | 0x02,       /**< Connection failed */
  79         MTPR_ERROR_RESOURCE_FAILED = TIZEN_ERROR_MEDIA_TRANSPORTER | 0x03,         /**< Resource failed */
  80         MTPR_ERROR_RESOURCE_CONFLICT = TIZEN_ERROR_MEDIA_TRANSPORTER | 0x04,       /**< Resource conflict */
  81 } mtpr_error_e;
  82
  83 /**
  84  * @brief Enumeration for Media Transporter state.
  85  * @since_tizen 7.0
  86  */
  87 typedef enum {
  88         MTPR_STATE_IDLE,        /**<  Created but not prepared */
  89 //      MTPR_STATE_READY,       /**<  Ready to start */
  90         MTPR_STATE_PLAYING,     /**<  Started */
  91         MTPR_STATE_PAUSED,      /**<  Paused while starting */
  92 } mtpr_state_e;
  93
  94 /**
  95  * @brief Enumeration for Media Transporter media type.
  96  * @since_tizen 7.0
  97  */
  98 typedef enum {
  99         MTPR_MEDIA_TYPE_AUDIO,   /**< Audio */
 100         MTPR_MEDIA_TYPE_VIDEO,   /**< Video */
 101 } mtpr_media_type_e;
 102
 103 /**
 104  * @brief Enumeration for Media Transporter source type.
 105  * @since_tizen 7.0
 106  */
 107 typedef enum {
 108         MTPR_SOURCE_TYPE_CAMERA,       /**< Camera preview */
 109         MTPR_SOURCE_TYPE_MIC,          /**< Audio from microphone */
 110         MTPR_SOURCE_TYPE_VIDEOTEST,    /**< Video test */
 111         MTPR_SOURCE_TYPE_AUDIOTEST,    /**< Audio test */
 112 } mtpr_source_type_e;
 113
 114 /**
 115  * @brief Definition for mode parameter of SRT.
 116  * @details The connection mode of SRT.\n
 117             0: not connected.\n
 118             1: caller mode to send the connection request like a client. (default)\n
 119             2: listener mode to wait for being connected by peer caller.\n
 120             3: rendezvous mode to support one-to-one only connection.
 121  * @since_tizen 7.0
 122  * @see mtpr_set_connection_params()
 123  * @see mtpr_get_connection_params()
 124  */
 125 #define MTPR_CONNECTION_PARAM_SRT_MODE "mode"
 126
 127 /**
 128  * @brief Definition for streamid parameter of SRT.
 129  * @details The streamid for the SRT access control.
 130  * @since_tizen 7.0
 131  * @see mtpr_set_connection_params()
 132  * @see mtpr_get_connection_params()
 133  */
 134 #define MTPR_CONNECTION_PARAM_SRT_STREAMID "streamid"
 135
 136 /**
 137  * @brief Definition for password parameter of SRT.
 138  * @details The password for the encrypted transmission of SRT.\n
 139  *          The number of characters must be 10 to 79.
 140  * @since_tizen 7.0
 141  * @remarks This is write only parameter.
 142  * @see mtpr_set_connection_params()
 143  */
 144 #define MTPR_CONNECTION_PARAM_SRT_PASSPHRASE "passphrase"
 145
 146 /**
 147  * @brief Definition for crypto key length of SRT.
 148  * @details The crypto key length in bytes of SRT.\n
 149             0: no encryption. (default)\n
 150             16: 16 bytes (128-bit) length.\n
 151             24: 24 bytes (192-bit) length.\n
 152             32: 32 bytes (256-bit) length.
 153  * @since_tizen 7.0
 154  * @see mtpr_set_connection_params()
 155  * @see mtpr_get_connection_params()
 156  */
 157 #define MTPR_CONNECTION_PARAM_SRT_PBKEYLEN "pbkeylen"
 158
 159 /**
 160  * @brief Definition for bonding addresses of RIST
 161  * @details Bonding address to send packets to (IPv4 or IPv6).\n
 162             Comma (,) separated list of <address>:<port> to send to
 163  * @since_tizen 7.0
 164  * @see mtpr_set_connection_params()
 165  * @see mtpr_get_connection_params()
 166  */
 167 #define MTPR_CONNECTION_PARAM_RIST_BONDING_ADDRESS "bonding-address"
 168
 169 /**
 170  * @brief Definition for max rtcp bandwidth fraction of RIST
 171  * @details The maximum bandwidth used for RTCP as a fraction of RTP bandwidth of RIST
 172             Range: 0 ~ 0.05
 173  * @since_tizen 7.0
 174  * @see mtpr_set_connection_params()
 175  * @see mtpr_get_connection_params()
 176  */
 177 #define MTPR_CONNECTION_PARAM_RIST_MAX_RTCP_BANDWIDTH "max-rtcp-bandwidth"
 178
 179 /**
 180  * @brief Definition for min rtcp interval for of RIST
 181  * @details The minimum interval (in ms) between two regular successive RTCP packets.\n
 182             Range: 0 ~ 100 (ms)
 183  * @since_tizen 7.0
 184  * @see mtpr_set_connection_params()
 185  * @see mtpr_get_connection_params()
 186  */
 187 #define MTPR_CONNECTION_PARAM_RIST_MIN_RTCP_INTERVAL "min-rtcp-interval"
 188
 189 /**
 190  * @brief Definition for size of retransmission queue for RIST
 191  * @details Size of the retransmission queue (in ms).
 192  * @since_tizen 7.0
 193  * @see mtpr_set_connection_params()
 194  * @see mtpr_get_connection_params()
 195  */
 196 #define MTPR_CONNECTION_PARAM_RIST_SENDER_BUFFER "sender-buffer"
 197
 198 /**
 199  * @brief Definition for IP to configure RTSP server
 200  * @details IP address where the RTSP server will listen on.
 201  * @remarks The default value is localhost (0.0.0.0 / 127.0.0.1).
 202  * @since_tizen 7.0
 203  * @see mtpr_set_connection_params()
 204  * @see mtpr_get_connection_params()
 205  */
 206 #define MTPR_CONNECTION_PARAM_RTSP_SERVER_IP "server-ip"
 207
 208 /**
 209  * @brief Definition for port of RTSP server
 210  * @details String containing port number bewteen 1 and 65535\n
 211             where the RTSP server will listen on.
 212  * @remarks The default value is '8554'.
 213  * @since_tizen 7.0
 214  * @see mtpr_set_connection_params()
 215  * @see mtpr_get_connection_params()
 216  */
 217 #define MTPR_CONNECTION_PARAM_RTSP_SERVER_PORT "server-port"
 218
 219 /**
 220  * @brief Definition for mount point of RTSP server
 221  * @remarks The default value is '/mtpr_server/tmp'.
 222  * @since_tizen 7.0
 223  * @see mtpr_set_connection_params()
 224  * @see mtpr_get_connection_params()
 225  */
 226 #define MTPR_CONNECTION_PARAM_RTSP_SERVER_MOUNT_POINT "mount-point"
 227
 228 /**
 229  * @brief Definition for video source width
 230  * @remarks The default value 320
 231  * @since_tizen 7.0
 232  * @see mtpr_add_media_source()
 233  */
 234 #define MTPR_SOURCE_PARAM_VIDEO_WIDTH "video-width"
 235
 236 /**
 237  * @brief Definition for video source height
 238  * @remarks The default value 240
 239  * @since_tizen 7.0
 240  * @see mtpr_add_media_source()
 241  */
 242 #define MTPR_SOURCE_PARAM_VIDEO_HEIGHT "video-height"
 243
 244 /**
 245  * @brief Definition for video source framerate
 246  * @remarks The default value 30
 247  * @since_tizen 7.0
 248  * @see mtpr_add_media_source()
 249  */
 250 #define MTPR_SOURCE_PARAM_VIDEO_FRAMERATE "video-framerate"
 251
 252 /**
 253  * @brief Definition for audio source channel
 254  * @remarks The default value 1
 255  * @since_tizen 7.0
 256  * @see mtpr_add_media_source()
 257  */
 258 #define MTPR_SOURCE_PARAM_AUDIO_CHANNEL "audio-channel"
 259
 260 /**
 261  * @brief Definition for audio source samplerate
 262  * @remarks The default value 48000
 263  * @since_tizen 7.0
 264  * @see mtpr_add_media_source()
 265  */
 266 #define MTPR_SOURCE_PARAM_AUDIO_RATE "audio-rate"
 267
 268 /**
 269  * @brief Definition for audio source format
 270  * @remarks The default value F32LE
 271  * @since_tizen 7.0
 272  * @see mtpr_add_media_source()
 273  */
 274 #define MTPR_SOURCE_PARAM_AUDIO_FORMAT "audio-format"
 275
 276 /**
 277  * @brief Definition for bitrate for encoder
 278  * @details encoding bitrate (kbits/s)\n
 279             If not set encoding parm,\n
 280             bitrate is controlled by the encoder according to width and height.
 281  * @since_tizen 7.0
 282  * @see mtpr_add_media_source()
 283  */
 284 #define MTPR_ENCODING_PARAM_BITRATE "target-bitrate"
 285
 286
 287 /**
 288  * @brief Called when an error occurs.
 289  * @details The following error codes can be received:\n
 290  *          #MTPR_ERROR_INVALID_OPERATION\n
 291  *          #MTPR_ERROR_CONNECTION_FAILED\n
 292  *          #MTPR_ERROR_RESOURCE_FAILED\n
 293  *          #MTPR_ERROR_RESOURCE_CONFLICT
 294  * @since_tizen 7.0
 295  * @remarks The @a mtpr is the same object for which the callback was set.\n
 296  *          The @a mtpr should not be released.
 297  * @param[in] mtpr       Media Transporter handle
 298  * @param[in] error      The error code
 299  * @param[in] user_data  The user data passed from the callback registration function
 300  * @see mtpr_set_error_cb()
 301  * @see mtpr_unset_error_cb()
 302  */
 303 typedef void (*mtpr_error_cb)(mtpr_h mtpr, mtpr_error_e error, void *user_data);
 304
 305 /**
 306  * @brief Called when a new track is added to the receiver.
 307  * @since_tizen 7.0
 308  * @remarks The @a mtpr is the same object for which the callback was set.\n
 309  *          The @a mtpr should not be released.
 310  * @param[in] mtpr       Media Transporter handle
 311  * @param[in] type       The media type
 312  * @param[in] track_id   The track id
 313  * @param[in] user_data  The user data passed from the callback registration function
 314  * @see mtpr_set_track_added_cb()
 315  * @see mtpr_unset_track_added_cb()
 316  */
 317 typedef void (*mtpr_track_added_cb)(mtpr_h mtpr, mtpr_media_type_e type, unsigned int track_id, void *user_data);
 318
 319 /**
 320  * @brief Called when all the track is parsed and prerolled.
 321  * @since_tizen 7.0
 322  * @remarks The @a mtpr is the same object for which the callback was set.\n
 323  *          The @a mtpr should not be released.\n
 324  * @param[in] mtpr       Media Transporter handle
 325  * @param[in] user_data  The user data passed from the callback registration function
 326  * @see mtpr_set_no_more_track_cb()
 327  * @see mtpr_unset_no_more_track_cb()
 328  */
 329 typedef void (*mtpr_no_more_track_cb)(mtpr_h mtpr, void *user_data);
 330
 331 /**
 332  * @brief Called when each audio or video frame is ready to be rendered via the Media Transporter pipeline after the negotiation.
 333  * @since_tizen 7.0
 334  * @remarks The @a mtpr is the same object for which the callback was set.\n
 335  *          The @a mtpr should not be released.\n
 336  *          Use media_packet_get_buffer_data_ptr() with @a packet to get the Gstreamer buffer pointer.\n
 337  *          The @a packet should be released using media_packet_destroy().
 338  * @param[in] mtpr       Media Transporter handle
 339  * @param[in] type       The media type
 340  * @param[in] track_id   The track id
 341  * @param[in] packet     The media packet which has a frame data
 342  * @param[in] user_data  The user data passed from the callback registration function
 343  * @see mtpr_set_audio_packet_cb()
 344  * @see mtpr_unset_audio_packet_cb()
 345  * @see mtpr_set_video_packet_cb()
 346  * @see mtpr_unset_video_packet_cb()
 347  * @see media_packet_get_buffer_data_ptr()
 348  */
 349 typedef void (*mtpr_encoded_frame_cb)(mtpr_h mtpr, mtpr_media_type_e type, unsigned int track_id, media_packet_h packet, void *user_data);
 350
 351 /**
 352  * @brief Creates an instance of Media Transporter.
 353  * @since_tizen 7.0
 354  * @privlevel public
 355  * @privilege %http://tizen.org/privilege/internet
 356  * @remarks A signaling channel not addressed in this API should be established to send SDP or ICE candidate messages to each other.\n
 357  *          The @a mtpr should be released using mtpr_destroy().
 358  * @param[in] type        The connection type
 359  * @param[out] mtpr       Media Transporter handle
 360  * @return @c 0 on success,
 361  *         otherwise a negative error value
 362  * @retval #MTPR_ERROR_NONE Successful
 363  * @retval #MTPR_ERROR_NOT_SUPPORTED Not supported
 364  * @retval #MTPR_ERROR_PERMISSION_DENIED Permission denied
 365  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 366  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 367  * @post @a mtpr state will be #MTPR_STATE_IDLE.
 368  * @see mtpr_destroy()
 369  */
 370 int mtpr_create(mtpr_connection_type_e type, mtpr_h *mtpr);
 371
 372 /**
 373  * @brief Destroys the Media Transporter.
 374  * @since_tizen 7.0
 375  * @param[in] mtpr    Media Transporter handle
 376  * @return @c 0 on success,
 377  *         otherwise a negative error value
 378  * @retval #MTPR_ERROR_NONE Successful
 379  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 380  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 381  * @see mtpr_create()
 382  */
 383 int mtpr_destroy(mtpr_h mtpr);
 384
 385 /**
 386  * @brief Starts the Media Transporter.
 387  * @since_tizen 7.0
 388  * @param[in] mtpr    Media Transporter handle
 389  * @return @c 0 on success,
 390  *         otherwise a negative error value
 391  * @retval #MTPR_ERROR_NONE Successful
 392  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 393  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 394  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 395  * @retval #MTPR_ERROR_RESOURCE_FAILED Resource failed
 396  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 397  * @post @a mtpr state will be #MTPR_STATE_PLAYING. // FIXME
 398  * @see mtpr_create()
 399  * @see mtpr_stop()
 400  */
 401 int mtpr_start(mtpr_h mtpr);
 402
 403 /**
 404  * @brief Stops the Media Transporter.
 405  * @since_tizen 7.0
 406  * @param[in] mtpr    Media Transporter handle
 407  * @return @c 0 on success,
 408  *         otherwise a negative error value
 409  * @retval #MTPR_ERROR_NONE Successful
 410  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 411  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 412  * @retval #MTPR_ERROR_RESOURCE_FAILED Resource failed
 413  * @pre @a mtpr state must be set to #MTPR_STATE_PLAYING. // FIXME
 414  * @post @a mtpr state will be #MTPR_STATE_IDLE.
 415  * @see mtpr_create()
 416  * @see mtpr_start()
 417  */
 418 int mtpr_stop(mtpr_h mtpr);
 419
 420 /**
 421  * @brief Gets the Media Transporter state.
 422  * @since_tizen 7.0
 423  * @param[in]  mtpr     Media Transporter handle
 424  * @param[out] state    Media Transporter state
 425  * @return @c 0 on success,
 426  *         otherwise a negative error value
 427  * @retval #MTPR_ERROR_NONE    Successful
 428  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 429  */
 430 int mtpr_get_state(mtpr_h mtpr, mtpr_state_e *state);
 431
 432 /**
 433  * @brief Gets the connection type.
 434  * @since_tizen 7.0
 435  * @remarks The default value is #MTPR_CONNECTION_TYPE_RIST.
 436  * @param[in] mtpr        Media Transporter handle
 437  * @param[out] type       The connection type
 438  * @return @c 0 on success,
 439  *         otherwise a negative error value
 440  * @retval #MTPR_ERROR_NONE    Successful
 441  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 442  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 443  */
 444 int mtpr_get_connection_type(mtpr_h mtpr, mtpr_connection_type_e *type);
 445
 446 /**
 447  * @brief Sets the sender address
 448  * @since_tizen 7.0
 449  * @remarks It should set when mtpr connection type is \n
 450  *                                      (#MTPR_CONNECTION_TYPE_SRT_SENDER, #MTPR_CONNECTION_TYPE_SRT_RECEIVER, #MTPR_CONNECTION_TYPE_RTSP_SENDER)
 451  * @param[in] mtpr        Media Transporter handle
 452  * @param[in] address     The connection address
 453  * @return @c 0 on success,
 454  *         otherwise a negative error value
 455  * @retval #MTPR_ERROR_NONE    Successful
 456  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 457  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 458  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 459  * @see mtpr_get_connection_address()
 460  */
 461 int mtpr_set_sender_address(mtpr_h mtpr, const char *address);
 462
 463 /**
 464  * @brief Gets the sender address
 465  * @since_tizen 7.0
 466  * @remarks The @a address should be released using free().
 467  * @param[in] mtpr        Media Transporter handle
 468  * @param[out] address    The sender address
 469  * @return @c 0 on success,
 470  *         otherwise a negative error value
 471  * @retval #MTPR_ERROR_NONE    Successful
 472  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 473  * @see mtpr_set_sender_address()
 474  */
 475 int mtpr_get_sender_address(mtpr_h mtpr, char **address);
 476
 477 /**
 478  * @brief Sets the receiver address
 479  * @since_tizen 7.0
 480  * @remarks It should set when mtpr connection type is \n
 481  *                                      (#MTPR_CONNECTION_TYPE_RIST_SENDER, #MTPR_CONNECTION_TYPE_RIST_RECEIVER, #MTPR_CONNECTION_TYPE_RTSP_SENDER_TO_SERVER
 482  * @param[in] mtpr        Media Transporter handle
 483  * @param[in] address     The connection address
 484  * @return @c 0 on success,
 485  *         otherwise a negative error value
 486  * @retval #MTPR_ERROR_NONE    Successful
 487  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 488  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 489  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 490  * @see mtpr_get_receiver_address()
 491  */
 492 int mtpr_set_receiver_address(mtpr_h mtpr, const char *address);
 493
 494 /**
 495  * @brief Gets the receiver address
 496  * @since_tizen 7.0
 497  * @remarks The @a address should be released using free().
 498  * @param[in] mtpr        Media Transporter handle
 499  * @param[out] address    The receiver address
 500  * @return @c 0 on success,
 501  *         otherwise a negative error value
 502  * @retval #MTPR_ERROR_NONE    Successful
 503  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 504  * @see mtpr_set_receiver_address()
 505  */
 506 int mtpr_get_receiver_address(mtpr_h mtpr, char **address);
 507
 508 /**
 509  * @brief Sets connection parameter list.
 510  * @details The parameters are key and value pairs. \n
 511             The key is defined in this header file and the value data type must be string.
 512  * @since_tizen  7.0
 513  * @param[in] mtpr         Media Transporter handle
 514  * @param[in] param_name   connection parameter nam
 515  * @param[in] param_value  connection parameter value
 516  * @return @c 0 on success,
 517  *         otherwise a negative error value
 518  * @retval #MTPR_ERROR_NONE    Successful
 519  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 520  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 521  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 522  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 523  * @see mtpr_set_connection_params()
 524  * @see mtpr_get_connection_params()
 525  * @see #bundle
 526  */
 527 int mtpr_set_connection_param(mtpr_h mtpr, const char *param_name, const char *param_value);
 528
 529 /**
 530  * @brief Sets connection parameter list.
 531  * @details Many connection parameters can be set at one time all together by using bundle. \n
 532             The parameters are key and value pairs. \n
 533             The key is defined in this header file and the value data type must be string.
 534  * @since_tizen  7.0
 535  * @param[in] mtpr         Media Transporter handle
 536  * @param[in] param_list   Key value array of connection parameters
 537  * @return @c 0 on success,
 538  *         otherwise a negative error value
 539  * @retval #MTPR_ERROR_NONE    Successful
 540  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 541  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 542  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 543  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 544  * @see mtpr_get_connection_params()
 545  * @see #bundle
 546  */
 547 int mtpr_set_connection_params(mtpr_h mtpr, bundle *param_list);
 548
 549 /**
 550  * @brief Gets connection parameter list.
 551  * @since_tizen  7.0
 552  * @remarks The @a param_list should be released using bundle_free().\n
 553  * @param[in]  mtpr        Media Transporter handle
 554  * @param[out] param_list  Key value array of connection parameters
 555  * @return @c 0 on success,
 556  *         otherwise a negative error value
 557  * @retval #MTPR_ERROR_NONE    Successful
 558  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 559  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 560  * @see mtpr_set_connection_params()
 561  * @see #bundle
 562  */
 563 int mtpr_get_connection_params(mtpr_h mtpr, bundle **param_list);
 564
 565 /**
 566  * @brief Adds a media source.
 567  * @since_tizen 7.0
 568  * @remarks The camera privilege(%http://tizen.org/privilege/camera) should be added if @a type is #MTPR_MEDIA_SOURCE_TYPE_CAMERA.\n
 569  *          The recorder privilege(%http://tizen.org/privilege/recorder) should be added if @a type is #MTPR_MEDIA_SOURCE_TYPE_MIC.
 570  * @param[in]  mtpr       Media Transporter handle
 571  * @param[in]  mtpr       The media source type to be added
 572  * @param[in]  param_list Key value array of connection/encoding parameters
 573  * @param[out] source_id  The media source id
 574  * @return @c 0 on success,
 575  *         otherwise a negative error value
 576  * @retval #MTPR_ERROR_NONE    Successful
 577  * @retval #MTPR_ERROR_NOT_SUPPORTED Not supported
 578  * @retval #MTPR_ERROR_PERMISSION_DENIED Permission denied
 579  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 580  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 581  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 582  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 583  * @see mtpr_remove_media_source()
 584  * @see mtpr_media_source_set_video_resolution()
 585  * @see mtpr_media_source_get_video_resolution()
 586  * @see mtpr_media_source_set_video_framerate()
 587  * @see mtpr_media_source_get_video_framerate()
 588  */
 589 int mtpr_add_media_source(mtpr_h mtpr, mtpr_source_type_e type, bundle* param_list, unsigned int *source_id);
 590
 591 /**
 592  * @brief Removes the media source.
 593  * @since_tizen 7.0
 594  * @param[in] mtpr        Media Transporter handle
 595  * @param[in] source_id   The media source id to be removed
 596  * @return @c 0 on success,
 597  *         otherwise a negative error value
 598  * @retval #MTPR_ERROR_NONE    Successful
 599  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 600  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 601  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 602  * @pre Add media source to @a mtpr to get @a source_id by calling mtpr_add_media_source().
 603  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 604  * @see mtpr_add_media_source()
 605  */
 606 int mtpr_remove_media_source(mtpr_h mtpr, unsigned int source_id);
 607
 608 /**
 609  * @brief Sets the mic source's sound manager stream information.
 610  * @details If @a source_id is not a media source of #MTPR_SOURCE_TYPE_MIC, this function will return #MTPR_ERROR_INVALID_PARAMETER.
 611  * @since_tizen 7.0
 612  * @remarks You can set sound stream information including audio routing.\n
 613  *          The following sound stream types can be used to create the @a stream_info :\n
 614  *          #SOUND_STREAM_TYPE_MEDIA\n
 615  *          #SOUND_STREAM_TYPE_VOICE_RECOGNITION\n
 616  *          #SOUND_STREAM_TYPE_VOIP\n
 617  *          #SOUND_STREAM_TYPE_MEDIA_EXTERNAL_ONLY\n
 618  *          For more details, please refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE.
 619  * @param[in] mtpr        Media Transporter handle
 620  * @param[in] source_id   The mic source id
 621  * @param[in] stream_info The sound stream information
 622  * @return @c 0 on success, otherwise a negative error value
 623  * @retval #MTPR_ERROR_NONE    Successful
 624  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 625  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 626  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 627  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 628  * @see #sound_stream_info_h
 629  * @see sound_manager_create_stream_information()
 630  * @see sound_manager_destroy_stream_information()
 631  */
 632 int mtpr_mic_source_set_sound_stream_info(mtpr_h mtpr, unsigned int source_id, sound_stream_info_h stream_info);
 633
 634 /**
 635  * @brief Sets a callback function to be invoked when an asynchronous operation error occurs.
 636  * @since_tizen 7.0
 637  * @param[in] mtpr        Media Transporter handle
 638  * @param[in] callback    Callback function pointer
 639  * @param[in] user_data   The user data to be passed to the callback function
 640  * @return @c 0 on success,
 641  *         otherwise a negative error value
 642  * @retval #MTPR_ERROR_NONE    Successful
 643  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 644  * @post mtpr_error_cb() will be invoked.
 645  * @see mtpr_unset_error_cb()
 646  * @see mtpr_error_cb()
 647  */
 648 int mtpr_set_error_cb(mtpr_h mtpr, mtpr_error_cb callback, void *user_data);
 649
 650 /**
 651  * @brief Unsets the error callback function.
 652  * @since_tizen 7.0
 653  * @param[in] mtpr       Media Transporter handle
 654  * @return @c 0 on success,
 655  *         otherwise a negative error value
 656  * @retval #MTPR_ERROR_NONE    Successful
 657  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 658  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 659  * @see mtpr_set_error_cb()
 660  */
 661 int mtpr_unset_error_cb(mtpr_h mtpr);
 662
 663 /**
 664  * @brief Sets a track added callback function to be invoked when a new track is added to the receiver.
 665  * @since_tizen 7.0
 666  * @remarks The registered callback will be invoked in an internal thread of the media transporter.
 667  * @param[in] mtpr        Media Transporter handle
 668  * @param[in] callback    Callback function pointer
 669  * @param[in] user_data   The user data to be passed to the callback function
 670  * @return @c 0 on success,
 671  *         otherwise a negative error value
 672  * @retval #MTPR_ERROR_NONE    Successful
 673  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 674  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 675  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 676  * @post mtpr_track_added_cb() will be invoked.
 677  * @see mtpr_unset_track_added_cb()
 678  * @see mtpr_track_added_cb()
 679  */
 680 int mtpr_set_track_added_cb(mtpr_h mtpr, mtpr_track_added_cb callback, void *user_data);
 681
 682 /**
 683  * @brief Unsets the track added callback function.
 684  * @since_tizen 7.0
 685  * @param[in] mtpr        Media Transporter handle
 686  * @return @c 0 on success,
 687  *         otherwise a negative error value
 688  * @retval #MTPR_ERROR_NONE    Successful
 689  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 690  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 691  * @see mtpr_set_track_added_cb()
 692  */
 693 int mtpr_unset_track_added_cb(mtpr_h mtpr);
 694
 695 /**
 696  * @brief Sets a no more track callback function to be invoked when all the tracks are added to the receiver.
 697  * @since_tizen 7.0
 698  * @remarks The registered callback will be invoked in an internal thread of the media transporter.
 699  * @param[in] mtpr        Media Transporter handle
 700  * @param[in] callback    Callback function pointer
 701  * @param[in] user_data   The user data to be passed to the callback function
 702  * @return @c 0 on success,
 703  *         otherwise a negative error value
 704  * @retval #MTPR_ERROR_NONE    Successful
 705  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 706  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 707  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 708  * @post mtpr_no_more_track_cb() will be invoked.
 709  * @see mtpr_unset_no_more_track_cb()
 710  * @see mtpr_no_more_track_cb()
 711  */
 712 int mtpr_set_no_more_track_cb(mtpr_h mtpr, mtpr_no_more_track_cb callback, void* user_data);
 713
 714 /**
 715  * @brief Unsets the no more track callback function.
 716  * @since_tizen 7.0
 717  * @param[in] mtpr        Media Transporter handle
 718  * @return @c 0 on success,
 719  *         otherwise a negative error value
 720  * @retval #MTPR_ERROR_NONE    Successful
 721  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 722  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 723  * @see mtpr_set_no_more_track_cb()
 724  */
 725 int mtpr_unset_no_more_track_cb(mtpr_h mtpr);
 726
 727 /**
 728  * @brief Sets an encoded audio frame callback function to be invoked when each audio frame is ready to be rendered.
 729  * @since_tizen 7.0
 730  * @remarks If @a callback is set, audio data from the remote peer will be forwarded to @a callback without being rendered by itself.\n
 731  *          The registered callback will be invoked in an internal thread of the media transporter.
 732  * @param[in] mtpr        Media Transporter handle
 733  * @param[in] callback    Callback function pointer
 734  * @param[in] user_data   The user data to be passed to the callback function
 735  * @return @c 0 on success,
 736  *         otherwise a negative error value
 737  * @retval #MTPR_ERROR_NONE    Successful
 738  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 739  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 740  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 741  * @post mtpr_encoded_frame_cb() will be invoked.
 742  * @see mtpr_unset_audio_packet_cb()
 743  * @see mtpr_encoded_frame_cb()
 744  */
 745 int mtpr_set_audio_packet_cb(mtpr_h mtpr, mtpr_encoded_frame_cb callback, void *user_data);
 746
 747 /**
 748  * @brief Unsets the encoded audio frame callback function.
 749  * @since_tizen 7.0
 750  * @param[in] mtpr      Media Transporter handle
 751  * @return @c 0 on success,
 752  *         otherwise a negative error value
 753  * @retval #MTPR_ERROR_NONE    Successful
 754  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 755  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 756  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 757  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 758  * @see mtpr_set_audio_packet_cb()
 759  */
 760 int mtpr_unset_audio_packet_cb(mtpr_h mtpr);
 761
 762 /**
 763  * @brief Sets an encoded video frame callback function to be invoked when each video frame is ready to be rendered.
 764  * @since_tizen 7.0
 765  * @remarks If @a callback is set, video data from the remote peer will be forwarded to @a callback without being rendered by itself.\n
 766  *          The registered callback will be invoked in an internal thread of the media transporter.
 767  * @param[in] mtpr        Media Transporter handle
 768  * @param[in] callback    Callback function pointer
 769  * @param[in] user_data   The user data to be passed to the callback function
 770  * @return @c 0 on success,
 771  *         otherwise a negative error value
 772  * @retval #MTPR_ERROR_NONE    Successful
 773  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 774  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 775  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 776  * @post mtpr_encoded_frame_cb() will be invoked.
 777  * @see mtpr_unset_video_packet_cb()
 778  * @see mtpr_encoded_frame_cb()
 779  */
 780 int mtpr_set_video_packet_cb(mtpr_h mtpr, mtpr_encoded_frame_cb callback, void *user_data);
 781
 782 /**
 783  * @brief Unsets the encoded video frame callback function.
 784  * @since_tizen 7.0
 785  * @param[in] mtpr      Media Transporter handle
 786  * @return @c 0 on success,
 787  *         otherwise a negative error value
 788  * @retval #MTPR_ERROR_NONE    Successful
 789  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 790  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 791  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 792  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 793  * @see mtpr_set_video_packet_cb()
 794  */
 795 int mtpr_unset_video_packet_cb(mtpr_h mtpr);
 796
 797 /**
 798  * @}
 799  */
 800
 801 #ifdef __cplusplus
 802 }
 803 #endif /* __cplusplus */
 804
 805 #endif /* __TIZEN_MEDIA_TRANSPORTER_H__ */
 806