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_RESOURCE_FAILED Resource failed
 395  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 396  * @post @a mtpr state will be #MTPR_STATE_PLAYING. // FIXME
 397  * @see mtpr_create()
 398  * @see mtpr_stop()
 399  */
 400 int mtpr_start(mtpr_h mtpr);
 401
 402 /**
 403  * @brief Stops the Media Transporter.
 404  * @since_tizen 7.0
 405  * @param[in] mtpr    Media Transporter handle
 406  * @return @c 0 on success,
 407  *         otherwise a negative error value
 408  * @retval #MTPR_ERROR_NONE Successful
 409  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 410  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 411  * @retval #MTPR_ERROR_RESOURCE_FAILED Resource failed
 412  * @pre @a mtpr state must be set to #MTPR_STATE_PLAYING. // FIXME
 413  * @post @a mtpr state will be #MTPR_STATE_IDLE.
 414  * @see mtpr_create()
 415  * @see mtpr_start()
 416  */
 417 int mtpr_stop(mtpr_h mtpr);
 418
 419 /**
 420  * @brief Gets the Media Transporter state.
 421  * @since_tizen 7.0
 422  * @param[in]  mtpr     Media Transporter handle
 423  * @param[out] state    Media Transporter state
 424  * @return @c 0 on success,
 425  *         otherwise a negative error value
 426  * @retval #MTPR_ERROR_NONE    Successful
 427  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 428  */
 429 int mtpr_get_state(mtpr_h mtpr, mtpr_state_e *state);
 430
 431 /**
 432  * @brief Gets the connection type.
 433  * @since_tizen 7.0
 434  * @remarks The default value is #MTPR_CONNECTION_TYPE_RIST.
 435  * @param[in] mtpr        Media Transporter handle
 436  * @param[out] type       The connection type
 437  * @return @c 0 on success,
 438  *         otherwise a negative error value
 439  * @retval #MTPR_ERROR_NONE    Successful
 440  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 441  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 442  */
 443 int mtpr_get_connection_type(mtpr_h mtpr, mtpr_connection_type_e *type);
 444
 445 /**
 446  * @brief Sets the sender address
 447  * @since_tizen 7.0
 448  * @remarks It should set when mtpr connection type is \n
 449  *                                      (#MTPR_CONNECTION_TYPE_SRT_SENDER, #MTPR_CONNECTION_TYPE_SRT_RECEIVER, #MTPR_CONNECTION_TYPE_RTSP_SENDER)
 450  * @param[in] mtpr        Media Transporter handle
 451  * @param[in] address     The connection address
 452  * @return @c 0 on success,
 453  *         otherwise a negative error value
 454  * @retval #MTPR_ERROR_NONE    Successful
 455  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 456  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 457  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 458  * @see mtpr_get_connection_address()
 459  */
 460 int mtpr_set_sender_address(mtpr_h mtpr, const char *address);
 461
 462 /**
 463  * @brief Gets the sender address
 464  * @since_tizen 7.0
 465  * @remarks The @a address should be released using free().
 466  * @param[in] mtpr        Media Transporter handle
 467  * @param[out] address    The sender address
 468  * @return @c 0 on success,
 469  *         otherwise a negative error value
 470  * @retval #MTPR_ERROR_NONE    Successful
 471  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 472  * @see mtpr_set_sender_address()
 473  */
 474 int mtpr_get_sender_address(mtpr_h mtpr, char **address);
 475
 476 /**
 477  * @brief Sets the receiver address
 478  * @since_tizen 7.0
 479  * @remarks It should set when mtpr connection type is \n
 480  *                                      (#MTPR_CONNECTION_TYPE_RIST_SENDER, #MTPR_CONNECTION_TYPE_RIST_RECEIVER, #MTPR_CONNECTION_TYPE_RTSP_SENDER_TO_SERVER
 481  * @param[in] mtpr        Media Transporter handle
 482  * @param[in] address     The connection address
 483  * @return @c 0 on success,
 484  *         otherwise a negative error value
 485  * @retval #MTPR_ERROR_NONE    Successful
 486  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 487  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 488  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 489  * @see mtpr_get_receiver_address()
 490  */
 491 int mtpr_set_receiver_address(mtpr_h mtpr, const char *address);
 492
 493 /**
 494  * @brief Gets the receiver address
 495  * @since_tizen 7.0
 496  * @remarks The @a address should be released using free().
 497  * @param[in] mtpr        Media Transporter handle
 498  * @param[out] address    The receiver address
 499  * @return @c 0 on success,
 500  *         otherwise a negative error value
 501  * @retval #MTPR_ERROR_NONE    Successful
 502  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 503  * @see mtpr_set_receiver_address()
 504  */
 505 int mtpr_get_receiver_address(mtpr_h mtpr, char **address);
 506
 507 /**
 508  * @brief Sets connection parameter list.
 509  * @details The parameters are key and value pairs. \n
 510             The key is defined in this header file and the value data type must be string.
 511  * @since_tizen  7.0
 512  * @param[in] mtpr         Media Transporter handle
 513  * @param[in] param_name   connection parameter nam
 514  * @param[in] param_value  connection parameter value
 515  * @return @c 0 on success,
 516  *         otherwise a negative error value
 517  * @retval #MTPR_ERROR_NONE    Successful
 518  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 519  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 520  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 521  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 522  * @see mtpr_set_connection_params()
 523  * @see mtpr_get_connection_params()
 524  * @see #bundle
 525  */
 526 int mtpr_set_connection_param(mtpr_h mtpr, const char *param_name, const char *param_value);
 527
 528 /**
 529  * @brief Sets connection parameter list.
 530  * @details Many connection parameters can be set at one time all together by using bundle. \n
 531             The parameters are key and value pairs. \n
 532             The key is defined in this header file and the value data type must be string.
 533  * @since_tizen  7.0
 534  * @param[in] mtpr         Media Transporter handle
 535  * @param[in] param_list   Key value array of connection parameters
 536  * @return @c 0 on success,
 537  *         otherwise a negative error value
 538  * @retval #MTPR_ERROR_NONE    Successful
 539  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 540  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 541  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 542  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 543  * @see mtpr_get_connection_params()
 544  * @see #bundle
 545  */
 546 int mtpr_set_connection_params(mtpr_h mtpr, bundle *param_list);
 547
 548 /**
 549  * @brief Gets connection parameter list.
 550  * @since_tizen  7.0
 551  * @remarks The @a param_list should be released using bundle_free().\n
 552  * @param[in]  mtpr        Media Transporter handle
 553  * @param[out] param_list  Key value array of connection parameters
 554  * @return @c 0 on success,
 555  *         otherwise a negative error value
 556  * @retval #MTPR_ERROR_NONE    Successful
 557  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 558  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 559  * @see mtpr_set_connection_params()
 560  * @see #bundle
 561  */
 562 int mtpr_get_connection_params(mtpr_h mtpr, bundle **param_list);
 563
 564 /**
 565  * @brief Adds a media source.
 566  * @since_tizen 7.0
 567  * @remarks The camera privilege(%http://tizen.org/privilege/camera) should be added if @a type is #MTPR_MEDIA_SOURCE_TYPE_CAMERA.\n
 568  *          The recorder privilege(%http://tizen.org/privilege/recorder) should be added if @a type is #MTPR_MEDIA_SOURCE_TYPE_MIC.
 569  * @param[in]  mtpr       Media Transporter handle
 570  * @param[in]  mtpr       The media source type to be added
 571  * @param[in]  param_list Key value array of connection/encoding parameters
 572  * @param[out] source_id  The media source id
 573  * @return @c 0 on success,
 574  *         otherwise a negative error value
 575  * @retval #MTPR_ERROR_NONE    Successful
 576  * @retval #MTPR_ERROR_NOT_SUPPORTED Not supported
 577  * @retval #MTPR_ERROR_PERMISSION_DENIED Permission denied
 578  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 579  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 580  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 581  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 582  * @see mtpr_remove_media_source()
 583  * @see mtpr_media_source_set_video_resolution()
 584  * @see mtpr_media_source_get_video_resolution()
 585  * @see mtpr_media_source_set_video_framerate()
 586  * @see mtpr_media_source_get_video_framerate()
 587  */
 588 int mtpr_add_media_source(mtpr_h mtpr, mtpr_source_type_e type, bundle* param_list, unsigned int *source_id);
 589
 590 /**
 591  * @brief Removes the media source.
 592  * @since_tizen 7.0
 593  * @param[in] mtpr        Media Transporter handle
 594  * @param[in] source_id   The media source id to be removed
 595  * @return @c 0 on success,
 596  *         otherwise a negative error value
 597  * @retval #MTPR_ERROR_NONE    Successful
 598  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 599  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 600  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 601  * @pre Add media source to @a mtpr to get @a source_id by calling mtpr_add_media_source().
 602  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 603  * @see mtpr_add_media_source()
 604  */
 605 int mtpr_remove_media_source(mtpr_h mtpr, unsigned int source_id);
 606
 607 /**
 608  * @brief Sets the mic source's sound manager stream information.
 609  * @details If @a source_id is not a media source of #MTPR_SOURCE_TYPE_MIC, this function will return #MTPR_ERROR_INVALID_PARAMETER.
 610  * @since_tizen 7.0
 611  * @remarks You can set sound stream information including audio routing.\n
 612  *          The following sound stream types can be used to create the @a stream_info :\n
 613  *          #SOUND_STREAM_TYPE_MEDIA\n
 614  *          #SOUND_STREAM_TYPE_VOICE_RECOGNITION\n
 615  *          #SOUND_STREAM_TYPE_VOIP\n
 616  *          #SOUND_STREAM_TYPE_MEDIA_EXTERNAL_ONLY\n
 617  *          For more details, please refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE.
 618  * @param[in] mtpr        Media Transporter handle
 619  * @param[in] source_id   The mic source id
 620  * @param[in] stream_info The sound stream information
 621  * @return @c 0 on success, otherwise a negative error value
 622  * @retval #MTPR_ERROR_NONE    Successful
 623  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 624  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 625  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 626  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 627  * @see #sound_stream_info_h
 628  * @see sound_manager_create_stream_information()
 629  * @see sound_manager_destroy_stream_information()
 630  */
 631 int mtpr_mic_source_set_sound_stream_info(mtpr_h mtpr, unsigned int source_id, sound_stream_info_h stream_info);
 632
 633 /**
 634  * @brief Sets a callback function to be invoked when an asynchronous operation error occurs.
 635  * @since_tizen 7.0
 636  * @param[in] mtpr        Media Transporter handle
 637  * @param[in] callback    Callback function pointer
 638  * @param[in] user_data   The user data to be passed to the callback function
 639  * @return @c 0 on success,
 640  *         otherwise a negative error value
 641  * @retval #MTPR_ERROR_NONE    Successful
 642  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 643  * @post mtpr_error_cb() will be invoked.
 644  * @see mtpr_unset_error_cb()
 645  * @see mtpr_error_cb()
 646  */
 647 int mtpr_set_error_cb(mtpr_h mtpr, mtpr_error_cb callback, void *user_data);
 648
 649 /**
 650  * @brief Unsets the error callback function.
 651  * @since_tizen 7.0
 652  * @param[in] mtpr       Media Transporter handle
 653  * @return @c 0 on success,
 654  *         otherwise a negative error value
 655  * @retval #MTPR_ERROR_NONE    Successful
 656  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 657  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 658  * @see mtpr_set_error_cb()
 659  */
 660 int mtpr_unset_error_cb(mtpr_h mtpr);
 661
 662 /**
 663  * @brief Sets a track added callback function to be invoked when a new track is added to the receiver.
 664  * @since_tizen 7.0
 665  * @remarks The registered callback will be invoked in an internal thread of the media transporter.
 666  * @param[in] mtpr        Media Transporter handle
 667  * @param[in] callback    Callback function pointer
 668  * @param[in] user_data   The user data to be passed to the callback function
 669  * @return @c 0 on success,
 670  *         otherwise a negative error value
 671  * @retval #MTPR_ERROR_NONE    Successful
 672  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 673  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 674  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 675  * @post mtpr_track_added_cb() will be invoked.
 676  * @see mtpr_unset_track_added_cb()
 677  * @see mtpr_track_added_cb()
 678  */
 679 int mtpr_set_track_added_cb(mtpr_h mtpr, mtpr_track_added_cb callback, void *user_data);
 680
 681 /**
 682  * @brief Unsets the track added callback function.
 683  * @since_tizen 7.0
 684  * @param[in] mtpr        Media Transporter handle
 685  * @return @c 0 on success,
 686  *         otherwise a negative error value
 687  * @retval #MTPR_ERROR_NONE    Successful
 688  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 689  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 690  * @see mtpr_set_track_added_cb()
 691  */
 692 int mtpr_unset_track_added_cb(mtpr_h mtpr);
 693
 694 /**
 695  * @brief Sets a no more track callback function to be invoked when all the tracks are added to the receiver.
 696  * @since_tizen 7.0
 697  * @remarks The registered callback will be invoked in an internal thread of the media transporter.
 698  * @param[in] mtpr        Media Transporter handle
 699  * @param[in] callback    Callback function pointer
 700  * @param[in] user_data   The user data to be passed to the callback function
 701  * @return @c 0 on success,
 702  *         otherwise a negative error value
 703  * @retval #MTPR_ERROR_NONE    Successful
 704  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 705  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 706  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 707  * @post mtpr_no_more_track_cb() will be invoked.
 708  * @see mtpr_unset_no_more_track_cb()
 709  * @see mtpr_no_more_track_cb()
 710  */
 711 int mtpr_set_no_more_track_cb(mtpr_h mtpr, mtpr_no_more_track_cb callback, void* user_data);
 712
 713 /**
 714  * @brief Unsets the no more track callback function.
 715  * @since_tizen 7.0
 716  * @param[in] mtpr        Media Transporter handle
 717  * @return @c 0 on success,
 718  *         otherwise a negative error value
 719  * @retval #MTPR_ERROR_NONE    Successful
 720  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 721  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 722  * @see mtpr_set_no_more_track_cb()
 723  */
 724 int mtpr_unset_no_more_track_cb(mtpr_h mtpr);
 725
 726 /**
 727  * @brief Sets an encoded audio frame callback function to be invoked when each audio frame is ready to be rendered.
 728  * @since_tizen 7.0
 729  * @remarks If @a callback is set, audio data from the remote peer will be forwarded to @a callback without being rendered by itself.\n
 730  *          The registered callback will be invoked in an internal thread of the media transporter.
 731  * @param[in] mtpr        Media Transporter handle
 732  * @param[in] callback    Callback function pointer
 733  * @param[in] user_data   The user data to be passed to the callback function
 734  * @return @c 0 on success,
 735  *         otherwise a negative error value
 736  * @retval #MTPR_ERROR_NONE    Successful
 737  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 738  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 739  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 740  * @post mtpr_encoded_frame_cb() will be invoked.
 741  * @see mtpr_unset_audio_packet_cb()
 742  * @see mtpr_encoded_frame_cb()
 743  */
 744 int mtpr_set_audio_packet_cb(mtpr_h mtpr, mtpr_encoded_frame_cb callback, void *user_data);
 745
 746 /**
 747  * @brief Unsets the encoded audio frame callback function.
 748  * @since_tizen 7.0
 749  * @param[in] mtpr      Media Transporter handle
 750  * @return @c 0 on success,
 751  *         otherwise a negative error value
 752  * @retval #MTPR_ERROR_NONE    Successful
 753  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 754  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 755  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 756  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 757  * @see mtpr_set_audio_packet_cb()
 758  */
 759 int mtpr_unset_audio_packet_cb(mtpr_h mtpr);
 760
 761 /**
 762  * @brief Sets an encoded video frame callback function to be invoked when each video frame is ready to be rendered.
 763  * @since_tizen 7.0
 764  * @remarks If @a callback is set, video data from the remote peer will be forwarded to @a callback without being rendered by itself.\n
 765  *          The registered callback will be invoked in an internal thread of the media transporter.
 766  * @param[in] mtpr        Media Transporter handle
 767  * @param[in] callback    Callback function pointer
 768  * @param[in] user_data   The user data to be passed to the callback function
 769  * @return @c 0 on success,
 770  *         otherwise a negative error value
 771  * @retval #MTPR_ERROR_NONE    Successful
 772  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 773  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 774  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 775  * @post mtpr_encoded_frame_cb() will be invoked.
 776  * @see mtpr_unset_video_packet_cb()
 777  * @see mtpr_encoded_frame_cb()
 778  */
 779 int mtpr_set_video_packet_cb(mtpr_h mtpr, mtpr_encoded_frame_cb callback, void *user_data);
 780
 781 /**
 782  * @brief Unsets the encoded video frame callback function.
 783  * @since_tizen 7.0
 784  * @param[in] mtpr      Media Transporter handle
 785  * @return @c 0 on success,
 786  *         otherwise a negative error value
 787  * @retval #MTPR_ERROR_NONE    Successful
 788  * @retval #MTPR_ERROR_INVALID_PARAMETER Invalid parameter
 789  * @retval #MTPR_ERROR_INVALID_OPERATION Invalid operation
 790  * @retval #MTPR_ERROR_INVALID_STATE Invalid state
 791  * @pre @a mtpr state must be set to #MTPR_STATE_IDLE.
 792  * @see mtpr_set_video_packet_cb()
 793  */
 794 int mtpr_unset_video_packet_cb(mtpr_h mtpr);
 795
 796 /**
 797  * @}
 798  */
 799
 800 #ifdef __cplusplus
 801 }
 802 #endif /* __cplusplus */
 803
 804 #endif /* __TIZEN_MEDIA_TRANSPORTER_H__ */
 805